FHIR Terminology Ecosystem IG, published by HL7 FHIR Product Director. This guide is not an authorized publication; it is the continuous build for version 1.11.1-snapshot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-tx-ecosystem-ig/ and changes regularly. See the Directory of published versions
This document describes the requirements for all servers that are part of the HL7 terminology ecosystem. Note that systems do not need to conform to these requirements to be described as 'FHIR Terminology servers', but they do need to conform to these requirements to be part of the ecosystem.
Every requirement on this page is enforced by one or more of the test cases, and the test cases are the definitive statement of what the requirement means: where this page and a test case disagree, that is a defect in one of them, and should be reported. Each section names the test suites that cover it, so that an implementer can go from a rule to the tests that check it.
Most requirements apply to every server. Some apply only to a server that supports a particular code system or a particular feature, and those are stated conditionally - "if a server supports X, then it SHALL …". In the test cases these conditional requirements are gated by a mode: a test gated on a mode you do not pass to the runner does not run, and does not count as either a pass or a failure. So a server declares which of these sections apply to it by which modes it asks to be tested in. See Modes.
The test cases are written in R5 but run against R4 servers as well, with the runner converting requests and responses on the fly. Where a requirement takes a different form in R4, it says so, and R4 and the Test Cases has the detail.
A server speaks one version of FHIR, and the test runner discovers which:
$versions operation at the root, or return a CapabilityStatement from /metadata that populates CapabilityStatement.fhirVersion§8. A server that does neither cannot be tested, and cannot be registered(covered throughout; the http-code property on a test case says what is expected)
application/fhir+json)§11. XML is not requiredParameters resource POSTed to the operation endpoint§12. GET forms are used in places by clients but are not required by the ecosystem$validate-code that finds the code invalid is a successful operation, and returns
200 with result = falseOperationOutcome when it could not carry out the operation at all§14:
the value set could not be resolved, the request was malformed, the code system
is unknown to a $subsumes call, the expansion is too costly. The test cases state the expected
status as 4xx rather than a specific code, so any 4xx is acceptedEvery error, warning and comment the server produces is carried as an OperationOutcome.issue, either
in a returned OperationOutcome or in the issues parameter of an operation response. For all of them:
severity, code, details.coding, and details.text§16details.coding SHALL include a coding from http://hl7.org/fhir/tools/CodeSystem/tx-issue-type§17.
This is what lets a validator process the issue correctly, and it matters more than issue.code,
for which more than one value is often acceptedexpression naming it§18, so that
a validator can locate the issue in the resource being validateddiagnostics MAY be populated§19; the test cases ignore ithttp://hl7.org/fhir/StructureDefinition/operationoutcome-message-id extension§20
with the server's own identifier for the message. Only tx.fhir.org is required to, but other servers are
strongly encouraged to, since this is how users filter the messagesA server in the ecosystem is exposed to requests it did not write, from clients it does not control, so
it has to be able to say no. (suites: big, regex-bad)
tx-issue-type is too-costly§21.
What the limit is, and how it is calculated, is up to the server; that there is a limit, and that exceeding it produces this answer, is nottx-issue-type is vs-invalid§22, rather than crashing with some looping error (note: servers that can process some kinds of circular definitions and return a correct result may do so )(suite: metadata)
$versions at the root, returning the FHIR versions it supports§24. It is the
first thing the test runner asks for, and it is the only way for a server that speaks more than one
version of FHIR to say so$versions, Servers SHALL declare it in CapabilityStatement.rest.operation§25{root}/metadata§26url, version, name, title, status (active), date, and kind (instance)§27software.name, software.version and software.releaseDate. The name is what the test runner uses to identify the server in its output§28fhirVersion, and rest[mode = server].security.service§29application/fhir+json in format§30CapabilityStatement.instantiates value of http://hl7.org/fhir/CapabilityStatement/terminology-server§31rest.resource for CodeSystem, the operations lookup, subsumes and validate-code§32rest.resource for ValueSet, the read and search-type interactions and the operations expand and validate-code§33cache-control operation at the system level in rest.operation§34. This declaration is the only way a client discovers that the protocol is availableCodeSystemAsParameter, saying whether the server accepts CodeSystem resources in the tx-resource parameter. The feature SHALL be present; its value may be true or false§35{root}/metadata?mode=terminology§37version, name, title, status and date§38TerminologyCapabilities.codeSystem.uri, with the versions in codeSystem.version.code. Code systems SHALL be listed here whether or not they are available through /CodeSystem search§39 - this list, not the /CodeSystem endpoint, is what the ecosystem uses to decide whether to send a request to a serverexpansion.parameter, at least the parameters activeOnly, check-system-version, count, displayLanguage, excludeNested, force-system-version, includeDefinition, includeDesignations, offset, property, system-version and tx-resource§40default-valueset-version§41. Note that caching is not declared here: cache-id is no longer an expansion parameter, and support for caching is declared by the $cache-control operation in the CapabilityStatement - see CachingA 'supported' CodeSystem is any code system that the server supports correctly for calls to $expand, $validate-code, and $lookup.
A 'pre-defined' CodeSystem is any value set that the server makes available through the /CodeSystem endpoint.
There are two kinds of servers that are made available to the ecosystem: general purpose terminology servers that support arbitrary CodeSystem resources, and servers that are code system specific - they only support one code system (or a select short list of CodeSystems).
Servers are encouraged to make all the code systems that they support available on the /CodeSystem endpoint (search/read) but
they do not have to, and code systems such as SNOMED CT and LOINC often are not. But they must be listed in the
TerminologyCapabilities statement so that the ecosystem knows which code systems the server supports.
TerminologyCapabilities.codeSystem.uri, and all the versions in TerminologyCapabilities.codeSystem.version.code. Code systems SHALL be listed here whether or not they are available through code system search §42/CodeSystem endpoint for search and read operations§43url and version search parameters§44Note that it's the bigger code systems such as SNOMED CT and LOINC that might not be available through /CodeSystem. Also note that the
terminology ecosystem does not make use of any search parameters
/CodeSystem/CodeSystem MAY have content = not-present§45; the tools will not consider this when choosing whether to try using the code system (uses TerminologyCapabilities.codeSystem.uri)Servers are encouraged to ensure that all code systems conform to the ShareableCodeSystem Profile found in the CRMI specification, but this is not a technical requirement for being part of the ecosystem.
It's up to the server how to manage what content they support and implement. Servers can choose to support update/create if they want, though it SHOULD only do so for authenticated clients§47. update and create are not tested as part of the ecosystem.
Servers SHALL ensure that they only send correct results for the code systems for which they is registered as 'authoritative'§48 (e.g., not allow not appropriately authorised users to change the results by posting resources)
All predefined code systems SHALL have a web representation that is appropriate for a human to look at§49 (see below)
Terminology servers can choose to accept CodeSystems in the tx-resource parameter. General purpose servers SHALL accept CodeSystems (and are required to do this to pass the general tests)§50.
Servers SHALL indicate their support or not for passing CodeSystem resources in the tx-resource parameter using the CodeSystemAsParameter feature in the CapabilityStatement§51 (see above)
Terminology servers SHALL support passing CodeSystem supplements, particularly language packs§52. Servers that don't support language packs should only choose not to support language packs when there is governance over the use of language translations, and only by negotiation with the terminology ecosystem managers (see also notes below)
Servers SHALL support global language packs, including as tx-resource parameters, except where CodeSystems do not allow this§53 (ICD-11, for instance, allows explicit language packs, but not global language packs)
lang-pack - that is also marked with the
codesystem-supplement-global extension, with
the value true. A language pack without it is not global. (codesystem-supplement-global can also mark an
extension-codes supplement as global)
used-supplement in $lookup and $expand when it contributes
a display or a designation§55 unless the global language pack is defined privately by the server as part of supporting the code systemuseSupplement, or the
valueset-supplement extension) - passing it in
tx-resource is not enough (suite: global-lang-pack)reservedCodeSpace
is a regular expression that a code must match in full, and whose default-display is the display of a code in the
space that nothing defines (User-assigned if it doesn't give one). An extension-codes supplement
(codesystem-supplement-type) defines codes in
a reserved code space, with their displays
extension-codes supplement (marked with codesystem-supplement-global = true) is used for the code
system it supplements whether or not it is referenced, as if the code system defined its codes: its display is the
code's display, and a different display is an error (a warning with lenient-display-validation)extension-codes supplement that is not global is only used when it is referenced. Its display is then the
code's display, but not the only correct one: a different display is a warningextension-codes supplement defines are only in an expansion when they are listed in the value set
(compose.include.concept), not when it includes all of the code systemvalueset-unclosed), since codes in the reserved code
spaces are members of the value set ($validate-code accepts them) that the expansion can't list§57compose.include.concept) is a member of it: it is in the
expansion, and $validate-code accepts it. A filter never selects a code in a reserved code space - not even a
concept in or code in filter that lists it - since such codes have no hierarchy or properties: it is not in the
expansion, $validate-code rejects it, and the filter does not make the expansion unclosedextension-codes supplement that gives a display to a code outside the reserved code space - one the code
system defines - acts as a language pack does for that code (suites: extension-codes, and
extension-codes-3166 for ISO 3166's user-assigned codes)extension-codes supplement can give human displays to codes the grammar makes. Its display is
then the code's display, as above, but the display the grammar generates stays a valid display (suites:
icf-ec, sct-ec)Servers are required to support code system supplements. Specifically, this means:
Where a server makes language specific authoritative claims in the ecosystem registration (the languages property):
complete or fragment), not just the supplements§60 - it will receive the whole operation, not just the language-specific part$expand, $validate-code, and $lookup SHALL return correct displays and designations in that language (typically via loaded supplements)§61. This is verified by the language routing test cases, not by the coordination serverServers are required to support the following properties in the CodeSystem resource:
CodeSystem.caseSensitive SHALL be supported: validation SHALL correctly check case§62. In the case of non-case sensitive code systems, expansions SHOULD just contain the code as defined§63 (in the code system or the value set enumeration), and not all the case variants that could be generated. (suite: case)
CodeSystem.valueSet. Clients can use this to determine the server's value set for 'the entire code system'
CodeSystem.hierarchyMeaning. If the code system defines a hierarchy, both $expand and $validate SHALL correctly handle the hierarchy when interpreting filters and validating codes§64
CodeSystem.compositional. A server SHALL not accept compositional grammars for codes unless the CodeSystem is marked as Compositional§65. Servers that do not know the grammar for a CodeSystem that is marked as compositional SHALL note this in validation errors for the CodeSystem§66
CodeSystem.versionNeeded. If a CodeSystem says that version is needed, the $validate-code operation SHALL check that version is populated, and return an error if it's not§67
CodeSystem.content. Servers SHALL not process $expand or $validate-code requests on CodeSystems that have content = not-present or example§68. Servers SHALL reflect content = fragment in an error message if the code is not valid against a fragment. Specifically, where the code system is a fragment, a code that is not found SHALL NOT be reported as invalid: the answer is that the server cannot tell, and the message SHALL say that the code system is a fragment§69 (suite: fragment)
CodeSystem.supplements. Servers SHALL not mistake supplements and code systems for each other§70.
A number of concept properties defined at
concept-properties change how a concept behaves, and a server
SHALL honour them§71. The rule for recognising them is the same in each case, and is tested in detail for
notSelectable (suite: notSelectable):
uri from concept-properties, the
server SHALL recognise it whatever local code the code system gave it§72uri, it is a different property, and
the server SHALL NOT treat it as the standard one§74The properties that matter to the ecosystem are status, inactive, deprecated, notSelectable,
definition, parent and child. See
Inactive, Deprecated and Not-Selectable Codes for what
the first four mean.
A 'supported' value set is any value set that can be used in $expand or $validate-code operations, including value sets imported into other value sets, and including implicit value sets. A 'pre-defined' value set is any value set that the server makes available through the /ValueSet endpoint.
All servers are required to fully support value sets as defined in this document (per below).
/ValueSet endpoints for search and read operations§75url and version search parameters§76_summary search parameter§77Servers are encouraged to ensure that all value sets conform to the ShareableValueSet Profile found in the CRMI specification, but this is not a technical requirement for being part of the ecosystem.
It's up to the server how to manage what content they support and implement. Servers can choose to support update/create if they want, though it SHOULD only do so for authenticated clients§79.
$expand and $validate-code operations§81.TerminologyCapabilities.expansion.parameter§83ValueSet.compose§84ValueSet.compose.include and ValueSet.compose.exclude§85| Servers SHALL support extensionally defined value sets§87 (by enumerating codes in ValueSet.compose.in | exclude.concept) |
big, simple-cases)The ecosystem makes no rules - at this time - about the handling of value sets that have an expansion with no definition.
#id in
compose.include.valueSet or compose.exclude.valueSet to the contained value set with that id§92. As FHIR requires,
a #id reference is resolved against the contained resources of the containing resource, so a contained value
set can import another value set contained in the same resource (suites: simple-cases, validation, exclude)(suites: translate, translate2)
A server that supports $translate holds ConceptMaps in the same way it holds CodeSystems and
ValueSets, and the same rules apply:
tx-resource parameter, and use them for
$translate requests in the same call§94/ConceptMap endpoint for read
and search, and SHALL support the url and version search parameters if it does§95sourceScope / targetScope and ConceptMaps that
do not§96. A ConceptMap with no scope is still usable; it is only the server's ability to find it
without being told which map to use that is affectedThe content on that page MAY be static or active; it is at the discretion of the server to decide what's on the page, but it SHOULD be more than just the json/xml for the resource§98 (and it isn't limited to information in the resource, e.g. the server MAY choose to make additional process/provenance/context information available§99)
The server MAY choose to make this content available at the end-point for the relevant resource§100. e.g. a request for {root}/CodeSystem/123 with an Accept header of 'application/fhir+json' returns the resource, and the same URL with an Accept header of 'text/html' returns a web page suitable for human consumption. Servers are not required to do this; they MAY choose to make the content available elsewhere§101.
If the server chooses to make them available elsewhere, Servers SHALL populate the extension http://hl7.org/fhir/StructureDefinition/web-source in any resources it makes available with a valueUrl where the web view can be found. This SHALL be populated when the CodeSystem, ValueSet or ConceptMap is read, and also in any $expand of the value set (just for the root value set in this case)§102.
These apply to $expand and $validate-code alike.
If a server receives a terminology resource it does not process correctly, Servers SHALL return an error§104
system-version, check-system-version and force-system-version, and
SHALL observe the difference between them: system-version supplies a default that anything explicit
in the value set overrides, force-system-version overrides the value set, and check-system-version
produces an error if the value set asks for a different version§107. See
Code System VersionsA terminology client - the validator, the IG publisher - validates and expands thousands of times
against the same value sets and code systems, and many of them are ones the server does not already
have, because the IG being built is what defines them. Re-sending those definitions on every call is
the single largest source of wasted traffic in the ecosystem. The $cache-control protocol lets a
client send each resource to the server once and refer to it by url thereafter.
The protocol is defined in the FHIR Tools IG - see Terminology Caching for the protocol and the reasoning behind it, and the $cache-control OperationDefinition for the formal definition. That IG is normative for the protocol; what follows is what the ecosystem requires of a server that is part of it.
Note that this replaces the earlier cache-id parameter. The cache-id is now issued by the server
and carried in an HTTP header, and the parameter is withdrawn: servers SHOULD NOT accept it§108, and it is
no longer listed in TerminologyCapabilities.expansion.parameter.
$cache-control. This is not yet a SHALL§109, but it makes a very large
difference to build times and to network use, and it is expected to become onecache-control operation at the system level in
CapabilityStatement.rest.operation§110. A client uses the protocol only against a server that
advertises it, and inlines the resources on every request against any other - correct, just not
optimisedaffectsState = true; servers SHALL accept start and end by POST§111Note that declaring the operation has an immediate consequence: the test runner uses it. A server
whose CapabilityStatement advertises system-level cache-control will have each test suite's setup
resources front-loaded with mode=start and then referred to by url under the returned cache-id,
instead of being re-sent with every request. The runner does not pass sealed, so it takes the
server's default, which SHOULD be true - a sealed cache holding exactly the suite's setup§112. A server
that advertises the operation but does not implement it correctly will fail the whole suite rather than
one test, so declare it when it works, not before.
cache-id output parameter of
a mode=start call§113. A client does not invent one. This is what makes it possible for the server to
say authoritatively whether a cache-id it is handed is one it actually hasX-Cache-Id HTTP header, not as an
operation parameter, so that it is transport metadata: readable by proxies and load balancers, and
by the server before the body is parsedmode=start response SHALL report sealed, so that a client never has to assume a default§115start call.
Resources sent inline on later requests are used for that request and SHALL NOT be added to the cache§116sealed = false) SHALL accumulate each resource the server sees under that
cache-id - whether sent as tx-resource or as the primary valueSet / codeSystem - the first time
it is seen, and resolve it by reference thereafter§117The three cases - never issued, released, timed out - are indistinguishable to the client unless the server distinguishes them, so:
$validate-code, $expand or any other operation carries an X-Cache-Id the server does
not have, the server SHALL fail the request with HTTP 404 and an OperationOutcome whose issue
carries cache-id-unknown from http://hl7.org/fhir/tools/CodeSystem/tx-issue-type§118. It is the
coded issue, not the status, that a client keys on: cache-id-unknown means the client's cache
is gone and it should start a new one, where an unknown value set is an authoring error. A server
that reports a lost cache as a content error sends implementers hunting for a mistake that is not
theremode=end for a cache the server does not have SHALL NOT be an error§119. It returns HTTP 200, because
the client's intent - that the cache be gone - is already satisfiedA client can depend on a server-side cache it has not used for a long time, because its own local cache
is answering everything; the failure then shows up as the first rare code that does reach the server,
long into a build. mode=check exists for this.
mode=check SHALL return HTTP 200 whatever the answer§121 - it is not an error to ask about a cache
that is gone. A client polling its cache has to be able to tell "the server is up and says my cache
is gone" from "I could not reach the server": the first means start a new cache, the second means
retry, and collapsing them into a failed request loses exactly thatvalid = true and sealed, and SHOULD carry
resource-count and idle§122 (the idle time as it was before the check reset it)timeout, the server's idle timeout in seconds, where the server is
willing to state one§123. A client has no other way to discover it, and without it can only guess at how
often to checkvalid = false and an outcome
parameter holding an OperationOutcome with the same cache-id-unknown issue that a request using
the cache-id would have failed with§124url + version - front-loaded at
start, and again on later requests - and the server SHALL tolerate it§126. A client is not expected to
track what it has already registeredurl + version is required to be identical, so a server MAY treat
any copy as authoritative - first, last, or any other§127. A server MAY verify that repeated copies
match and reject a request that redefines a url + version with different content, but a client
SHALL NOT rely on that check being made§128expansion
has that expansion cached as suppliedtx-resource or as an entry's primary valueSet / codeSystem -
SHALL be populated into the cache before any entry is evaluated. An entry may therefore refer by
url to a resource supplied by a different entry, whatever order the two appear in, and population
SHALL NOT depend on whether individual entries succeeded§129. The batch's effect on the cache is
all-or-nothing at the level of the batch, not the entry. None of this applies to a sealed cache,
which does not growCaching does not change which version a versionless reference resolves to, but it makes a disagreement about it both more durable and harder to see.
(suites: simple-cases, parameters, properties, exclude, search, notSelectable, inactive,
deprecated, fragment, big, overload, other, errors, default-valueset-version, version,
regex-bad, language)
url, by valueSet (a resource in the request), or by
a resource passed in tx-resource and named by url§131ValueSet.expansion.parameter§132used-codesystem expansion
parameter with the value {url}|{version}. Where a supplement was used, Servers SHALL also report
used-supplement§133; where another value set was imported, used-valueset. This is how a client knows
what the expansion actually depended onexpansion.identifier and expansion.timestamp§134expansion.total where it knows the total§135excludeNested, which forces a flat expansion§137include is skipped, not an error: the expansion contains
the codes that do exist, and no issue is raisedcount and offset§139. offset is used by the ecosystem's clients only with
the value 0, but both are testedactiveOnly, includeDesignations, includeDefinition, property and
designation§140designation value is a token: system|code, or a bare code, which SHALL match a designation whose
language is that code or whose use has that code (in any system)§141. designation=nl-NL is the same as
designation=urn:ietf:bcp:47|nl-NL. A language matches exactly: de-CH does not select de designationsdisplayLanguage, and the Accept-Language header, and
ValueSet.language§142, as specified in Languagesfilter (text search)§143. The ecosystem makes no requirements about the
quality of the text search - only that the parameter is supported and that obvious matches are
found and obvious non-matches are not (suite: search) (the search tests require only that exact matches are found)abstract in the sense described under notSelectable§144default-valueset-version, which supplies a version for imported value sets that are referenced without one§145. Where a default-valueset-version is supplied and names a value set version that does not exist, the server SHALL return an error rather than silently falling back§146
(suite: default-valueset-version) The server SHALL support all the filters defined in the base specification, for all the code systems it
supports, and SHALL observe the distinctions between them (suites: simple-cases, tho)§147:
is-a includes the code named in the filter as well as everything below itdescendent-of excludes the code named in the filter - that is the only difference from is-ais-not-a excludes the code named in the filter and everything below it; everything else in the
code system, including the code above it and other branches, is includedchild-of includes the direct children only, and not the code named in the filter=, in, not-in, exists and regex on concept propertiesregex filter SHALL match the whole value§148 - the code, the property value or the display it is
applied to - not just part of it, for every code system: the pattern is treated as
^(?:pattern)$. So code2|code3 selects the codes code2 and code3, and not code2a (anchoring
the pattern as ^code2|code3$ gets this wrong); .*glucose.* finds values that contain "glucose",
glucose only a value that is exactly that (tests: simple-expand-regex,
simple-expand-regex-alt, snomed-expand-display-regex)parent /
subsumedBy property. A code system may state more than one parent for a concept, which nesting
cannot express, and the filters SHALL honour all of them§149(suite: properties)
property parameter, or with ValueSet.compose.property in the value set definition - the server SHALL return them, unless it does not know them§151ValueSet.compose.property SHALL be supported in both its forms: an enumerated list of property codes, and * meaning every property the code system defines§152ValueSet.expansion.property§153, giving each
one's code and, where it has one, its canonical uriValueSet.expansion.contains.property§154ValueSet.expansion.property declares the properties of the codes the expansion returns. An
expansion that returns no codes - count=0, asking only for the total - needs no declarations, but MAY
have them§155 (a server may declare the properties of the whole value set, e.g. status because it has
inactive codes); the test cases accept eitherValueSet.compose.property, ValueSet.expansion.property and ValueSet.expansion.contains.property do not exist as elements. An R4 server SHALL read and write them as the cross-version extensions http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.compose.property, http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.property and http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property§156. This
is a requirement, not an option: an R4 server that ignores the request or drops the response is
not conformant. R4 and the Test Cases has worked examples of
bothcompose.exclude in all its forms: excluding enumerated codes, excluding by
filter, and excluding by importing another value set (suite: exclude)§157overload)system-version parameter is also supplied, it is only a default, and SHALL NOT override a version the value set states explicitly§159(suites: validation, version, language2, permutations, overload, notSelectable, inactive,
deprecated, errors, fragment, other, tho)
code + system (+ version) (+ display), Coding, and
CodeableConcept§160. A CodeableConcept SHALL be validated as a whole: the result is true if any of its
codings validates, and the issues report what was wrong with the others§161valueset-membership-only§162, which restricts the check to whether the code is in
the value set (not its display, status, and so on)$expand)inferSystem is true and the value set contains the same code in two code systems, the server SHALL report the ambiguity as an error rather than choosing one§165lenient-display-validation, and SHALL distinguish the two answers: with it set, a display that is wrong but recognisable produces a warning; without it, an error§166abstract§167, which says whether the caller will accept a code that is not
selectableReturn parameters:
issues parameter with paths to the actual locations so a validator can locate the issue correctly§169http://hl7.org/fhir/tools/CodeSystem/tx-issue-type system, and helps validators process the errors correctly§170. The diagnostics property may be populated; this is ignored by the test casessystem and code parameters)display parameter)§173 but this is not always possible (e.g. some codes do not have displays) or required for some causes of validation failurex-caused-by-unknown-system parameter for each code system it did not support§174. This helps validators inform users of missing resourcesnormalized-code parameter where appropriate§175 (e.g. case insensitive code systems, code systems with complex grammars)processing-note when it has not fully validated the code§176 (e.g. when an SCT expression is not validated against the MRCM) The difference between "this code is not valid" and "this code is not in this value set" is a real one,
and the tx-issue-type coding SHALL say which: invalid-code for the first, not-in-vs for the
second. A message SHALL name both the code and the value set or code system it was checked against§177.
The same rules apply, less the value set. CodeSystem/$validate-code is tested separately throughout
(the test cases call it cs-validate-code), because a server can get one right and the other wrong.
result = false with
an invalid-code issue, not an error(suite: batch)
$validate-code request carrying repeated validation
parameters, each one a Parameters resource describing one code to validate§178. This is what makes
validating a large resource affordable$batch-validate-code, on both ValueSet and CodeSystem, and each entry means
what it would mean to that type's $validate-code: on CodeSystem, url names the code system, and an
entry with no url is validated against the code system its coding / codeableConcept namesurl, tx-resource, lenient-display-validation
and so on - apply to every validation in the batchvalidation overrides the top-level one for that validation
onlyvalidation parameter for each one in the request, in the same
order, each holding either the Parameters that $validate-code would have returned, or an
OperationOutcome where that one validation could not be performed§179(suites: simple-cases, parameters, omop, UCUM, icd-11, snomed)
display, and the name of the code system, and its version§181property parameter, including property=*, which asks for every
property the code system defines for the concept§182property=* is asked for, the server SHALL return definition, the hierarchy (parent and
child properties), and the standard concept properties it knows - inactive, notSelectable,
status - as well as the code system's own properties, at its discretion§183use and, where known, their language§184abstract§185code SHALL be echoed as it was asked for, not normalised. Where the server normalises the code, the
normal form belongs in the code property§186, which is what that property is forOperationOutcome§187(suites: simple-cases, tho, snomed, UCUM, mimetypes, langcodes, tx.fhir.org)
$subsumes on CodeSystem, in both forms: system + codeA + codeB,
and codingA + codingB§188outcome parameter with one of equivalent, subsumes,
subsumed-by, not-subsumed, or unknown§189equivalent SHALL be returned when the two codes are the same code, and when they are two spellings
of the same thing in a code system whose grammar makes that possible§190subsumedBy or parent property rather than by nesting, the server SHALL read it, including where a concept has more than one parent§192not-subsumed. So are
two parents of the same codeOperationOutcome. The message SHALL
name the code and the code system§193(suites: translate, translate2, omop, tx.fhir.org)
A server that holds ConceptMaps SHALL support ConceptMap/$translate§195. This section is new, and the
tests are correspondingly more detailed than the text; where they disagree, the tests are right.
sourceCode + sourceSystem, as sourceCoding, or as
sourceCodeableConcept§196code + system, coding and codeableConcept, and the
target system is targetsystem (lower case s) rather than targetSystem. An R4 server SHALL accept
the R4 names§197targetSystem, and SHOULD accept targetScope (target in R4), to
constrain what the answer may be§198url, the server SHALL use that map and no other§199. Naming a map
does not exempt it from the scope rule below: a client cannot put an out-of-scope code into a map's
scope by nominating the map, so the answer is still that the map does not applysourceScope and
targetScope fit the request, and use them. A server MAY decline to do this - not every server is
willing to choose a map on the client's behalf - in which case Servers SHALL say so rather than returning
an empty result§200sourceScope.
sourceScope limits the scope of the map, so a code outside it is not the map's business at all:
the map is not a candidate - whether the server chose it or the client named it - and in particular
its unmapped SHALL NOT fire for that code§201. Were it otherwise, a map with unmapped mode = fixed
would answer for every code in the code system its group names, whatever its author declared, and
sourceScope would have no effect on any map that has an unmapped - which is most of themoriginMap, as {url}|{version}§202, the map the server entered - not
the map that ultimately supplied the value. Where a delegation was followed, the match belongs to
the delegating map. In R4 this parameter is named source result SHALL be true where any valid mapping was found, and false where none was. There are three
different negative answers, and a server SHALL distinguish them§203:
result |
match |
|
|---|---|---|
| a map applies and says explicitly that there is no mapping | true |
one, with noMap = true and no concept |
a map applies, has no element for the code, and its unmapped fires |
true |
the unmapped concept |
| no map applies at all | false |
none |
The third is a successful operation with a negative answer, so it returns HTTP 200 with a message
saying why - not a 4xx
match parameter, whose parts are concept (the target Coding),
relationship, originMap, and sourceConcept (the Coding that was translated)§204. In R4 the
relationship is reported in equivalence, using the R4 codes (equivalent, narrower, wider,
relatedto …), and the R5 relationship element SHALL NOT be present§205; in R5 it is the other way
roundsourceComment SHALL be returned where the ConceptMap element carries a comment§206normalized-concept in the match: the same concept as a Coding in the code system's normal form -
the same normal form $validate-code reports in normalized-code. concept is still the target
as the map states it§207. This applies to any code systemnote part saying that the code
system is not known and the code has not been validated§208. Where the target code is not valid in its
code system, the match is still returned as the map states it, and the response SHALL carry an
error parameter saying that the target code is not valid - one for each such target§209. (A code
system whose content is a fragment cannot say a code is not in it, so neither applies there)noMap in R5, a target with no
code in R4 - the server SHALL return a match with noMap = true and no concept, and
result = true§212. "There is definitively no mapping" is an answer, not a failureunmapped answers the question "this map covers the code, but has no element for it". A code that
is outside the map's sourceScope is not covered at all, and is disposed of by the scope rule above
rather than by unmappedConceptMap.group.unmapped in its modes§213:
fixed: any code not otherwise mapped translates to the stated codeother-map: the translation is delegated to the named ConceptMap, and used-conceptmap reports ittargetCode,
targetCoding or targetCodeableConcept. The reverse parameter does not exist in R5, and a server
that receives Servers SHALL return a 4xx with a not-supported issue rather than guessing what was meant§214reverse parameter does exist, and an R4 server SHALL support it, as well as the
targetcode form§215$closure is tested by the closure suite, and its requirements are not yet written up here.
The $compare operation - determining whether two value sets are equivalent, or one a subset of the
other, or they overlap, or they are disjoint - is being trialled on tx.fhir.org. It is not a
requirement for registration in the ecosystem, and its tests are gated behind the tx.fhir.org mode.
This section will be written when the operation is settled.
(suites: version, overload, default-valueset-version, valueset-version)
Version handling is the largest single body of tests in the suite, because it is where servers most often differ. The rules:
used-codesystem for $expand, and the version parameter for $validate-codesystem-version supplies a default. Anything the value set states explicitly overrides itforce-system-version overrides the value setcheck-system-version SHALL produce an error where the value set asks for or resolves to a different version§218Code systems vary in whether codes and/or designations can be labelled as inactive, and if they do, how it is done. SNOMED CT defines 'inactive' explicitly. For other Code Systems, codes or designations are labelled as 'should not use' in any fashion, they are regard as inactive.
For the CodeSystem resource:
If a concept is defined as inactive:
If a designation is defined as inactive:
A concept may also be deprecated or withdrawn by the value set rather than by the code system, using
the valueset-deprecated or standards-status extension on ValueSet.compose.include.concept. A
server SHALL honour that too§225, and report it in the same way (suite: deprecated).
Not-selectable is a different thing again: the code exists and is valid, but it is not meant to be used
in an instance (suite: notSelectable).
http://hl7.org/fhir/concept-properties#notSelectable with the value true - see
Concept Properties for how that property is recognisednotSelectable SHALL be usable as a filter, with both the = and the in operators§226abstract§227$validate-code SHALL accept a not-selectable code only where the request says it will take one:
with abstract = true the code validates, and without it the server SHALL report that the code is
not selectable§228The listed extensions SHALL be supported§230:
http://hl7.org/fhir/StructureDefinition/codesystem-alternate - if code system has alternate codes (TODO: this is subject to further discussion)http://hl7.org/fhir/StructureDefinition/codesystem-conceptOrder - if code system has order, then this SHOULD be echoed§231 (nothing else needed)http://hl7.org/fhir/StructureDefinition/codesystem-label - if code system supports 'labels', then this SHOULD be echoed§232 (nothing else needed)http://hl7.org/fhir/StructureDefinition/coding-sctdescid - if sct is in scope (exact use cases need discussion)http://hl7.org/fhir/StructureDefinition/itemWeight - echo in value set if defined in code system or value sethttp://hl7.org/fhir/StructureDefinition/rendering-style - echo in value set if defined in code system or value sethttp://hl7.org/fhir/StructureDefinition/rendering-xhtml - echo in value set if defined in code system or value sethttp://hl7.org/fhir/StructureDefinition/valueset-concept-definition - populate if requested in expansion requesthttp://hl7.org/fhir/StructureDefinition/valueset-deprecated - populate in the response if code system concept is deprecatedhttp://hl7.org/fhir/StructureDefinition/valueset-supplement - check for this, blow up if supplement is properly supportedhttp://hl7.org/fhir/StructureDefinition/valueset-label - echo in value set if defined in code system or value sethttp://hl7.org/fhir/StructureDefinition/valueset-conceptOrder - echo in value set if defined in code system or value sethttp://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status - may be found on either a concept or a concept designation. The status codes 'withdrawn' and 'deprecated' mean that the concept / designation is inactive. In addition, it might be found on a ValueSet.compose.include.concept to indicate that the concept's inclusion in the value set is deprecated/withdrawn etcNote that some of these extensions may be supported by rejecting instances that contain them, depending on the specific use cases that the server supports. E.g., if the server does not support externally derived code systems then the code system extensions are not relevant.
In R4, several R5 elements are carried as cross-version extensions. Those are not optional either - see
R4 and the Test Cases, and ValueSet.compose.property above.
The requirements above apply to every server. The requirements below apply only to a server that supports the code system in question, and each corresponds to a mode in the test runner. A server declares which of these apply to it by the modes it asks to be tested in; a server that claims a mode SHALL pass that mode's tests§233.
(mode: snomed; suites: snomed, sct-ecl)
The SNOMED tests run against a fixed test subontology, not against a real edition: it is published in
the tx-source directory of this IG's repository, under the edition
http://snomed.info/xsct/31000003106. A server that claims the snomed mode SHALL load it, because
the tests assert specific concepts, displays and counts that only that subontology has§234.
?fhir_vs (all of SNOMED), ?fhir_vs=isa/{sctid}, ?fhir_vs=refset/{sctid} and ?fhir_vs=ecl/{expression}§235. Where the implicit value set names a refset or a concept that does not exist, the server SHALL return an error naming the value set that was asked for§236
?fhir_vs=ecl/ is URL-encoded in the value set URL, as the SNOMED CT on FHIR page
writes it (test: snomed-expand-implicit-ecl)http://snomed.info/sct?fhir_vs... form, and the server SHALL draw the value set from the
edition and version so named§237:
http://snomed.info/sct/{edition}?fhir_vs... - the latest version of that edition the server
has (test: snomed-expand-implicit-edition)http://snomed.info/sct/{edition}/version/{date}?fhir_vs... - that version (test:
snomed-expand-implicit-version)http://snomed.info/sct?fhir_vs... - the edition and version the request asks for with
force-system-version, system-version or check-system-version, where it asks; otherwise the
server's default edition (tests: snomed-expand-implicit-system-version,
snomed-validate-implied-refset-map). This includes the check that the concept or reference
set the URL names exists: a concept that is only in the edition the request asks for is found.
An edition or version named in the URL itself is not overridden by these parametersconcept filter with in, is-a, descendent-of, descendent-leaf,
is-not-a and child-of, and the SNOMED-specific expressions filter§238:
descendent-leaf is the descendants of the concept that have no children of their own; the
concept itself is never included (test: snomed-expand-descendent-leaf)in takes a comma-separated list of concepts, and means any of them (tests:
snomed-expand-concept-in, snomed-validate-concept-in). A listed concept that is a reference
set stands for its members (not yet tested)code as the same filter property as concept§239: value sets in
production use the two interchangeably (tests: snomed-expand-code-in, snomed-validate-code-in)display filter with the regex operator§240 - published value sets
(VSAC among them) select SNOMED CT concepts this way. Since a concept has many descriptions, possibly
in many languages, the filter is defined as follows (tests: snomed-expand-display-regex,
snomed-validate-display-regex, snomed-expand-display-regex-nl):
regex filter (see Filters) -
.*hematoma.* finds terms that contain "hematoma", hematoma only a term that is exactly that -
and the match is case-sensitivedisplayLanguage parameter, or if there is none, the HTTP Accept-Language header - that the
edition has descriptions in; if the request names none of the edition's languages, or no language
at all, the edition's default language (English for the International Edition and for the test
edition). Descriptions in other languages SHALL NOT be searched§241, even where they would match.
So the same value set, expanded with displayLanguage=nl against an edition that has Dutch
descriptions, matches Dutch terms and not English onesexpressions = false, a well-formed expression SHALL be rejected as not
in the value set§243, even where its focus concept is in the value setexpressions = true, a well-formed expression whose focus concept is in
the value set SHALL be accepted§244$validate-code on an expression SHALL check the expression against the machine-readable concept
model (MRCM) where the server has it§246, and report a violation as an error: an attribute outside its
domain, a value outside its range, an attribute used more times than its cardinality allows, an
ungrouped attribute written inside a relationship group, laterality on a body structure
that is not in the lateralizable reference set, and the concrete-value rules (a concrete value where
a concept is required, or the reverse, and concrete values outside their stated range)40468003:363698007=10200004 is
equivalent to 40468003:{363698007=10200004} for validation, rendering and subsumption§247processing-note issue
rather than silently passing it§248$subsumes SHALL work between expressions, and between an expression and a precoordinated concept,
in both directions. Where the structure of the two expressions does not settle the question - they
refine different attributes, or the same attribute with unrelated values - the server SHALL return an
error saying it cannot determine the relationship. Finding no relationship is not the same as
establishing that there is none, and the server SHALL NOT report not-subsumed in that case§249$subsumes SHALL reject an expression that is not valid under the MRCM rather than answering it§250$lookup SHALL return the properties the SNOMED CT on FHIR page defines§252, under the names it gives
them (the module is moduleId):
property=* SHALL return all of them - parent, child, the defining relationships,
effectiveTime, inactive, moduleId, sufficientlyDefined and semanticTag - except the
normal forms§253 (test: snomed-lookup-all-properties)normalForm and normalFormTerse are computed, and SHALL be returned only when they are asked
for by name§254: not by default, and not for property=* (test: snomed-lookup-normal-form)parent and child are the
direct onesvalueString
for a string and valueBoolean for a boolean. A number SHALL be typed by the attribute's range in the
MRCM: valueDecimal where the range is dec(...), and valueInteger where it is int(...). RF2
writes both kinds the same way, so the value doesn't decide the type: #4000 for a presentation
strength numerator (a dec() attribute) is the decimal 4000, and #1 for count of base of active
ingredient (an int() attribute) is the integer 1. Only where the MRCM gives the attribute no range
is a number with a decimal point a decimal, and one without an integer§255
(test: snomed-lookup-concrete)Note: The SNOMED Computable Languages Group (meeting of 19 October 2026, at the SNOMED International
business meetings) agreed the support that ecosystem servers are required to provide for post-coordinated
expressions. The full set is recorded here so that implementers know what is coming; the items marked
(not yet tested) are not yet enforced by the test cases, and will be added to the snomed suite as the
tests are written. Where they bear on the rules above, the rules above already say how the tests check
them.
A server that supports SNOMED CT SHALL meet the minimum requirements§256:
$validate-code§257 (as described above)$validate-code on a valid
expression SHALL return a display that a human can read§258expressions = false admits post-coordinated expressions, and for such a value set the server MAY generate post-coordinated expressions in the expansion§260, but is never required to: a server that returns only precoordinated concepts (and any expressions the value set enumerates) is conformant$translate to and from post-coordinated expressions, catering for the normal form§262: a map target or source that is written in a different but equivalent form SHALL still be matched§263*$subsumes, correctly determine when one post-coordinated expression is subsumed by another, or by a precoordinated concept, by simple structural rules. The server SHALL NOT wrongly claim that expressions are or are not subsumed, and MAY (and generally SHOULD) answer that subsumption cannot be determined where the structural rules do not settle it§265. Servers are not expected to base their subsumption reasoning on an OWL classifier (as described above)(mode: loinc; suite: loinc)
The LOINC tests depend on which LOINC release and accessory files the server has loaded. They are
written against LOINC 2.83, and every request names that version - version in $lookup,
$subsumes and $validate-code on the code system, systemVersion in $validate-code on a value set,
system-version in $expand, and the version of the source Coding in $translate. The behaviour tested covers the LOINC properties (COMPONENT,
METHOD_TYP, ORDER_OBS, SCALE_TYP, CLASS), STATUS, the parent/child hierarchy, answer lists,
parts, and the answers-for and answer-list filters.
Answer lists (as agreed with LOINC, UP-645):
http://loinc.org/vs/[LL code], in $expand and $validate-code§266answers-for = code: all the answers (LA) in the answer list associated with the code, which is either the answer list itself (LL) or a LOINC term that has an associated answer list§267answer-list = code: all the answer lists (LL) that the answer (LA) is in§268LIST = [LL code] is tx.fhir.org's own name for answers-for with an answer list code. tx.fhir.org only supports it for backwards compatibility, and the tests for it only run in tx.fhir.org mode. Other servers do not need to support itProperty values and property filters (this clarifies the UTG LOINC page,
which lists the filter value for every property as [string value]):
code (or Coding) property it is the code, and for a string property it is the stringCOMPONENT, PROPERTY, TIME_ASPCT, SYSTEM, SCALE_TYP and METHOD_TYP - SHALL be
code properties whose value is the LOINC Part code (e.g. SCALE_TYP = LP7753-9, not Qn), in $lookup and
in property filters§269SCALE_TYP = Qn)§270. This is not
the correct value, but it is so widespread in existing value sets that all servers are required to support itCLASS SHALL be a string property whose value is the class name (e.g. PULM), in $lookup and in property
filters§271. A server MAY also return the Part code for the class in $lookup, as a partCode part of the property
(an informal extension)CLASS filter (e.g. CLASS =
LP7840-4)§272, for the same reasonHierarchy and implicit value sets:
ancestor filter (= and in, the value a Part code) on the multi-axial hierarchy§273:
ancestor = X is every code X subsumes, transitively - terms and parts, but not X itself (it is the same set as
concept descendent-of X). in is the union over the listed partshttp://loinc.org/vs/[partcode]§274,
which the UTG LOINC page defines as a single include with the filter
ancestor = [partcode](mode: tx.fhir.org at present; suite: UCUM)
$lookup SHALL work for a UCUM expression§277, including one carrying an annotation$subsumes on UCUM SHALL report equivalent for two spellings of the same unit - a named derived
unit and the expression it is defined as§278, a unit with and without an annotation - and
not-subsumed otherwise. UCUM has no hierarchy, so a scaled unit is not subsumed by the unit it
scales, two units sharing a canonical unit but differing in magnitude are not related, and neither
are two dimensionless units that differ only in magnitude$subsumes request SHALL produce an error§279(mode: mimetypes; suite: mimetypes)
Media types have no hierarchy between types and subtypes, but parameters narrow a media type, and that is what makes subsumption meaningful.
base filter, selecting by type (text) or by type and subtype
(text/plain). Parameters on a code SHALL NOT stop it matching a base filter§280registered filter, selecting media types that are or are not in the
IANA registry§281base filter or registered=false:
those are unbounded, and the server SHALL answer too-costly rather than returning a partial
expansion presented as complete. registered=true can be expanded, narrowed by a base filter, and
SHALL be marked as an unclosed expansion§282$subsumes SHALL treat a media type carrying a parameter as subsumed by the same type without it,
and a parameter set as subsumed by a superset of it. Media types are case-insensitive§283text/plain and text/plain; charset=us-ascii are equivalent, and text/plain and
text/plain; charset=utf-8 are not-subsumed - the parameter contradicts the default rather than
narrowing it(mode: tx.fhir.org at present; suite: langcodes)
QM..QZ) SHALL be accepted§286normalized-code and note the difference§288$subsumes SHALL implement RFC 4647 extended filtering: a tag subsumes any tag that adds subtags to
it, including where the added subtag sits between two the shorter tag names (en-US subsumes
en-Latn-US)§289. A grandfathered tag subsumes nothinglanguage, region and script filters§290. An absent component does not
match a fixed one: a tag with no region is not in a region=US value set, and a tag with no script
is not in a script=Latn value set, even where that is the script the language is written inlanguage filter is finite and SHALL be expandable (paged). A region filter alone is finite but far too large, and a script filter alone leaves the language open: both SHALL answer too-costly. Expanding all language codes SHALL return the common-languages base value set, marked as unclosed§291(mode: omop; suite: omop)
The OMOP tests are based on a stable subset maintained for the ecosystem. Some servers support only OMOP, and the tests are written so that they can.
code+system, Coding and CodeableConcept, with and
without a value set, and SHALL check both the display and the version§292$lookup SHALL work for standard OMOP concepts. A non-standard concept may be looked up or refused,
depending on the server§293(mode: icd-11; suite: icd-11)
The ICD-11 tests assert correct FHIR behaviour rather than the behaviour of any particular server, and
the ICD documentation explains each one. Three code systems are in play, each
with its own canonical: the Foundation (http://id.who.int/icd/entity), the MMS linearization
(http://id.who.int/icd/release/11/mms) and ICF (http://id.who.int/icd/release/11/icf).
$lookup and $validate-code against each of the three, by code and by
entity URI, including grouper concepts and residual categories§295$lookup SHALL echo code as it was asked for§296. A request by entity URI gets the entity URI back;
the normalised short form belongs in the code property$lookup and $validate-code, including
clustered and repeated axis values, and SHALL reject an invalid axis§297count, offset and
filter§298