Change Set Contents

Change Sets are intended to be a lightweight, incremental distribution that is a more agile alternative to a full distribution for a given terminology. As such, their contents are expected to consist of new concepts to be added, or modified versions of existing concepts (including deprecation/inactivation) within a specific Terminology version, and not updates to the structure or operation of a Terminology. The primary substance of a Change Set is expected to be contained within the CodeSystem.concept structure of of Change Set CodeSystem resource. Additionally, while the following elements may be included in a Change Set, they must match the values present in the corresponding baseline of the Terminology from which the Change Set was derived:

• CodeSystem.caseSensitive
• CodeSystem.hierarchyMeaning
• CodeSystem.compositional
• CodeSystem.property - note that only properties relevant to content within the change set may be included, but those properties should be a subset of properties defined in the corresponding baseline of the Terminology from which the change set was derived (i.e., no net-new properties should be defined via a change set).

How receiving systems should operate in the presence of a change set

Change sets are designed to be processed to make updates to the authoritative CodeSystems made available by a Terminology Server. They are designed to be used by content authors as a distribution format for terminology, and are not intended to be persisted or retrievable from a Terminology Server supporting operational transactions. Specifically, they are not intended to function like supplements, which are intended to be persisted side-by-side with a full representation of a CodeSystem and effect the outcome of Terminology Service Operations on that CodeSystem.

Additional considerations for receiving systems operating in the presence of a change set include the following subsections.

Persistence of change set as a Separate Object vs. Integration

• Separate Object: If the change set is persisted as a separate object, it allows for easier tracking and management of changes over time without altering the original CodeSystem. This approach can be useful for maintaining historical data for audit purposes or for scenarios where changes need to be reviewed or approved before being applied.
• Integration into CodeSystem: Integrating the change set directly into the CodeSystem simplifies the management by ensuring that there is only one up-to-date version of each CodeSystem. However, this can complicate rollback and audit processes since the original state is overwritten.

Operational Changes with persisted change sets

• When a client application performs a lookup operation (e.g., $lookup), it should ideally check the change set first to see if there has been a recent update relevant to the query. If no relevant change is found in the change set, then the lookup should proceed to check the main CodeSystem. This ensures that the most current data is used.

Managing Terminology Revisions via change sets

It could be possible to manage the evolution of Terminology as a series of persisted change sets, but that use case for change sets was not considered as part of development of this guide.

Extending Terminologies

One potential use case for Terminology Change Sets is for sharing locally extended versions of Terminologies. Some examples of such extensions include the US Department of Veterans Affairs extending SNOMED CT to include findings and procedures unique to war veteran treatment, and the US Association of Public Health Laboratories extending LOINC to support COVID test data quality initiatives.

While use cases do exist to justify such extensions, implementers are strongly cautioned not to author and distribute such extensions without first exhausting pathways for updates to the source terminology through the SDO that maintains it. Most SDOs maintain new term submission pathways that are well maintained and promptly serviced (see: SNOMED CT process, LOINC process, HL7 process), and such pathways should be the preferred process for implementers when new concepts are needed from a terminology.

When code system stewards/publishers decide to extend a terminology version, they are expected to maintain alignment with the authoring guidelines and terms of use for the terminology they are extending. Implementers developing and maintaining extensions should ensure they have a strategy for clearly identifying extended CodeSystem resources utilizing the following elements:

• CodeSystem.url – where not specified by an SDO-specific policy (such as SNOMED CT’s extension process) locally-maintained extensions should include a url clearly identifying the extension as published under the implementer’s authority, and not the SDO.
• CodeSystem.version – where not specified by an SDO-specific policy, it is recommended that implementers consider aligning to HL7 terminology versioning approach
• CodeSystem.name – locally-maintained extensions should contain a computer-friendly name (consist with cnl-0) clearly identifying the CodeSystem resource as a change set and ideally conveying both the source terminology from which it was derived and a notion of its contents.
• CodeSystem.title – locally-maintained extensions should contain a human-friendly name clearly identifying the CodeSystem resource as a change set and ideally conveying both the source terminology from which it was derived and a notion of its contents.
• CodeSystem.description – locally-maintained extensions should utilize the description element to provide a more robust inventory of the contents of the change set.

In the absence of an editorial policy from the source terminology, implementers should strive to follow the best practices described in Desiderata for Controlled Medical Vocabularies in the Twenty-First Century.

CodeSystem Properties

Within a FHIR representation, a CodeSystem's properties are perhaps the most important structure for defining the terminology-specific semantics for the concepts in that CodeSystem. Given the broad variation of semantics adopted across terminologies, FHIR has a flexible design for representing properties (see: https://hl7.org/fhir/R4/codesystem.html#properties), but that flexibility can lead to inconsistency of implementation without clear guidance for representation of terminology-specific properties.

To address this issue, HL7 has developed guidance for properties on its terminology-specific sub pages under the External Code Systems page within HL7's Terminology publication. On the "Use with HL7 Standards" tab, the far right column of the displayed table ("Use with HL7 Standards") contains links to terminology specific pages where guidance on properties is present. Below are direct links to several commonly used terminologies in the US:

• SNOMED CT Properties
• RxNorm Properties
• LOINC Properties

These pages are works in progress, and have varying levels of completeness, but should be referenced as the most robust source for guidance on terminology-specific properties, until such time as similar guidance is available directly from the maintainers of these external code systems.

Use of PATCH with change sets

In addition to distribution of incremental terminology updates utilizing a Terminology Change Set, implementers of FHIR Terminology Servers could repackage the changes from the change set as a patch document and perform a PATCH operation to update an entire CodeSystem resource. This can be useful when a server is seeking to minimize its bandwidth utilization, or in scenarios where a client has only partial access or support for a resource. The server shall process its own copy of the resource in the format indicated, applying the operations specified in the document, following the relevant PATCH specification. While this use case is not a focus of this FHIR IG, we acknowledge that a PATCH transaction could be used to update a FHIR Terminology Server’s representation of a given Terminology.