FHIR Conformance QA Criteria

Content on this page has been migrated to Confluence here: https://confluence.hl7.org/display/FHIR/Conformance+QA+Criteria

These are the criteria that apply to the different types of FHIR artifacts (i.e. instances of one of the FHIR Conformance resources) in order for them to be eligible for FMM level 3. These are binding on all artifacts published by HL7 International and are intended to apply to artifacts created by other projects (as part of implementation guides, profiles, etc.) These criteria are based on the previous resource quality criteria found here: DSTU_QA_Guidelines which are replaced by this page.

Compliance with these criteria is tracked here: FHIR QA Conformance Tracker

StructureDefinition - Resource definition

FHIR QA Conformance Tracker - Resource

1. Introduction

a. Contexts identified: 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. Differentiated from peers: 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. Non-examples provided: 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)

d. TOOL? Specify entered-in-error: Resource should have an definition for 'entered in error' status (see lifecycle.html#error)

2. Examples

a. Examples are comprehensive: 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 ok for clinical/business w/ comments: 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. TOOL? Extensions have valid/example URLs: 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/StructureDefinition)

3. Mappings

a. RIM mappings ok: Work group (or modeling representatives from it) must review the RIM mappings and verify they are correct and aligned with definitions. (See FHIR Guide to Designing Resources for guidance)

b. External mappings provided: 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. Use correct code systems: 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. These should be Preferred bindings - i.e. Appropriate and recommended for use.
• 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). These would also typically be Preferred bindings
• National 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.). National code systems can only be bound with type=Example, never with type=Preferred.
• If no appropriate external code exists for a CodeableConcept, look to the HL7 Terminology Authority to define one before considering defining one in FHIR. These would generally be type=Preferred bindings. (If you're not creating a "recommended" value set, it may be better to not create a value set at all.)
• 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. Representative where possible: Value set bindings should be "Representative" 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. code data type appropriate: 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.

d. Codes cover space, don't overlap: 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. References point right way: 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. Inline vs. Reference ok: 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. isModifier ok: Ensure all elements (and only those elements) that could change the interpretation of other data are marked as "isModifier"

d. summary ok: Ensure resource identifies "summary" data elements and only includes those elements necessary for a summary "low bandwidth" list-type view of a resource

e. W5 column ok: The W5 column must be filled in with all matching elements. w5 elements not present in the resource should be evaluated as to whether they make sense for the resource and fall within the 80%. (See w5 page for details.

f. Workflow column ok: The workflow mapping column is filled in for all matching elements if the resource is based on 'Act' or one of its specializations in the RIM mapping. Workflow template elements not present in the resource should be evaluated as to whether they make sense for the resource and fall within the 80%.

h. No use of prohibited elements: MnM approval should be sought before populating the "StructureDefinition.description", "identifier", "version", "code" or "snapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)

6. Elements & search criterion items

a. Names appropriately consistent: Names of elements & search criteria for resources should be consistent across FHIR, particularly within the same "family" (e.g. medications, interventions, orders, w5 report equivalents, etc.), unless business convention dictates otherwise.

b. Elements sorted ok: Data elements & search criteria should be ordered in the same way across resources (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. W5 elements must appear in the order defined unless there are strong business reasons for a different order (raise with MnM to get permission to override the sort rule for a given resource). Note that items related to W5 items can still be inter-mixed with W5 items.

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: All data elements must have definitions that follow best practices:

• 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.
• Definitions should use singular words for the element (e.g. "An observation related to this observation" not "Observations related to this observation")

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for each element indicating why it is necessary/appropriate

d. Committee notes filled in: 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. Narrative-only allowed: 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. Not over-restrictive: 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.

c. Profiles on types approved: Profiles on element types, if present, must be HL7 International defined profiles and their use requires MnM approval

9. Search

a. Criteria meet 80%: Ensure that appropriate search criteria are defined for the 80% (i.e. everything that most systems would use, but not more)

b. Descriptions complete: 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?

StructureDefinition - Data type definition

FHIR QA Conformance Tracker - Data Type

1. Introduction

a. Scope identified: Data type introductions should identify the set of circumstances in which the data type is intended to be used.

b. Differentiated from peers: Data type introductions must clearly differentiate the resource from any data types where a designer might wonder "which of these should I use in my scenario?"

c. Non-examples provided: Where implementers might be tempted to use a data type inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this resource for x)

2. Examples

a. Examples are comprehensive: Examples should exist for every intended use identified in the data type introduction and must, between them, show the use of every data element in the data type definition. Examples should include a mixture of "simple" and fully fleshed out "complex" scenarios. (Expect 5-10 examples for 'complex' data types. One example is sufficient for simple data types)

b. Examples ok for clinical/business w/ comments: 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. TOOL? Extensions have valid/example URLs: 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/StructureDefinition)

3. Mappings

a. RIM mappings ok: Work group (or modeling representatives from it) must review the RIM mappings and verify they are correct and aligned with definitions. (See FHIR Guide to Designing Resources for guidance)

b. External mappings provided: 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. Use correct code systems: 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). See Resource criteria for details

