Proposal: Standard metadata properties for SNOMED CT reference sets
Dion McMurtrie, CSIRO Australian e-Health Research Centre · Draft for TRAG / MAG discussion · October 2026
Summary
We propose that SNOMED International defines a small, extensible catalogue of reference set metadata properties, each carried in RF2 using one of three existing mechanisms, listed below. Each property is specified so it can be adopted on its own, and where properties interact the specification states how. No producer needs to adopt a new file format or populate everything at once.
- Defining relationships for facts that fix what a refset is, such as a map’s target code system
- Non-defining relationships for machine-actionable facts that may change, such as an inactive member policy
- Component annotations for human-readable text and URLs
Because the metadata lives in RF2, it is versioned with the reference set it describes, and no external artefact has to be found to interpret the release correctly. The primary aim is machine-actionable properties that terminology services act on during FHIR operations such as $expand, $validate-code and $translate, and that QA and authoring tools act on. A secondary benefit is standard presentation: each property maps to a FHIR ValueSet or ConceptMap element where one exists, as a goal rather than a constraint, so a server can also render a complete resource for the implicit URLs http://snomed.info/sct?fhir_vs=refset/[sctid] and http://snomed.info/sct?fhir_cm=[sctid] from the release alone.
We ask TRAG and MAG to consider and endorse the framework, agree the Phase 1 properties, agree the governance process, and advise on the open questions in the final section. The aim is not to solve every use case now, but to agree a well-founded base that later properties can build on, together with a governance process for growing, managing and maintaining the catalogue without it becoming unwieldy. That process is the central part of this proposal.
Problem and prior work
A reference set in RF2 today says what it contains, but almost nothing about what it is for, who maintains it, or how it should behave. Producers fill the gap with documents, web pages and separate metadata repositories. Consumers then have to find and interpret those sources, and a separate repository drifts out of step with the release it describes.
Some gaps are machine-level, not just descriptive:
- Maps. Older map reference sets give no machine-readable way to identify the non-SNOMED code system, and older ones did not state direction. Implementers hard-code which refset maps to which code system.
- Membership expectations. Nothing says whether a reference set may legitimately contain inactive components. Some should never do so (for example a data-entry subset). Others are expected to (for example a historical or migration set). QA and authoring tools cannot tell a defect from a design choice.
- FHIR operations. Operations such as $expand, $validate-code and $translate need facts the release does not carry: whether inactive members belong in an expansion, which code systems a map joins, and what relationship a map row asserts. Servers get these from local configuration or hard-coding. Presenting a complete resource (description, purpose, publisher, status) has the same gap, a lesser but real one.
This has been discussed several times without reaching an agreed specification:
| When | Effort | Outcome |
|---|---|---|
| 2023–2026 | Component and Member Annotation String Value refsets, populated from July 2024 for attribution | A general-purpose annotation mechanism now exists, but no agreed annotation types for refset metadata |
| 2021–2025 | Map refset redesign (MAG 2021, TRAG forum 2025): separate from and to SNOMED CT patterns with mapSource |
Direction now explicit for migrated maps; the other code system still not identified in content |
| 2020–2022 | TRAG Working Group: Refined Metadata (Andrew Atkinson, Dion McMurtrie, Matt Cordell, Michael Lawley, later Mikael Nyström, Alejandro Lopez Osornio, Reuben Daniels) | Sorted requirements into four categories: package, component gaps, IP and release notes, and refset metadata. The refset metadata straw man was never created; the group concluded the release package JSON file could cover foreseeable needs |
| 2020 | Release package metadata file (release_package_information.json) |
Package-level metadata (delta from and to, languages, modules, licence) now shipped; no refset-level content |
| 2018 | TRAG page “Reference set metadata proposal” | Copy of the 2017 page pointing back to it |
| 2017 | TRAG page “Reference set metadata” (Dion McMurtrie) | Problem accepted; comments distinguished type-level from instance-level metadata, and a column-per-item from a serialised-blob design |
| 2014 | IHTSDO work on human-readable descriptive refset metadata | Left “incomplete and unapproved”; stalled partly because it was thought to need a tool to create, edit and search the metadata |
Two things have changed since the earlier attempts. RF2 now has annotation refsets and concrete domains, so no new file format is needed. And FHIR terminology servers have become the main way refsets are consumed, which gives the metadata a clear, testable purpose.
Scope, and why RF2 rather than the package JSON file
This proposal covers two of the working group’s four categories: component gaps (such as a map’s foreign code system URI and correlation) and refset metadata. Package-level metadata stays in release_package_information.json, where it belongs.
The working group’s conclusion that the JSON file could absorb refset metadata does not hold up for refsets, for four reasons:
- Versioning. A refset’s metadata changes over its life. In RF2 each change has an effectiveTime and survives in the full release; the JSON file describes one package at one point in time.
- Composition. Editions combine modules from several producers. RF2 rows compose across extensions and snapshot in the usual way; package JSON files do not merge, and one package cannot describe a refset in another.
- One source. Metadata in the JSON file would still need restating in content for tools that work from loaded RF2, which duplicates it. This was Michael Lawley’s argument in the working group.
- Identity. Metadata on the refset concept travels with that concept wherever it is distributed, including derivative packages and re-bundled editions.
Several of the working group’s recorded requirements are met directly by Phase 1: the foreign code system URI for map refsets, the relationship type for implicit ConceptMaps where the refset does not state it, and identification of the map product and its version (candidate).
Design principles
- Individually adoptable. Each property has its own definition, mechanism and FHIR mapping (if applicable). A producer can populate one property on one refset. A consumer that does not recognise a property ignores it. Where one property changes how another is read, both specifications say so (see Interactions between properties). Each must still work when the other is missing: for example, a map correlation is simply ignored if the map’s code systems are not stated.
- In RF2, versioned with the content. Metadata changes carry an effectiveTime and module like any other component. Snapshot, delta and full views work unchanged, and a FHIR rendering for a given edition version reads that version’s metadata. A consumer holding the release has everything it needs; no document, repository or configuration file has to be located to use a refset correctly.
- Existing mechanisms only. No new release file type. We use relationships, concrete values, the annotation refsets, text definitions and the refset descriptor. New content is limited to metadata concepts (attributes and values).
- Right mechanism for the property. Whether a property is defining, non-defining or an annotation follows from what it is (see Framework), not an arbitrary choice.
- Optional, with defined absence. Every property states what a consumer should assume when it is absent, usually today’s behaviour. No existing refset becomes non-conformant.
- FHIR-aligned, not FHIR-driven. Each property maps to a FHIR element where one exists. SNOMED CT semantics come first, and a property with no FHIR equivalent is still valid. Some are expected to have none, such as inclusion criteria; servers can still act on them in operations, or expose them through extensions.
- Incremental agreement. A small, uncontroversial Phase 1 is published first. Further properties are added one at a time as consensus forms, as the 2017 proposal recommended.
Framework
Every property is classified on two axes and assigned one carrier mechanism. The axes keep separate problems separate. The mechanism follows from what the property is.
Scope: type or instance. Type-level metadata describes a refset pattern and applies to every refset of that type, for example key uniqueness or which columns are mutable. It belongs on refset type concepts as defining properties; the refset descriptor remains a parsing specification only. Instance-level metadata describes one refset, for example its purpose or its map target. Phase 1 and the candidate properties define instance-level properties only. A value may be stated once on a refset type concept so that every refset of that type inherits it, as with the map code systems, but the property still describes each refset, not the type.
Audience: human or machine. Human-readable metadata is language-dependent text for people to read. Machine-actionable metadata is a concept or literal value that tools act on, such as a QA rule or a FHIR element.
Carrier mechanisms
| Mechanism | RF2 carrier | Values | Best for | Constraints |
|---|---|---|---|---|
| Existing structures | FSN and synonyms, text definition, refset descriptor, alternate identifier file, query specification refset | Text, descriptor rows, identifier rows, ECL | Name, short description, column structure, external identifiers, intensional definition | Already populated; reuse before inventing |
| Defining property | Stated axiom and inferred relationship on the refset concept; new attribute with MRCM domain << 900000000000455006 |Reference set| |
Concept or concrete value | Facts that fix what the refset is by stating necessary (and possibly sufficient) conditions that are part of the refset concept’s meaning | Changing the value means a new refset; ECL-queryable; inherited by subsumption; needs MRCM and classification of the metadata hierarchy |
| Non-defining property | Relationship with characteristic type Additional, attribute under 1295449009 |Additional relationship attribute| (per the MAG 2023 content model plan) |
Concept value, or concrete value (integer, decimal or string) | Data, metadata or knowledge about the refset that is not definitional, and may be temporal | Not inherited; not part of the concept’s meaning |
| Annotation | Component Annotation String Value refset, typeId under 1295447006 |Annotation attribute| |
String, with languageDialectCode |
Human-readable text and URLs | Strings only; not inherited; not ECL-queryable; weaker multilingual support than descriptions (a dialect code, but no acceptability or language refsets) |
Decision rule
Apply in order; the first match wins.
- An existing RF2 structure already carries it → use that structure.
- It is human-readable text or a URL → annotation; an external identifier goes in the alternate identifier file, under step 1.
- It is machine-actionable, and it states a necessary condition of the refset concept’s meaning, so that a different value would mean a different reference set → defining property.
- Otherwise, it is data or knowledge about the refset rather than part of its definition → non-defining property.
Steps 2 and 4 follow an existing agreement. At the October 2023 MAG meeting in Atlanta, TRAG asked when to use additional relationships or concrete values rather than annotations. The recorded answer was that metadata is an annotation and data is an additional relationship. The Terminology Management Working Group proposed that this data-versus-metadata test become Editorial Guidance, so that different parties do not solve the same problem differently; its example was URI identifiers for code systems. The same meeting’s work plan records “Refset metadata via annotations” as agreed, and notes that refset metadata was expected to be met by annotations, with language aliases as an early use case (MAG 2023-10-24/25).
Refset concepts are always primitive, but a primitive concept can still carry necessary conditions. Defining properties therefore add to the refset’s stated meaning without making it fully defined.
What “defining” means for a refset concept
A refset concept denotes an artefact, not a clinical class, so its defining properties are necessary conditions on that artefact across all its versions. Two consequences follow:
- Definitional implies stable, not the reverse. A necessary condition cannot change without changing the concept’s meaning, which in SNOMED CT practice means a new concept. A fact that happens never to change, such as a maintainer, is still not definitional.
- Few properties qualify. A useful test is whether the fact belongs in the refset’s FSN. Map source and target code system pass (“SNOMED CT to ICD-10 extended map”). So does Map correlation for a map whose every row carries the same correlation. Target code system version, Maintainer, Maturity and Inactive member policy do not, so they are non-defining or annotations.
Conditions on a refset’s members are not properties of the refset concept, so they cannot be defining relationships. They are covered by the existing Query specification reference set and by Inclusion criteria; see Membership under the Phase 1 catalogue.
Inheritance
Defining properties asserted on a refset type concept apply to all refsets beneath it by subsumption, and cannot be overridden: a refset beneath the type may add to them but not replace them. Non-defining properties and annotations apply only to the concept they are on. They are not inherited, so each refset states its own value, which may differ from its type’s. A property specification cannot introduce type-level defaults for non-defining properties. A fact that every refset of a type must share is, by that test, a candidate for a defining property.
Interactions between properties
Some properties are expected to interact. Known cases so far:
| Properties | Interaction | Proposed rule |
|---|---|---|
| Inactive member policy × query specification | Plain ECL already returns only active concepts, so the policy matters only for published member rows that have gone stale, or for ECL with history supplements | Not permitted: stale inactive members are a validation error. ECL with history supplements requires Expected |
| Inclusion criteria × query specification | An intensional refset may carry both | The ECL is authoritative; a mismatch with the criteria is a signal for review |
| Map source / target code system × Map correlation | A correlation only has meaning once both sides are known | Map correlation is ignored unless both code systems are resolvable |
| Defining property on a type × refset beneath it | The refset inherits the type’s defining properties | Cannot be overridden; only non-defining values differ per refset |
Other interactions may emerge as properties are added. Open question 7 asks how to govern them.
Governance of the property catalogue
TRAG owns the whole process, defining properties included, supported by a named role within SNOMED International to run it and to follow agreed changes through into the International Edition, with a note that the flow should be sporadic once the catalogue is established, so the role shouldn’t be onerous.
The catalogue is self-describing
Every property is a metadata concept under one of three grouper concepts: Reference set defining metadata attribute, Reference set non-defining metadata attribute, and Reference set metadata annotation (under 1295447006 |Annotation attribute|). Each property concept carries its own definition as a text definition and its FHIR mapping as an annotation. It has no separate catalogue status: a published property is in production, whether in the International Edition or an extension, and a retired one is inactivated like any other concept, with a historical association to its replacement. << [grouper] then lists the catalogue for any edition, and consumers discover new properties without a separate registry.
Property specification template
Every proposed property, from SNOMED International or anyone else, is written up with these fields before review:
| Field | Content |
|---|---|
| Name | FSN following the naming convention below |
| Definition | What the property asserts, in one or two sentences |
| Use case | The concrete problem, and at least one producer and one consumer who need it |
| Scope | Type-level or instance-level; which refsets it applies to, as refset types from the International Edition (for example map types, or simple type) or extension, or specific instances |
| Audience | Human-readable or machine-actionable |
| Mechanism | Defining, non-defining or annotation, with the decision-rule step that selects it |
| Value domain | Value hierarchy, concrete type, or text or URI format. For a value hierarchy, state whether existing concepts are reused (for example the map correlation or geographic location concepts) or new value concepts are specified with the property |
| Cardinality | Per refset, and per language dialect for text |
| Absence | What a consumer assumes when the property is not present |
| Interactions | Effects on, or from, existing properties |
| Behaviour | Expected effect on FHIR operations, validation and authoring tools |
| FHIR mapping | Target element, or “none” with the reason |
| Examples | Named refsets where it would be used if approved, ideally from more than one edition, with populated values |
Admission process
There are two routes into the catalogue, and both must be fast.
Route A: propose centrally. Anyone may propose a property directly to TRAG, which agrees it and SNOMED International implements it in a coming International Edition. This is the only route open to a producer with no extension or edition of its own, and it is the better route whenever the property is generally useful, since nobody should have to build something locally first to have a need met. The Phase 1 set follows this route.
Route B: build locally, then promote. A producer who needs a property now, or who wants to prove it in use, defines it in its own namespace and registers it with TRAG so others can reuse it rather than create an overlapping one. It is then proposed for promotion on the evidence of that use, and on promotion the local concept is inactivated and linked by a historical association to its International replacement.
Both routes meet at the same steps below. Route B differs only in supplying evidence of local use at the Submit step.
- Submit a completed template to TRAG, with evidence of local use where the property is being promoted from an extension.
- Screen against the anti-sprawl rules below; a proposal that fails goes back with reasons.
- Classify the mechanism using the decision rule. A defining property also needs its MRCM domain and range specified, and TRAG may draw on modelling advice where a proposal is contentious, but the decision stays with TRAG rather than going through a separate route.
- Review for interactions and FHIR alignment, with FHIR mappings and operation behaviours checked by the SNOMED on FHIR group.
- Approve and publish, with a target of the next International Edition release cycle, or withdraw. The SNOMED International role sees the approved content through to release. On promotion from an extension, the local concept is inactivated and linked by a historical association to its International replacement.
- Maintain. Changes to a definition follow the same route. A property that is superseded or unused is inactivated after a notice period, with a historical association to its replacement where one exists.
The central process of accepting and publishing properties must be prompt and responsive to users’ needs. If it is slow, producers with an extension will create their own properties to keep moving, giving divergent, overlapping properties — the sprawl this governance exists to prevent — and producers without one are left with no option at all. Responsiveness is what makes the central route the normal one.
Anti-sprawl rules
- Reuse first. No property duplicates an existing RF2 structure or catalogue entry. An extension to an existing value hierarchy is preferred to a new property.
- General, not bespoke. A property must make sense for refsets from more than one producer. Producer-specific needs stay local (below).
- Actionable or clearly human-facing. Each property either changes what a tool does, or carries text people need. Nothing is admitted “in case”.
- One meaning per property. No multipurpose free-text slots and no serialised blobs.
- Bounded values. Machine-actionable values come from a published value hierarchy or concrete type, not free text.
Naming
Attribute FSNs take a possessive verb form and the semantic tag (reference set attribute), following Has <name> (reference set attribute), for example Has inactive member policy (reference set attribute) and Has map target code system (reference set attribute). Value concepts follow <value> (foundation metadata concept) under a hierarchy named for their property.
Local properties
Local properties use the same groupers and template as International ones, so they are discoverable in any edition that includes them. Registration with TRAG happens when a local property is created, not only at promotion, so overlaps between producers are caught early. Adoption by a second producer is a strong signal that a local property should be proposed for promotion.
Continued in the first reply below: Proposed property catalogue, FHIR operations and rendering, worked examples, conformance, open questions and references.