FHIR Conformance QA Criteria

Note: the following criteria are draft and propose criteria that may apply to various Conformance resources. They are based on the conformance criteria found here: DSTU_QA_Guidelines

• Resource definition StructureDefinitions (to add to existing QA guidelines)
  • MnM approval should be sought before populating the "identifier", "version", "code" or "shapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)
  • Seek MnM approval before specifying any content for StructureDefinition.description
  • Element names (for slicing) should be software-friendly: UpperCamelCase alpha-numeric, starting with an alpha
  • Profiles on element types, if present, must be HL7-Int'l-defined profiles and their use requires MnM approval

Extension definition StructureDefinitions

• • 1a (Could be multiple or just one)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 1c
  • 2a (Should have at least 1 for non-trivial extensions – i.e. not for dates, numbers, etc. However good for complex multi-element extensions or for strings or unbound coded elements to show how element might be used. Can be covered by an example instance using a containing resource instance.)
  • 2b
  • 3a HL7 Int’l defined extensions must include RIM mappings or must explicitly declare they are not RIM mappable
  • 3b
  • 4a Preferred is generally desired. Use "Required" or "Extensible" only where there's certainty that the codes will be useful across all countries and scopes, or where the extension is explicitly defined as realm-specific.
  • 4b, 4c, 4d, 4e
  • 5a 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
  • 5c 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
  • 6a ??? - 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 (for Grahame).
  • 6b (For complex extensions)
  • 7a
  • 7b
  • 7c
  • 7d
  • 8a
  • 8b
  • Extension definitions should not overlap in purpose/meaning with other extensions (even if defined in other HL7 Int'l-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.)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For extensions that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • MnM approval should be sought before populating the "identifier", "version", "code" or "shapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)
  • 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
  • For HL7 Int'l-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
  • MnM approval should be sought before defining extensions whose root element has a minimum cardinality of "1"
  • Seek MnM approval before specifying any content for StructureDefinition.description
  • Element names (for type references or slicing) should be software-friendly: UpperCamelCase alpha-numeric, starting with an alpha
  • Profiles on element types, if present, must be HL7-Int'l-defined profiles
  • mustSupport must not be declared on HL7-Int'l defined extension definitions (declare it on the profiles where the extension is invoked)
  • A corresponding search criteria should exist for the extension if it's reasonable for systems to want to search on it

Constraint StructureDefinitions

• • 1a (Could be multiple or just one)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 1c
  • 2a
  • 2b
  • 2c
  • 3a RIM mappings are only required for HL7 Int’l-defined constraint profiles if the mappings would differ from the underlying resource.
  • 3b
  • 4a Preferred is generally desired. Use "Required" or "Extensible" only where there's certainty that the codes will be useful across all countries and scopes, or where the extension is explicitly defined as realm-specific.
  • 4b, 4c, 4d, 4e
  • 6a Slice names must be UpperCamelCase alphanumeric. Slice names should be consistent within a profile and within families of related profiles (same IG, same domain)
  • 6b (When listing permitted extensions)
  • 7a
  • 7b
  • 7c (rationale should be adjusted to reflect the rationale for any additional constraints)
  • 7d
  • 8b (within the context of intended use of the profile)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For profiles that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • For HL7 Int'l-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
  • MnM approval should be sought before populating the "identifier", "version", "code" or "shapshot.element.code" elements (so MnM can get a sense of how they're being used and ensure consistency)
  • Must have StructureDefinition.description which provides an overview of the purpose of this particular "constraint"
  • Element names (for type references or slicing) should be software-friendly: UpperCamelCase alpha-numeric, starting with an alpha
  • If slicing is present, description must be present.
  • If slicing is present, MnM approval must be sought if discriminator is not specified
  • Profiles on element types, if present, must be HL7-Int'l-defined profiles

ValueSets

• • 1a (Could be multiple or just one)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 1c
  • 6a 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.
  • 6b 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.
  • 7a
  • 7c (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)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For value sets that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • For HL7 Int'l-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
  • Value sets marked as immutable must have the use of isImmutable approved by the vocabulary work group

CodeSystems

• • 1a (Could be multiple or just one)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 1c
  • 3a - Expect mappings to HL7 v3 vocabularies for FHIR-defined code systems where such mappings exist
  • 3b - 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.)
  • 6a Code system names within the same "families" should be labeled in a consistent fashion. Names should reflect the scope of intended use of the value set.
  • 6b 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.
  • 7a
  • 7b (Will use Vocab's rules for good practices, including non-tautological)
  • 7c (Must populate the "requirements" element explaining why the code system is needed and why it's structured as it is)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For code systems that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • For HL7 Int'l-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
  • All codes must have both display names and definitions
  • property names must be lowerCamelCase alpha-numeric
  • properties must have meaningful/useful descriptions
  • Filters must have descriptions explaining what the formal representation is doing
  • If designations with a particular use/language are present on some codes, such designations must be present on all codes
  • FHIR defined code systems cannot set compositional or versionNeeded to true and must set content=complete
  • FHIR defined code systems must have "meaningful" code values, expressed in US-English

ImplementationGuide instance

• • 1a (Just one context)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 1c
  • 6a Must adhere to naming guidelines for HL7 specifications as published by TSC.
  • 6b ?? Will have separate guidance around implementation guide sections & ordering
  • 7a
  • 7c (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.)
  • 7d 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)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For extensions that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • For HL7 Int'l-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
  • 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
  • All pages within the IG should include links at the top and bottom that allow returning to the IG "home page" and should make it clear which implementation guide a page belongs to.

ConceptMap

• • 1c
  • 6a ??? Will also explore the need for computable names here. Human-readable names should identify the two artifacts mapped and the primary scope/purpose of the mapping.
  • 6b 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.
  • 7a
  • 7c (Must populate the "requirements" element explaining why the concept map is needed and what its purpose is)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For extensions that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • For HL7 Int'l-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
  • Source and target should be version-specific
  • Source, target and OtherElement concepts must exist in their respective value set versions (automate)
  • ConceptMap description should indicate whether the mapping is complete from a source and target perspective, and if incomplete, roughly what the coverage gaps are
  • Description should provide an explanation of how dependsOn and product are used in the context of the mapping.

Conformance

• • 1a (Could be multiple or just one)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 1c
  • 3b - Provide all other known "identifiers" for the naming system - OIDs, v2 code system labels or identifier types (where 1..1 with the system), etc.
  • 6a 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.
  • 7a
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For extensions that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared

OperationDefinition

• • 1a (Could be multiple or just one)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 1c
  • 2a (1 or more examples showing invocation & response. Examples should cover major expected parameter combinations. Every parameter should be covered at least once)
  • 2b
  • 6a lowerCamelCase alphanumeric avoiding reserved words. Operations must be unique within HL7-Int'l 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 IGs, etc.
  • 6b 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.
  • 7a
  • 7b
    • 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")
  • 7c (Must populate the "requirements" element explaining why the operation is needed and what its purpose is)
  • 7d
  • 8b (if we add invariants)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For extensions that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • For HL7 Int'l-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

SearchParameter

• • 1a (Could be multiple or just one)
  • 1b (Only in the scope of HL7 Int’l-defined artifacts)
  • 2a (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.)
  • 2b
  • 6a Code must be alllowercase alphanumeric avoiding reserved words. Both code and name must be unique across all SearchParameters defined by HL7 Int'l for the resource they apply to. Names and codes should be consistent within the resource and across families
  • 7a
  • 7b
    • 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")
  • 7c (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)
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For extensions that are not "global" in scope useContext should be declared for domain (e.g. pharmacy), realm (e.g. US), patient type (e.g. human vs. veterinary) should be declared
  • For HL7 Int'l-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

TestScript

• • 1a (Just one)
  • 6a ??? Will reach out to FHIR list for guidance here
  • 6b ??? Will reach out to FHIR list for guidance here
  • 7a
  • 7c (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))
  • 7d 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
  • Publisher and contact information must be set to the work group (and, where appropriate, project) responsible for maintaining the artifact
  • For HL7 Int'l-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