b. Representative where possible: Value set bindings should be "Representative" 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. code data type appropriate: 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.

d. Codes cover space, don't overlap: 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. References point right way: 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. Inline vs. Reference ok: 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. isModifier ok: Ensure all elements (and only those elements) that could change the interpretation of other data are marked as "isModifier"

d. summary ok: Ensure resource identifies "summary" data elements and only includes those elements necessary for a summary "low bandwidth" list-type view of a resource

h. No use of prohibited elements: MnM approval should be sought before populating the "StructureDefinition.description", "identifier", "version", "code" or "snapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)

6. Elements & search criterion items

a. Names appropriately consistent: Names of elements for data types should be consistent across FHIR, particularly within the same "family" (e.g. codes & identifiers, demographics, etc.), unless business convention dictates otherwise.

b. Elements sorted ok: Data elements & search criteria should be ordered in the same way across resources (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. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: All data elements must have definitions that follow best practices. See Resource criteria for details.

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for each element indicating why it is necessary/appropriate

d. Committee notes filled in: 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. Narrative-only allowed: Constraints and minimum repetitions must not prevent "narrative only" instances 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. Not over-restrictive: 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.

c. Profiles on types approved: Profiles on element types, if present, must be HL7 International defined profiles and their use requires MnM approval

StructureDefinition - Constraint / Profile

FHIR QA Conformance Tracker - Constraint / Profile

1. Introduction

a. Contexts identified: Profile introductions should identify the set of example contexts in which the profile might be used. (May be as few as 1, but can be multiple.)

b. Differentiated from peers: Profile introductions must clearly differentiate the profile from any similar profiles where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of artifacts produced by the same organization. E.g. HL7 International

c. Non-examples provided: Where implementers might be tempted to use a profile inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this profile for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Profile must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

h. Description present: Must have StructureDefinition.description which provides an overview of the purpose of this particular profile

2. Examples

a. Examples are comprehensive: Examples should exist for every example context identified in the profile introduction and must, between them, show the use of every data element in the profile definition. (This can be limited to 'mustSupport' elements for profiles that set this property.) Examples should include a mixture of "simple" and fully fleshed out "complex" scenarios. (Expect 2-5 examples/profile)

b. Examples ok for clinical/business w/ comments: 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. TOOL? Extensions have valid/example URLs: 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/StructureDefinition)

3. Mappings

a. RIM mappings ok: Work group(or modeling representatives from it) must review the RIM mappings and verify they are correct and aligned with definitions. Mappings will be imported from base resource but may be overridden to reflect the tighter semantics of the profile. (See FHIR Guide to Designing Resources for guidance)

b. External mappings provided: 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. Use correct code systems: Coded values should draw from external code systems as much as possible. (See resource criteria for guidance on code system selection.) 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).

b. Representative where possible: Value set bindings should be "Representative" 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.) Use "Required" or "Extensible" only where there's certainty that the codes will be useful across all countries and scopes, or where the profile is explicitly defined as realm-specific.

e. Names computable: Slice names and re-useable type names should be software-friendly: UpperCamelCase alpha-numeric, starting with an alpha

f. No prohibited elements: MnM approval should be sought before populating the "identifier", "version", "code" or "snapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)

5. Elements

i. Slicing Description present: If slicing is present, description must be present.

g. Slice names computable: Slice names should be software-friendly: UpperCamelCase alpha-numeric, starting with an alpha

