This wiki has undergone a migration to Confluence found Here

Code System Supplement Artifact Definition

From HL7Wiki
Jump to navigation Jump to search

Return to Artifact List

Code System Supplement

Definition and Purpose

A code system supplement allows properties, display names and relationships to be added to codes from another Code System. It is used when modification of the base code system is not possible. Unlike a code system, a code system supplement does not define any concepts, it merely adds information to concepts defined in an existing code system.

SAIF Matrix Location


  • Logical (PIM)


  • Information

Prior Methodology Correspondence

This artifact is supported in current methodology, though is presently only used by affiliates and not by HL7 International.


Health Care Community Audiences:

  • General public
  • Health care practitioners

These may encounter the supplemental display names and/or take advantage of the capabilities enabled by supplemental relationships and properties

Health Care Semantic Analysis Audiences:

  • Informaticists: Select and differentiate between information models and terminologies
  • System analysts: Map system requirements to specific technical solutions

Health Care Information Technology (IT) Audiences:

  • Standards developers and standards development organizations
  • Programmers/implementers

These will potentially need to create, maintain or use Code System Supplements


These artifacts only need to be created when there is a need to have additional information "in" a code system, when there is no ability to manipulate the code system directly. Common examples would be adding language translations for display names, adding properties to govern use of concepts, or adding relationships between concepts from code systems maintained by other organizations.

Rationale: Not all code systems have maintenance policies (or even the technical capability) to support introducing translations and other changes. As well, the properties or relationship additions to be introduced may not be within the scope of the maintaining organization.

Requirements, Relationships and Content

  1. Need to support adding alternate (and/or translated) display names for a concept in an existing code system.
    1. Rationale: It may not be possible to get these changes into the base code system due to maintenance policy or code system capabilities.
  2. There needs to be a way for concept properties not defined in a base code system to be introduced into the code system for use in creation of value sets
    1. RationaleFor example, adding a flag to indicate what LOINC codes are "orderable" in a particular jurisdiction; introduce formal logic constructs into a code system where they're not formally defined, etc.
  3. There needs to be a way for relationships to be introduced into a code system where the're not already defined.
    1. RationaleSome code systems may have "implicit" relationships that are not formally exposed but which are useful in defining value sets and/or allowing users to navigate the code system. As well, there may be a need to expose relationships between codes in distinct code systems where those relationships aren't defined in either the source or target code system.

Relationships and traceability

  • Code System Supplements must extend exactly one Code System
    • Rationale: The whole point of a supplement is to define additional information that's not in a base code system without defining additional codes
  • Code System Supplements may define relationships to other code systems.
    • Rationale: While a code system supplement is tied to exactly one code system, the relationships it defines may reference other code systems.

Artifact types that may or must relate to this artifact types:


  • Id - Unique identifier for the supplement
  • Name - Descriptive label for the supplement
  • Metadata - Description, rationale, who created it, etc.
  • Supplemented Code System Id - What code system is being supplemented
  • Property definitions - defines any new properties being defined, including allowed values and what type of concepts the property may or must be associated with
  • Representation definitions - defines any new display name types being defined, including constraints on where they can be used
  • Relationship definitions - defines any new association name types being defined, including constraints on where they can be used
  • Supplemented Concept - Reference (by code or concept id) to a concept being supplemented, including constraints on where they can be used
    • Supplemental property - property name and value
    • Supplemental representations - New display names, including language
    • Supplemental relationships - New display relationships, including source and target concept and relationship properties

Artifact Technology

Currently custom (MIF).


  • No existing technology manages the requirement



  • Allows assertions to be made about concepts defined in another namespace (code system)
  • Does not seem structured to support detailed metadata such as definitions with translations and markup


  • In theory fill fully support HL7 requirements in this space
  • Too new to have much tooling support

Content Constraints

  1. Code system supplements cannot define new codes
    1. Rationale: This would require a new code system, not a code system supplement
  2. Some other rule
    1. Rationale: Some other reason

Content Guidelines

  1. New display names or associations must not change the semantics of the associated concept in any way
    1. Rationale: Semantics of the code will be interpreted by applications using the code system, not the code system supplement

Publishing Representation(s)

  1. Some text
    1. Rationale: Some rationale

Publishing Constraints

  1. Content must be submitted in the "current" version of MIF, as determined by the publishing committee
    1. Rationale: Ensures consistent behavior of source files with tools

Tooling Considerations

  1. Nice-to-have: A tool that actually allows authoring of Code System supplements :>
    1. Rationale: Right now, all editing is by hand
  2. Nice-to-have: Support for validating and authoring code system supplements with knowledge of the current version of the underlying code system.
    1. Rationale: Eases authoring of code system supplements and ensures accuracy of the code system supplement

Development Process Considerations

  1. In most cases, code system supplements will not be developed by HL7 International, but will instead be produced by affiliates or implementing groups
    1. Rationale: HL7 International has full ability to modify and maintain its own code systems and minimal requirement to supplement the code systems of others.

Artifact Exchange and Version Management

Content will be exchanged using MIF 2.x, at least until CTS II tools are available and are capable of converting to and from MIF.

Authoring and Maintenance Tools

No tools currently exist. In theory LexEVS or DTS may be candidates once an HL7 CTS II profile is developed if these tools can round-trip MIF content.

Governance Process Considerations



  • Need to confirm full support for Code System Supplements in CTS II