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 be revisions to the concepts within a Terminology, and not a substantial update 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 should 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

The intent of Terminology Change Sets is that they are used as a communication pathway between systems, utilizing the CodeSystem resource. Systems involved in this exchange will intake a Change Set and receive it and process it, and should have a process to store and maintain the contents of the Change Set. Our expectation is that a Terminology Change Set is a transmission format, much like downloads of content available from RxNorm and SNOMED International. It is not necessarily expected that systems involved in Change Set exchange will re-publish the Change Set content in their own FHIR API, but it is rather an ingestion pathway for a system’s terminology server. If a system decides that it would be valuable to re-publish the contents of the Change Set, then they could do that and would need to maintain a process for reconciling Change Sets received from multiple sources.

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 Revisisions 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.

Recommended approach when persisting Change Sets

Maintaining Change Sets separately while developing robust mechanisms to integrate these changes into the Source CodeSystem as needed is advisable. This approach offers flexibility in managing changes and ensures data integrity while simplifying rollback and version control processes.

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 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 process, LOINC process, HL7 process), and such pathways should be the preferred process for implementers when new concepts are needed from a terminology.

When implementers determine that they are interested in extending a terminology, wherever possible, they should do so in alignment with the authoring guidelines and terms of use for the terminology they are extending. While SNOMED has a robust methodology allowing for the authoring, distribution, and maintenance of extensions, most other terminologies do not. 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’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.

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.