j. Discriminator for slices: If slicing is present, MnM approval must be sought if discriminator is not specified

k. Type profiles are HL7 defined: Profiles on element types, if present, must be HL7 International defined profiles

6. Elements & search criterion items

a. TOOL? Slice names must be UpperCamelCase alphanumeric. Slice names should be consistent within a profile and within families of related profiles (same IG, same domain)

b. Extensions sorted ok: Extensions should be ordered in the same way across profiles (particularly within the same "family"). Extensions 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. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: All overrides to definitions must follow definition best practices (see Resource criteria)

c. Rationale provided where needed: Where the reason for constraints would not be obvious even to those with little industry experience, rationale should be adjusted to include the reason for profile-specific constraints

d. Committee notes filled in: The Committee notes column for the profile should identify all points of contention/controversy that have been resolved over the course of development (what elements were marked as mustSupport & why, constraints on choice elements, cardinality, etc.)

8. Constraints

a. Narrative-only allowed?: Evaluate whether the use-case served by the profile should support narrative-only instances and, if so, ensure that constraints and minimum repetitions do not prevent "narrative only" instances. MinOccurs=1 should only occur when the work group is certain that there are no known use-cases in the profile context(s) where a system might need to communicate when the value could potentially be unknown or unavailable.

b. Not over-restrictive: Ensure that constraints (minOccurs, formalConstraints) are ones that can be reasonably met across all intended profile usages (partial data, summary reporting, etc.) and, if not, make them conditional on some other element.

StructureDefinition - Extension definition

FHIR QA Conformance Tracker - Extension

1. Introduction

a. Contexts identified: Extension introductions should identify the set of example contexts in which the extension might be used. (May be as few as 1, but can be multiple.)

b. Differentiated from peers: Extension introductions must clearly differentiate the extension from any similar extensions where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of artifacts produced by the same organization. E.g. HL7 International

c. Non-examples provided: Where implementers might be tempted to use an extension inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this extension for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Extensions that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

h. Description blank: Seek MnM approval before specifying any content for StructureDefinition.description

i. No overlap: Extension definitions should not overlap in purpose/meaning with other extensions (even if defined in other HL7 International maintained implementation guides) or with core elements that are found on the resource or data type element to be extended. Extensions that convey meaning that can be conveyed by chaining to elements found in other resources should be used with caution. (E.g. A data enterer extension isn't explicitly prohibited, but strong consideration should be given to using Provenance before adding an extension.)

j. Display present: Display should be present if the name is made up of multiple words or would otherwise be inappropriate to use as the user interface display term for the extension

2. Examples

a. Examples are comprehensive: Examples should exist for every example context identified in the extension introduction and must, between them, show the use of every data element in the extension definition. Examples should include a mixture of "simple" and fully fleshed out "complex" scenarios. (Should have at least 1 example for non-trivial extensions – i.e. not for dates, numbers, etc. Complex multi-element extensions, strings or unbound coded elements should show how the extension might be used. Can be covered by an example instance using a containing resource instance.)

b. Examples ok for clinical/business w/ comments: 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.

3. Mappings

a. RIM mappings ok: Work group (or modeling representatives from it) must review the RIM mappings and verify they are correct and aligned with definitions. HL7 International defined extensions must include RIM mappings or must explicitly declare they are not RIM mappable. (See FHIR Guide to Designing Resources for guidance)

b. External mappings provided: 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. Use correct code systems: Coded values should draw from external code systems as much as possible. (See resource criteria for guidance on code system selection.) 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).

b. Representative where possible: Value set bindings should be "Representative" 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.) Use "Required" or "Extensible" only where there's certainty that the codes will be useful across all countries and scopes, or where the profile is explicitly defined as realm-specific.

c. code data type appropriate: 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.

d. Codes cover space, don't overlap: 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

f. No prohibited elements: MnM approval should be sought before populating the "identifier", "version", "code" or "snapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)

5. Elements

a. References point right way: 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). Should avoid defining extensions that could result in bi-directional associations. If necessary, ensure that implementation notes are included that warn of the risks of actually using bi-directional links between two instances.

