DSTU 2 QA guidelines

Draft Quality Criteria for FHIR DSTU 2

These are the guidelines that resources and profiles (both ones included in DSTU 1 as well as new ones) are expected to meet for publication in FHIR DSTU 2. These guidelines have been developed by Modeling & Methodology and FMG & FGB.

Once resources have been developed or updated (to reflect change tracker requests), Work Groups are asked to complete the Google Sheet that can be found here to show that they believe their resource(s) comply with all of the specified criteria. (If you're responsible for maintaining resources and don't have edit access, send a request for edit privileges.)

In a few cases, these guidelines may not make sense for a particular resource (e.g. documenting multiple contexts for MessageHeader). If you don't think a "should" rule applies to your resource, mark it as NA in the spreadsheet and/or suppress the warnings in the build process. FMG will review these decisions and confirm whether a rule should be considered inapplicable.

If a work group is struggling to meet a criterion (e.g. need expertise not found in the WG), they should contact their FMG liaison who will do their best to find necessary help.

These criteria cover both resources and profiles (including profiles that only define "standard" extensions)

1. Introduction

• a. Resource introductions should identify a broad set of example contexts in which the resource might be used. (Should be minimum of 3 , as many as 8-10).
• b. Resource introductions must clearly differentiate the resource from any similar resources where an implementer might wonder "which of these should I use in my scenario?"
• c. Where implementers might be tempted to use a resource inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this resource for x)

2. Examples

• a. Examples should exist for every example context identified in the resource introduction and must, between them, show the use of every data element in the resource definition. Examples should include a mixture of "simple" and fully fleshed out "complex" scenarios. (Expect 5-10 examples/resource)
• b. Examples should be valid and reasonable from a clinical/business perspective and include comments explaining what they are representing where this is not obvious from the instance
• c. Where extensions appear in examples, those extensions should either be defined within published profiles (and point to those profiles by a valid URL) or should clearly be example extensions (using the prefix http://example.org/fhir/Profile)

3. Mappings

• a. Work group (or modeling representatives from it) must review the RIM mappings and verify they are correct and aligned with definitions
• b. Mappings should be provided to a minimum of 1 and ideally at least 2 or 3 broadly implemented specifications in the space covered by the resource (HL7 or non-HL7 – e.g. v2, CCDA, NCPDP, X12, ISO, etc.) where there is prior implementation experience

4. Value sets

• a. Coded values should draw from external code systems as much as possible. If defining a CodeableConcept, FHIR-specific codes must only be used when no external code systems apply (and should be verified for 80% if this occurs).
  • Preference is to use international code systems (SNOMED, LOINC, UCUM, ICD, etc.) where possible and where content is appropriate.
  • Existing HL7-maintained code systems (v2, v3) may be used if clearly superior to other international code systems after consulting HL7's Terminology Authority to confirm there are no plans to move these to an external code system (e.g. SNOMED, LOINC)
  • National or HL7 code systems may be used when international codes don't apply/exist (e.g. manufactured drug codes). When using national code systems, draw from different countries (i.e. not just U.S.)
  • If no appropriate external code exists for a CodeableConcept, look to the HL7 Terminology Authority to define one before considering defining one in FHIR.
  • For "code" elements, terminology should be HL7-controlled - either FHIR-specific or leveraging existing v2/v3 code systems
  • "code" elements should have human-readable codes
• b. Value set bindings should be "representative" (type=incomplete) whenever possible. I.e. The value set should be useable in production systems, at least as a reasonable starting point. (Though in some cases, might be limited to a specific country.)
• c. Where FHIR defines its own codes, every code must have a formal definition that follows best practices (i.e. isn't tautological)
• d. Ensure the "code" data type is only used for "structural" elements or where it's reasonable to expect all implementations to use (or map to) a single value set. (Check with FMG if you're not sure.) Coding should only be used if the work group is confident that translations (and transitions) to other code systems will not be relevant for the element. I.e. CodeableConcept is the default.
• e. If constraining to the "code" data type, ensure that the set of available codes will be sufficient in all possible business scenarios (including "unknown" and possibly "other" situations), particularly if the element is minOccurs = 1. Also ensure all codes are mutually exclusive or are defined in a proper hierarchy where siblings are mutually exclusive

5. Elements

• a. Elements with a type of Resource Reference should be reviewed such that a given relationship shall only be represented in one resource, not both (and should generally be present on the resource that is normally created second – e.g. Procedure is usually created after Encounter, so reference would live on Procedure)
• b. When a resource needs to refer to elements that could be modeled by referencing another resource, that is the preferred mechanism. However, content may be handled inline (as nested elements rather than by reference) if it is expected that less that 20% of existing systems would be capable of managing the content as a discrete resource.
• c. Ensure all elements (and only those elements) that could change the interpretation of other data are marked as "isModifier"
• d. Ensure resource identifies "summary" data elements and only includes those elements necessary for a summary "low bandwidth" list-type view of a resource

6. Elements & search criterion items

• a. Names of elements & search criteria for resources should be consistent across FHIR, particularly within the same "family" (e.g. medications, interventions, orders, etc.), unless business convention dictates otherwise.
• b. Data elements & search criteria within the same "family" should be ordered in the same way (particularly within the same "family"). Data elements should in general be ordered in a "sensible" way – related elements together, more important elements towards the top, "big" elements (those that take a lot of space in instances) towards the bottom.

7. Definitions

• a. Review and resolve all "todos" in the specification
• b. All data elements must have definitions that follow best practices:
  • It must be non-tautological (can't use the name of the element in the definition)
  • The first sentence (the main ‘definition') should be substitutable for the element name in a sentence
  • It should include examples unless the data type makes examples meaningless (e.g. no need for example integers or dates) or there is a vocabulary binding
  • It should provide additional guidance beyond the name and short description)
  • Definitions should not document constraints that can be conveyed by invariants . I.e. If you can use an xpath to enforce a constraint, use the invariant mechanism.
• c. Where not obvious even to those with little industry experience , rationale should be provided for each element indicating why it is necessary/appropriate
• d. The Committee notes column for the resource should identify all points of contention/controversy that have been resolved over the course of development (what elements got dropped & why, choice of repeating/non-repeating, choice of optionality, etc.)

8. Constraints

• a. Constraints and minimum repetitions must not prevent "narrative only" resources and must allow for broad use of the resource (summary and anonymized reporting, scenarios of partial availability, etc.). MinOccurs=1 should only occur when the work group is certain that there are no known use-cases where a system might need to communicate when the value could potentially be unknown or unavailable. This will tend to be for "structural" elements.
• b. Ensure that constraints (minOccurs, formalConstraints) are ones that can be reasonably met across all possible resource usages (partial data, summary reporting, etc.) and, if not, make them conditional on some other element.

9. Search

• a. Ensure that appropriate search criteria are defined for the 80% (i.e. everything that most systems would use, but not more)
• b. Search descriptions should provide guidance or examples on how they could be used in addition to what they're searching – i.e. how is this search parameter useful?