c. isModifier ok: Ensure all elements (and only those elements) that could change the interpretation of other data are marked as "isModifier". If an extension can change the meaning of other elements, make sure it's marked as a modifier and make sure it's defined as appearing as a child of the deepest element that contains all elements modified by the extension.

g. Element names computable: Element names (for type references or slicing) should be software-friendly: UpperCamelCase alpha-numeric, starting with an alpha

m. Root element cardinality: MnM approval should be sought before defining extensions whose root element has a minimum cardinality of "1"

6. Elements & search criterion items

a. Names appropriately consistent: Names of elements & search criteria for extensions should be consistent across FHIR, particularly within the same "family" (e.g. medications, interventions, orders, w5 report equivalents, etc.), unless business convention dictates otherwise. Extensions must be lower-camel-case alphanumeric only.

• ??? TODO - See with more experience whether any naming consistency or notions of "families" arises, but no QA criteria as yet. At minimum, enforce consistent naming in terms of the use of camel-case vs. dashes vs. all lower case. Extensions must be lower-camel-case alphanumeric only, search parameter names must be all lower case alphanumeric only. Enforce a "banned" list of reserved words for Java, C#, SQL, Javascript & Delphi (tracker 13880 added for Grahame).

b. Elements sorted ok: For complex extensions, data elements & search criteria should be ordered in the same way across extensions/resources (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. W5 elements must appear in the order defined unless there are strong business reasons for a different order (raise with MnM to get permission to override the sort rule for a given resource). Note that items related to W5 items can still be inter-mixed with W5 items.

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: All data elements must have definitions that follow best practices (see Resource criteria)

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for each element indicating why it is necessary/appropriate

d. Committee notes filled in: The Committee notes column for the extension 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. Narrative-only allowed: 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. Not over-restrictive: 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.

c. Profiles on types approved: Profiles on element types, if present, must be HL7 International defined profiles and their use requires MnM approval

d. mustSupport not declared: mustSupport must not be declared on HL7 International defined extension definitions (declare it on the profiles where the extension is invoked)

9. Search

a. Criteria meet 80%: A corresponding search criteria should exist for the extension if it's reasonable for systems to want to search on it (within the 80%).

b. Descriptions complete: 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?

StructureDefinition - Logical Model

FHIR QA Conformance Tracker - Logical Model

1. Introduction

a. Contexts identified: Logical Model introductions should identify a broad set of example contexts in which the pattern represented by the logical model might apply.

b. Differentiated from peers: Logical Model introductions must clearly differentiate the resource from any similar logical models where a designer might wonder "which of these should I use in my scenario?"

c. Non-examples provided: Where designers might be tempted to use a logical model inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this logical model for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Profile must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

3. Mappings

a. RIM mappings ok: Work group (or modeling representatives from it) must review the RIM mappings and verify they are correct and aligned with definitions. (Only applies to logical models that can be expressed as RIM) (See FHIR Guide to Designing Resources for guidance)

b. External mappings provided: Mappings should be provided, if appropriate, to other broadly implemented specifications in the space covered by the logical model (HL7 or non-HL7 – e.g. v2, CCDA, NCPDP, X12, ISO, etc.) where there is prior implementation experience

4. Value sets

a. Use correct code systems: 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). See Resource criteria for details.

b. Representative where possible: Value set bindings should be "Representative" 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. code data type appropriate: 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.

d. Codes cover space, don't overlap: 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. References point right way: Elements with a type of Resource Reference should be reviewed such that a given relationship shall only be represented in one logical model, 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. Inline vs. Reference ok: 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. isModifier ok: Ensure all elements (and only those elements) that could change the interpretation of other data are marked as "isModifier"

d. summary ok: Ensure resource identifies "summary" data elements and only includes those elements necessary for a summary "low bandwidth" list-type view of a resource

h. No use of prohibited elements: MnM approval should be sought before populating the "StructureDefinition.description", "identifier", "version", "code" or "snapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)

6. Elements & search criterion items

a. Names appropriately consistent: Names of elements & search criteria for logical models should be consistent across FHIR, particularly within the same "family", unless business convention dictates otherwise.

b. Elements sorted ok: Data elements & search criteria should be ordered in the same way across resources (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. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: All data elements must have definitions that follow best practices. See Resource criteria for details

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for each element indicating why it is necessary/appropriate

d. Committee notes filled in: 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. Narrative-only allowed: Constraints and minimum repetitions must not prevent "narrative only" instances and must allow for broad use of the pattern (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. Not over-restrictive: Ensure that constraints (minOccurs, formalConstraints) are ones that can be reasonably met across all possible pattern usages (partial data, summary reporting, etc.) and, if not, make them conditional on some other element.

c. Profiles on types approved: Profiles on element types, if present, must be HL7 International defined profiles and their use requires MnM approval

9. Search

a. Criteria meet 80%: Ensure that appropriate search criteria are defined for the 80% (i.e. everything that most systems would use, but not more)

b. Descriptions complete: 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?

StructureMap

FHIR QA Conformance Tracker - StructureMap

1. Introduction

a. Contexts identified: Must define the single context in which the mapping is intended to apply

b. Differentiated from peers: If there's more than one in the same space, structure map introductions must clearly differentiate the map from any similar maps where an implementer might wonder "which of these should I use in my scenario?"

c. Non-examples provided: Where implementers might be tempted to use a structure map inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this resource for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Structure maps must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

2. Examples

a. Examples are comprehensive: Implementation Guides containing structure maps should include sample instances showing source and product when applying the structure map.

5. Elements

n. Imported StructureMaps are HL7 defined: FMG approval is required for an HL7 defined structure map to import other structure maps that are not HL7 defined

6. Elements & search criterion items

a. Names appropriately consistent: Structure maps should be named consistently within an IG and across similar/related IGs and within domains

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for each element indicating why it is necessary/appropriate. (Must populate the "requirements" element explaining why the structure map is needed and what its purpose is)

d. Committee notes filled in: 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.)

Terminology - CodeSystem

FHIR QA Conformance Tracker - CodeSystem

1. Introduction

a. Contexts identified: Code system introductions should identify the set of example contexts in which the code system might be used. (May be as few as 1, but can be multiple.)

b. Differentiated from peers: Code system introductions must clearly differentiate the code system from any similar code systems where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of HL7 International defined artifacts.

c. Non-examples provided: Where implementers might be tempted to use a code system inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this code system for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Code systems that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

3. Mappings

a. RIM mappings ok: Expect mappings to HL7 v3 vocabularies for FHIR defined code systems where such mappings exist

b. External mappings provided: FHIR defined code systems should try to map to 1-3 other "common" code systems where such mappings exist and would be of value to implementers (e.g. v2, CDA, ISO 21090, etc.)

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: (Will use Vocab's rules for good practices, including non-tautological)

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for the code set indicating why it is necessary/appropriate (Must populate the "requirements" element explaining why the code system is needed and why it's structured as it is)

d. Committee notes filled in: The Committee notes column for the code system 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.)

e. Name appropriately consistent: Code system names within the same "families" should be labeled in a consistent fashion. Names should reflect the scope of intended use of the code system.

10. Codes

a. Codes sorted ok: For large code systems (>~10 codes), codes should be listed in alphabetic order by code within hierarchy. For smaller code systems, concepts may be listed in "intuitive"/related order. For codes having ordinal relationships, list by either increasing or decreasing ordinal value.

b. Display and Description present: All codes must have both display names and definitions

c. Property Names computable: Property names must be lowerCamelCase alpha-numeric

d. Property Description present: Properties must have meaningful/useful descriptions

e. Filter Description present: Filters must have descriptions explaining what the formal representation is doing

f. Designations present: If designations with a particular use/language are present on some codes, such designations must be present on all codes

g. Meaningful values: FHIR defined code systems must have "meaningful" code values, expressed in US-English

h. Content complete: FHIR defined code systems cannot set compositional or versionNeeded to true and must set content=complete

i. Case sensitive: HL7 defined code systems must be case sensitive

j. Non-HL7 code systems: For non-HL7 maintained code systems, FMG approval must be sought before allowing a content value other than "not-present"

Terminology - ValueSet

FHIR QA Conformance Tracker - ValueSet

1. Introduction

a. Contexts identified: Value set introductions should identify the set of example contexts in which the value set might be used. (May be as few as 1, but can be multiple.)

b. Differentiated from peers: Value set introductions must clearly differentiate the value set from any similar value sets where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of HL7 International defined artifacts.

c. Non-examples provided: Where implementers might be tempted to use a value set inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this value set for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Value sets that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

c. Rationale provided where needed: Must populate the "requirements" element explaining why the value set is needed and why it's structured as it is, draws from the terminology it does

10. Codes

a. Name appropriately consistent: Value set names within the same "families" should be labeled in a consistent fashion. Names should reflect the scope of intended use of the value set.

b. Codes sorted ok: For large enumerated value sets (>~10 codes), codes should be listed in alphabetic order by code within hierarchy. For smaller value sets, concepts may be listed in "intuitive"/related order. For codes having ordinal relationships, list by either increasing or decreasing ordinal value.

k. Mutable approved: Value sets marked as immutable must have the use of isImmutable approved by the vocabulary work group

Terminology - ConceptMap

FHIR QA Conformance Tracker - ConceptMap

1. Introduction

c. Non-examples provided: Where implementers might be tempted to use a concept set inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this value set for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Concept maps that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

h. Description present: Concept map description should indicate whether the mapping is complete from a source and target perspective, and if incomplete, roughly what the coverage gaps are

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

c. Rationale provided where needed: Must populate the "requirements" element explaining why the concept map is needed and what its purpose is

e. Name appropriately consistent: Human-readable names should identify the two artifacts mapped and the primary scope/purpose of the mapping.

• ??? TODO Will also explore the need for computable names here.

f. Description complete: Description should provide an explanation of how "dependsOn" and "product" are used in the context of the mapping

10. Codes

a. Codes sorted ok: Mappings should be listed based on order of source concept, then target concept, the same as the codes/structure elements appear in their source systems.

l. Codes are version specific: Source and target should be version-specific

m. Codes exist in value set: Source, target and OtherElement concepts must exist in their respective value set versions

• ??? TODO (automate)

Terminology - NamingSystem

1. Introduction

a. Contexts identified: Naming system introductions should identify the set of example contexts in which the naming system might be used (May be as few as 1, but can be multiple)

b. Differentiated from peers: If there's more than one in the same space, naming system introductions must clearly differentiate the system from any similar systems where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of HL7 International defined artifacts.

c. Non-examples provided: Where implementers might be tempted to use a value set inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this value set for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Naming systems that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

3. Mappings

b. External mappings provided: Provide all other known "identifiers" for the naming system - OIDs, v2 code system labels or identifier types (where 1..1 with the system), etc.

5. Elements

o. Rendering guidance: Include "usage" about how the identifier or code should be rendered (e.g. case sensitive, always upper case, remove whitespace or dashes, retain leading zeros, etc.) whenever there are usage constraints

p. Meaningful URL: For HL7 defined naming systems, always use a meaningful URL, not an OID-based urn

q. Appropirate URLs: All naming systems should include at least a URL for FHIR and, where one exists, the corresponding OID, both marked as primary

r. Responsible complete: Try to be consistent in populating "responsible" when the same agency is responsible for multiple identifier or code system types

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

e. Name appropriately consistent: Should be consistent with names of other artifacts of the same type. E.g. Avoid "Florida Drivers License" for one naming system and "Drivers License - Ohio" for another.

f. Descriptions complete: Do not use abbreviations for organizations in descriptions

Behavior - ImplementationGuide

FHIR QA Conformance Tracker - ImplementationGuide

1. Introduction

a. Context identified: Implementation guide introductions should identify the context in which the implementation guide is to be used

b. Differentiated from peers: If there's more than one in the same space, implmentation guide introductions must clearly differentiate the implementation guide from any similar implementation guides where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of HL7 International defined artifacts.

c. Non-examples provided: Where implementers might be tempted to use an implementation guide inappropriately, work groups should explicitly document "non-examples" (i.e. don't use this implementation guide for x)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Implementation guides that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

6. Elements & search criterion items

a. Names appropriately consistent: Must adhere to naming guidelines for HL7 specifications as published by TSC.

b. Elements sorted ok: ??

• ??? TODO Will have separate guidance around implementation guide sections & ordering

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

c. Rationale provided where needed: Should have a "page" or section that describes why the implementation guide is needed and how/where it's intended to be used - e.g. use cases, storyboards, etc.

d. Committee notes filled in: Implementation guides should have a non-published text document that identifies any issues/controversial areas that came up during design and how they were resolved. (Not necessary to document discussion already present in tracker items)

g. IG table of contents: Should start with a table of contents consisting of links that include, in most cases:

• Overview
• Purpose/Use cases
• Conformance expectations & naming conventions
• Security & General conformance rules
• List of used Profiles
• List of defined extensions
• List of used value sets
• List of defined system roles (Conformance instances)
• Credits & contact information

h. Navigation links: All pages within the implementation guide should include links at the top and bottom that allow returning to the implementation guide "home page" and should make it clear which implementation guide a page belongs to.

Behavior - CapabilityStatement

FHIR QA Conformance Tracker - CapabilityStatement

1. Introduction

a. Contexts identified: Capability statement introductions should identify the set of example contexts in which the capability statement might be used (Could be just one)

b. Differentiated from peers: If not implementation specific, capability statement introductions must clearly differentiate the resource from any similar resources where an implementer might wonder "which of these should I use in my scenario?"

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Implementaiton guides that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

5. Elements

t. Software and Implementation not present: "software" and "implementation" must not be present for capability statement instances intended to define system behavior as part of an implementation guide

6. Elements & search criterion items

a. Names appropriately consistent: Capability statement resources should be named consistently within an implementation guide and across similar/related implementation guides and within domains

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for each element indicating why it is necessary/appropriate (Must populate the "requirements" element explaining why the capability statement instance is needed and what its purpose is)

d. Committee notes filled in: 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.)

Behavior - OperationDefinition

FHIR QA Conformance Tracker - OperationDefinition

1. Introduction

a. Contexts identified: Operation definition introductions should identify the set of example contexts in which the operation definition might be used (May be as few as 1, but can be multiple)

b. Differentiated from peers: Operation definition introductions must clearly differentiate the operation from any similar operations where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of HL7 International defined artifacts.

c. Non-examples provided: 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)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Operation definitions that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

2. Examples

a. Examples are comprehensive: 1 or more examples showing invocation & response. Examples should cover major expected parameter combinations. Every parameter should be covered at least once

b. Examples ok for clinical/business w/ comments: 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.

6. Elements & search criterion items

a. Names appropriately consistent: code must be lowerCamelCase alphanumeric avoiding reserved words. Operations must be unique within HL7 International defined OperationDefinitions taking into account the different contexts in which the operations can be invoked. Operations should be named consistently within resources and across families of resources, within Implementation Guides, etc.

b. Parameters sorted ok: Parameters should be grouped such that "related" parameters appear together and "more important" or required parameters appear before less important/optional parameters. All other things being equal, use alphabetic order.

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: All operation definitions must have definitions that follow best practices:

• 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
• Definitions should use singular words for the element (e.g. "An observation related to this observation" not "Observations related to this observation")

c. Rationale provided where needed: Where not obvious even to those with little industry experience, rationale should be provided for each operation indicating why it is necessary/appropriate (Must populate the "requirements" element explaining why the operation is needed and what its purpose is)

d. Committee notes filled in: 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

b. Not over-restrictive: If we add invariants, 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.

11. Operations

a. Names appropriately consistent: Names of operations should be unique within HL7 and sufficiently descriptive to differentiate and understand the purpose when looking at a list of operations available

b. Operation invocations ok: Allow operations to be invoked in the context of a specific resource as well as by passing in a reference to the resource. Where appropriate, also allow invocation by business identifier

c. Parameters appropriately consistent: Align parameter name and usage (including data type) with other operations defined by HL7, particularly for similar "types" of operations or operations intended to be invoked with the same context

d. Parameters within 80%: Adhere to 80% principles when deciding what parameters should be present, what data types and cardinalities to support, etc.

e. Parameters documented: Every parameter must have documentation explaining what the parameter does - this must be more than just a repetition of the name

Behavior - SearchParameter

FHIR QA Conformance Tracker - SearchParameter

1. Introduction

a. Contexts identified: Search parameter introductions should identify the set of example contexts in which the search parameter might be used (May be as few as 1, but can be multiple)

b. Differentiated from peers: Search parameter introductions must clearly differentiate the search parameter from any similar search parameters where an implementer might wonder "which of these should I use in my scenario?" This differentiation only needs to be done in the context of HL7 International defined artifacts.

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

f. Jurisdiction declared: Search parameters that are not "global" in scope must declare the jurisdiction(s) for which it was designed. (Use the code for International if not jurisdiction-specific). As well context should be declared where appropriate (e.g. oncology, veterinary, etc.)

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

2. Examples

a. Examples are comprehensive: At least one - show in combination with other parameters with an explanation of intent of the search. I.e. how might this parameter be used to solve real use-cases.

b. Examples ok for clinical/business w/ comments: 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.

5. Elements

u. expression present: "expression" must be present

• ??? TODO (tracker 13885 created to automate this)

6. Elements & search criterion items

a. Names appropriately consistent: Code must be all lowercase alphanumeric avoiding reserved words. Both code and name must be unique across all SearchParameters defined by HL7 International for the resource they apply to. Names and codes should be consistent within the resource and across families

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

b. Best practice definitions: All search parameters must have definitions that follow best practices:

• The first sentence (the main ‘definition') should be substitutable for the element name in a sentence
• It should include examples of use (why/how would you use the parameter)
• It should provide additional guidance beyond the name
• Definitions should use singular words for the element (e.g. "An observation related to this observation" not "Observations related to this observation")

c. Rationale provided where needed: Where not obvious even to non-domain experts, should populate the "requirements" element explaining why the search criteria is needed and what its purpose is

Behavior - MessageDefinition

FHIR QA Conformance Tracker - MessageDefinition

• TODO - waiting for more experience with these artifacts (and for the resource to no longer be draft) before attempting to define quality criteria

Behavior - CompartmentDefinition

FHIR QA Conformance Tracker - CompartmentDefinition

• TODO

Behavior - GraphDefinition

FHIR QA Conformance Tracker - GraphDefinition

• TODO - waiting for more experience with these artifacts (and for the resource to no longer be draft) before attempting to define quality criteria

Testing - TestScript

FHIR QA Conformance Tracker - TestScript

1. Introduction

a. Contexts identified: Test script introductions should identify the set of example contexts in which the test script might be used (Could be just one)

e. Publisher/contact included: Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact

g. Copyright ok: For HL7 International defined artifacts, copyright should be left unspecified (and will default to the standard FHIR license). If alternate licensing arrangements are desired, FMG approval is required

5. Elements

v. Metadata present: Metadata must be present for all systems involved in the test case

w. Metadata links present: Include metadata links to relevant portions of the spec to make clear what areas are being tested

x. Setup & Teardown appropriate: Setup & teardown must be defined such that the system returns to its original state, even in case of test failure

6. Elements & search criterion items

a. Names appropriately consistent: Names of elements & search criteria for resources should be consistent across FHIR, particularly within the same "family" (e.g. medications, interventions, orders, w5 report equivalents, etc.), unless business convention dictates otherwise.

• ??? TODO Will reach out to FHIR list for guidance here

b. Elements sorted ok: Data elements & search criteria should be ordered in the same way across resources (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. W5 elements must appear in the order defined unless there are strong business reasons for a different order (raise with MnM to get permission to override the sort rule for a given resource). Note that items related to W5 items can still be inter-mixed with W5 items.

• ??? TODO Will reach out to FHIR list for guidance here

7. Descriptive Content

a. Todos resolved: Review and resolve all "todos" in the specification

c. Rationale provided where needed: Must populate the "requirements" element explaining what the test script is trying to accomplish and to differentiate it from other test scripts for the same resource(s) and/or profile(s)

d. Committee notes filled in: If there are major points of contention in the design of a test script, XML comments should be used to capture those issues and their resolutions to help guide future development/maintenance

f. Descriptions complete: Include descriptions for each test step explaining the purpose

Web Page (e.g. http.html, xml.html, etc.)

FHIR QA Conformance Tracker - Web Page

7. Descriptive Content

i. Header ok: All non-navigation pages (i.e. pages whose primary purposes is not navigation of the spec) must have a header that allows identification of the responsible work group

j. FMM Level & Ballot Status ok: Only "implementable" pages should have an FMM level and ballot status. (Ballot status of non-implementable pages is "supporting material")

• ??? TODO Note: We will need to add the notion of "supporting material" and mixed-level artifacts to the GOM