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
| Id | Expectation | Rule |
|---|---|---|
| SHALL SHALL NOT MAY SHOULD SHOULD NOT | ||
| §1 | SHALL | The standard discovery parameters SHALL be supported by all servers |
| §2 | SHALL | The standard resolution parameters SHALL be supported by all servers |
| §3 | SHALL | All endpoints listed in the server registration file SHALL return CapabilityStatement and TerminologyCapabilities resources that conform to the requirements described in this IG |
| §4 | SHALL | A server making language specific claims SHALL host the content of the claimed code systems
(complete or fragment) as well as the relevant supplement(s) |
| §5 | SHALL | Servers SHALL support all four approaches to specifying languages |
| §6 | SHALL | Clients SHALL resolve the display language (from the four sources above, in priority order) before server selection |
| §7 | SHALL | The language used for routing and the language used in the subsequent operation SHALL be the same |
| §8 | SHALL | The server SHALL either support the $versions operation at the root, or return a CapabilityStatement from /metadata that populates CapabilityStatement.fhirVersion |
| §9 | SHALL | The server SHALL support either R4 or R5 |
| §10 | SHALL | The server SHALL be consistent: the version it reports is the version in which it will accept requests and return responses |
| §11 | SHALL | The server SHALL support the JSON format (application/fhir+json) |
| §12 | SHALL | The server SHALL accept operation parameters as a Parameters resource POSTed to the operation endpoint |
| §13 | SHALL | The server SHALL return HTTP 200 when the operation completed |
| §14 | SHALL | The server SHALL return a 4xx status with an OperationOutcome when it could not carry out the operation at all |
| §15 | SHALL NOT | The server SHALL NOT return a 5xx status for any of the test cases |
| §16 | SHALL | Each issue SHALL have severity, code, details.coding, and details.text |
| §17 | SHALL | details.coding SHALL include a coding from http://hl7.org/fhir/tools/CodeSystem/tx-issue-type |
| §18 | SHALL | Issues that relate to a particular part of the request SHALL carry expression naming it |
| §19 | MAY | diagnostics MAY be populated |
| §20 | MAY | Servers MAY populate the http://hl7.org/fhir/StructureDefinition/operationoutcome-message-id extension |
| §21 | SHALL | Where an expansion would be larger than the server is prepared to produce, the server SHALL return a 4xx with an issue whose tx-issue-type is too-costly |
| §22 | SHALL | Where a value set's imports are circular, the server SHALL detect it and return a 4xx with an issue whose tx-issue-type is vs-invalid |
| §23 | SHALL NOT SHALL | Where a regex filter is capable of catastrophic backtracking, the server SHALL either evaluate it safely and return the right answer, or refuse the request with an error. Servers SHALL NOT hang |
| §24 | SHOULD | The server SHOULD support $versions at the root, returning the FHIR versions it supports |
| §25 | SHALL | If the server supports $versions, Servers SHALL declare it in CapabilityStatement.rest.operation |
| §26 | SHALL | Server SHALL return a CapabilityStatement from {root}/metadata |
| §27 | SHALL | Servers SHALL populate url, version, name, title, status (active), date, and kind (instance) |
| §28 | SHALL | Servers SHALL populate software.name, software.version and software.releaseDate. The name is what the test runner uses to identify the server in its output |
| §29 | SHALL | Servers SHALL populate fhirVersion, and rest[mode = server].security.service |
| §30 | SHALL | Servers SHALL include application/fhir+json in format |
| §31 | SHALL | Servers SHALL include a CapabilityStatement.instantiates value of http://hl7.org/fhir/CapabilityStatement/terminology-server |
| §32 | SHALL | Servers SHALL declare, under rest.resource for CodeSystem, the operations lookup, subsumes and validate-code |
| §33 | SHALL | Servers SHALL declare, under rest.resource for ValueSet, the read and search-type interactions and the operations expand and validate-code |
| §34 | SHALL | Where the server supports the caching protocol, Servers SHALL declare the cache-control operation at the system level in rest.operation |
| §35 | SHALL | Servers SHALL carry a feature extension for CodeSystemAsParameter, saying whether the server accepts CodeSystem resources in the tx-resource parameter. The feature SHALL be present; its value may be true or false |
| §36 | SHALL | Servers SHALL carry a feature extension reporting the version of the test cases the server passes |
| §37 | SHALL | The server SHALL return a TerminologyCapabilities from {root}/metadata?mode=terminology |
| §38 | SHALL | Servers SHALL populate version, name, title, status and date |
| §39 | SHALL | Servers SHALL list every code system it supports in TerminologyCapabilities.codeSystem.uri, with the versions in codeSystem.version.code. Code systems SHALL be listed here whether or not they are available through /CodeSystem search |
| §40 | SHALL | Servers SHALL list, in expansion.parameter, at least the parameters activeOnly, check-system-version, count, displayLanguage, excludeNested, force-system-version, includeDefinition, includeDesignations, offset, property, system-version and tx-resource |
| §41 | SHOULD | Servers SHOULD also list any of the optional parameters it supports there, in particular default-valueset-version |
| §42 | SHALL | The TerminologyCapabilities SHALL list all the predefined code systems that the server supports in 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 |
| §43 | SHOULD | The server SHOULD make all the code systems it supports available through the /CodeSystem endpoint for search and read operations |
| §44 | SHALL | The server SHALL support the url and version search parameters |
| §45 | MAY | CodeSystems available at /CodeSystem MAY have content = not-present |
| §46 | SHOULD | Servers SHOULD generally allow multiple resources for the same canonical URL with different Resource.version |
| §47 | SHOULD | Servers can choose to support update/create if they want, though it SHOULD only do so for authenticated clients |
| §48 | SHALL | Servers SHALL ensure that they only send correct results for the code systems for which they is registered as 'authoritative' |
| §49 | SHALL | All predefined code systems SHALL have a web representation that is appropriate for a human to look at |
| §50 | SHALL | General purpose servers SHALL accept CodeSystems (and are required to do this to pass the general tests) |
| §51 | SHALL | Servers SHALL indicate their support or not for passing CodeSystem resources in the tx-resource parameter using the CodeSystemAsParameter feature in the CapabilityStatement |
| §52 | SHALL | Terminology servers SHALL support passing CodeSystem supplements, particularly language packs |
| §53 | SHALL | Servers SHALL support global language packs, including as tx-resource parameters, except where CodeSystems do not allow this |
| §54 | SHALL | A server SHALL use a global language pack - passed in tx-resource, or loaded on the server - for the code system it supplements, whether or not the request or the value set refers to it |
| §55 | SHALL | A server SHALL report a global language pack as a used-supplement in $lookup and $expand when it contributes
a display or a designation |
| §56 | SHALL | Any other supplement SHALL only be used when it is referenced |
| §57 | SHALL | An expansion of a value set that includes all of a code system with reserved code spaces - whether or not any
supplements are in play - SHALL be marked as unclosed (valueset-unclosed), since codes in the reserved code
spaces are members of the value set ($validate-code accepts them) that the expansion can't list |
| §58 | SHALL | Servers intended to be used as the primary server for the validator and IG publisher SHALL accept CodeSystems in the tx-resource parameter |
| §59 | SHALL MAY | Servers SHALL not ignore supplements, though they MAY choose to return errors rather than process them correctly |
| §60 | SHALL | The server SHALL host the content of the claimed code systems (complete or fragment), not just the supplements |
| §61 | SHALL | The server SHALL support each claimed language for the code systems claimed under it: $expand, $validate-code, and $lookup SHALL return correct displays and designations in that language (typically via loaded supplements) |
| §62 | SHALL | CodeSystem.caseSensitive SHALL be supported: validation SHALL correctly check case |
| §63 | SHOULD | In the case of non-case sensitive code systems, expansions SHOULD just contain the code as defined |
| §64 | SHALL | If the code system defines a hierarchy, both $expand and $validate SHALL correctly handle the hierarchy when interpreting filters and validating codes |
| §65 | SHALL | A server SHALL not accept compositional grammars for codes unless the CodeSystem is marked as Compositional |
| §66 | SHALL | Servers that do not know the grammar for a CodeSystem that is marked as compositional SHALL note this in validation errors for the CodeSystem |
| §67 | SHALL | 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 |
| §68 | SHALL | Servers SHALL not process $expand or $validate-code requests on CodeSystems that have content = not-present or example |
| §69 | SHALL NOT SHALL | 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 |
| §70 | SHALL | Servers SHALL not mistake supplements and code systems for each other |
| §71 | SHALL | A number of concept properties defined at concept-properties change how a concept behaves, and a server SHALL honour them |
| §72 | SHALL | Where the CodeSystem declares the property with the canonical uri from concept-properties, the
server SHALL recognise it whatever local code the code system gave it |
| §73 | SHALL | Where the CodeSystem declares no property definition at all, the server SHALL recognise the property by its standard code |
| §74 | SHALL NOT | Where the CodeSystem declares the property with a different uri, it is a different property, and
the server SHALL NOT treat it as the standard one |
| §75 | SHALL | The server SHALL make all the predefined value sets it supports available through the /ValueSet endpoints for search and read operations |
| §76 | SHALL | The server SHALL support the url and version search parameters |
| §77 | SHALL | The server SHALL support the _summary search parameter |
| §78 | SHOULD | Servers SHOULD generally allow multiple resources for the same canonical URL with different Resource.version, but this is subject to business rules on the server |
| §79 | SHOULD | Servers can choose to support update/create if they want, though it SHOULD only do so for authenticated clients |
| §80 | SHALL | All predefined value sets SHALL have a web representation that is appropriate for a human to look at |
| §81 | SHALL | Servers SHALL accept ValueSets passed in the tx-resource parameter to both $expand and $validate-code operations |
| §82 | SHALL | Servers SHALL use these value sets when resolving imports in other ValueSet resources |
| §83 | SHALL | Servers SHALL indicate their support for passing ValueSet resources in the tx-resource parameter in TerminologyCapabilities.expansion.parameter |
| §84 | SHALL | Servers SHALL support ValueSet.compose |
| §85 | SHALL | Servers SHALL support ValueSet.compose.include and ValueSet.compose.exclude |
| §86 | SHALL | Servers SHALL support imported value sets |
| §87 | SHALL | Servers SHALL support extensionally defined value sets |
| §88 | SHALL | Servers SHALL support intensionally defined value sets |
| §89 | SHALL | Servers SHALL support all the filters defined in the base specification for all code systems |
| §90 | SHALL | Servers SHALL return an error if a ValueSet uses a filter they do not understand |
| §91 | SHALL | Servers SHALL only return an existing expansion if it is the correct expansion for the definition of the value set |
| §92 | SHALL | Servers SHALL support value sets that contain value sets, and SHALL resolve a reference of the form #id in
compose.include.valueSet or compose.exclude.valueSet to the contained value set with that id |
| §93 | MAY | Servers MAY reject resources that contain contained CodeSystems and ConceptMaps, but are not required to |
| §94 | SHALL | The server SHALL accept ConceptMap resources in the tx-resource parameter, and use them for
$translate requests in the same call |
| §95 | SHALL SHOULD | The server SHOULD make pre-defined ConceptMaps available through the /ConceptMap endpoint for read
and search, and SHALL support the url and version search parameters if it does |
| §96 | SHALL | The server SHALL support ConceptMaps that declare sourceScope / targetScope and ConceptMaps that
do not |
| §97 | SHALL | All pre-defined code systems, value sets and concept maps SHALL have a web representation |
| §98 | SHOULD MAY | The 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 |
| §99 | MAY | the server MAY choose to make additional process/provenance/context information available |
| §100 | MAY | The server MAY choose to make this content available at the end-point for the relevant resource |
| §101 | MAY | Servers are not required to do this; they MAY choose to make the content available elsewhere |
| §102 | SHALL | 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) |
| §103 | SHALL | The server SHALL support the tx-resource parameter for passing related terminology |
| §104 | SHALL | If a server receives a terminology resource it does not process correctly, Servers SHALL return an error |
| §105 | SHALL | The server SHALL support supplements for the purposes of designations in different languages |
| §106 | SHALL | Servers SHALL not ignore supplements; if they don't support a relevant supplement (per the rules above), they SHALL return an error that they cannot process the supplement |
| §107 | SHALL | The server SHALL support 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 |
| §108 | SHOULD NOT | 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 |
| §109 | SHALL SHOULD | Servers SHOULD support $cache-control. This is not yet a SHALL |
| §110 | SHALL | A server that supports Servers SHALL declare the cache-control operation at the system level in
CapabilityStatement.rest.operation |
| §111 | SHALL | The operation declares affectsState = true; servers SHALL accept start and end by POST |
| §112 | SHOULD | 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 |
| §113 | SHALL | The cache-id SHALL be allocated by the server, and returned in the cache-id output parameter of
a mode=start call |
| §114 | SHALL NOT | A server SHALL NOT honour a cache-id on an endpoint other than the one that issued it |
| §115 | SHALL | A mode=start response SHALL report sealed, so that a client never has to assume a default |
| §116 | SHALL NOT | A sealed cache - the default - holds exactly the resources front-loaded in the start call.
Resources sent inline on later requests are used for that request and SHALL NOT be added to the cache |
| §117 | SHALL | An unsealed cache (sealed = 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 |
| §118 | SHALL | Where a $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 |
| §119 | SHALL NOT | mode=end for a cache the server does not have SHALL NOT be an error |
| §120 | SHOULD | Servers SHOULD record why each cache-id they retired went away, and say which in the diagnostics |
| §121 | SHALL | mode=check SHALL return HTTP 200 whatever the answer |
| §122 | SHALL SHOULD | For a valid cache, the response SHALL carry valid = true and sealed, and SHOULD carry
resource-count and idle |
| §123 | SHOULD | The response SHOULD carry timeout, the server's idle timeout in seconds, where the server is
willing to state one |
| §124 | SHALL | For a cache the server does not have, the response SHALL carry valid = 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 |
| §125 | SHALL | A successful check counts as use, and SHALL reset the cache's idle timer |
| §126 | SHALL | A client may send the same resource more than once under the same url + version - front-loaded at
start, and again on later requests - and the server SHALL tolerate it |
| §127 | MAY | Every copy sent under a given url + version is required to be identical, so a server MAY treat
any copy as authoritative - first, last, or any other |
| §128 | SHALL NOT MAY | 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 |
| §129 | SHALL NOT SHALL | Where the server supports batches against an unsealed cache, every resource
supplied anywhere in the batch - as tx-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 |
| §130 | SHOULD | Content in the ecosystem SHOULD therefore pin versions explicitly on references between terminology resources wherever the exact version matters |
| §131 | SHALL | The server SHALL expand a value set given by url, by valueSet (a resource in the request), or by
a resource passed in tx-resource and named by url |
| §132 | SHALL | The server SHALL echo all parameters - including ones it assumed a value for - in
ValueSet.expansion.parameter |
| §133 | SHALL | The server SHALL report every code system version it actually used, as a used-codesystem expansion
parameter with the value {url}|{version}. Where a supplement was used, Servers SHALL also report
used-supplement |
| §134 | SHALL | The server SHALL populate expansion.identifier and expansion.timestamp |
| §135 | SHOULD | The server SHOULD populate expansion.total where it knows the total |
| §136 | SHOULD | The server SHOULD return hierarchical expansions when possible |
| §137 | SHALL | The server SHALL support excludeNested, which forces a flat expansion |
| §138 | SHALL | Where the expansion is knowingly incomplete - the underlying grammar is unbounded, or the server returned a base subset - the expansion SHALL be marked as unclosed rather than presented as complete |
| §139 | SHALL | The server SHALL support count and offset |
| §140 | SHALL | The server SHALL support activeOnly, includeDesignations, includeDefinition, property and
designation |
| §141 | SHALL | A designation 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) |
| §142 | SHALL | The server SHALL support displayLanguage, and the Accept-Language header, and
ValueSet.language |
| §143 | SHALL | The server SHALL support filter (text search) |
| §144 | SHALL | The server SHALL support abstract in the sense described under notSelectable |
| §145 | SHOULD | The server SHOULD support default-valueset-version, which supplies a version for imported value sets that are referenced without one |
| §146 | SHALL | 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 |
| §147 | SHALL | 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) |
| §148 | SHALL | A regex filter SHALL match the whole value |
| §149 | SHALL | Hierarchy SHALL be followed however the code system states it - by nesting, or by a 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 |
| §150 | SHALL | A filter the server does not understand, or a filter with no value where one is required, SHALL produce an error |
| §151 | SHALL | Where the expansion request asks for properties - with the property parameter, or with ValueSet.compose.property in the value set definition - the server SHALL return them, unless it does not know them |
| §152 | SHALL | ValueSet.compose.property SHALL be supported in both its forms: an enumerated list of property codes, and * meaning every property the code system defines |
| §153 | SHALL | The server SHALL declare the properties it returned in ValueSet.expansion.property |
| §154 | SHALL | The server SHALL return the values in ValueSet.expansion.contains.property |
| §155 | MAY | ValueSet.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 |
| §156 | SHALL | In R4, ValueSet.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 |
| §157 | SHALL | The server SHALL support compose.exclude in all its forms: excluding enumerated codes, excluding by
filter, and excluding by importing another value set (suite: exclude) |
| §158 | SHALL | The server SHALL support a value set that includes two versions of the same code system, and SHALL keep the versions distinct |
| §159 | SHALL NOT | Where an include names no version, the server resolves it to its default for that code system; where a system-version parameter is also supplied, it is only a default, and SHALL NOT override a version the value set states explicitly |
| §160 | SHALL | The server SHALL support validating code + system (+ version) (+ display), Coding, and
CodeableConcept |
| §161 | SHALL | 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 |
| §162 | SHALL | The server SHALL support valueset-membership-only |
| §163 | SHALL | The server SHALL support language correctly |
| §164 | SHALL | The server SHALL support the inferSystem parameter |
| §165 | SHALL | Where 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 |
| §166 | SHALL | The server SHALL support lenient-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 |
| §167 | SHALL | The server SHALL support abstract |
| §168 | SHALL | the server SHALL return a result parameter, along with a message summarising the reason why if result = false |
| §169 | SHALL | any errors and warnings SHALL be itemised in an issues parameter with paths to the actual locations so a validator can locate the issue correctly |
| §170 | SHALL | any issue entries in the OperationOutcome SHALL have a severity, type, expression, details.coding, and details.text. The coding SHALL be taken from the http://hl7.org/fhir/tools/CodeSystem/tx-issue-type system, and helps validators process the errors correctly |
| §171 | SHALL | the server SHALL return the code system and code against which validation was based |
| §172 | SHOULD | The server SHOULD return the version against which validation was based |
| §173 | SHOULD | The server SHOULD return a display for the code (display parameter) |
| §174 | SHALL | The server SHALL return a x-caused-by-unknown-system parameter for each code system it did not support |
| §175 | SHOULD | The server SHOULD return a normalized-code parameter where appropriate |
| §176 | SHOULD | The server SHOULD return an issue with tx issue type processing-note when it has not fully validated the code |
| §177 | SHALL | 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 |
| §178 | SHOULD | The server SHOULD support batch validation: a $validate-code request carrying repeated validation
parameters, each one a Parameters resource describing one code to validate |
| §179 | SHALL | A batch response SHALL contain one validation 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 |
| §180 | SHALL NOT | One bad validation in a batch SHALL NOT fail the batch |
| §181 | SHALL | The server SHALL return display, and the name of the code system, and its version |
| §182 | SHALL | The server SHALL support the property parameter, including property=*, which asks for every
property the code system defines for the concept |
| §183 | SHALL | Where property=* 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 |
| §184 | SHALL | The server SHALL return designations, with their use and, where known, their language |
| §185 | SHOULD | The server SHOULD return abstract |
| §186 | SHALL | code SHALL be echoed as it was asked for, not normalised. Where the server normalises the code, the
normal form belongs in the code property |
| §187 | SHALL | Where the code is not valid, the server SHALL return a 4xx and an OperationOutcome |
| §188 | SHALL | The server SHALL support $subsumes on CodeSystem, in both forms: system + codeA + codeB,
and codingA + codingB |
| §189 | SHALL | The server SHALL return an outcome parameter with one of equivalent, subsumes,
subsumed-by, not-subsumed, or unknown |
| §190 | SHALL | equivalent 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 |
| §191 | SHALL | Subsumption SHALL be transitive: a code subsumes its distant descendants, not just its direct children |
| §192 | SHALL | Subsumption SHALL follow the hierarchy however the code system states it. Where the code system states hierarchy with a subsumedBy or parent property rather than by nesting, the server SHALL read it, including where a concept has more than one parent |
| §193 | SHALL | Where either code is not valid, or not in the code system, or the version or system named is one the
server does not have, the server SHALL return a 4xx with an OperationOutcome. The message SHALL
name the code and the code system |
| §194 | SHALL | Where the code system's structure does not settle the question, the server SHALL say so rather than guessing |
| §195 | SHALL | A server that holds ConceptMaps SHALL support ConceptMap/$translate |
| §196 | SHALL | The server SHALL accept the source concept as sourceCode + sourceSystem, as sourceCoding, or as
sourceCodeableConcept |
| §197 | SHALL | In R4 the same parameters are named code + system, coding and codeableConcept, and the
target system is targetsystem (lower case s) rather than targetSystem. An R4 server SHALL accept
the R4 names |
| §198 | SHALL SHOULD | The server SHALL accept targetSystem, and SHOULD accept targetScope (target in R4), to
constrain what the answer may be |
| §199 | SHALL | Where the request names a map with url, the server SHALL use that map and no other |
| §200 | SHALL MAY | Where the request names no map, the server SHALL find the ConceptMaps whose sourceScope 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 |
| §201 | SHALL NOT | A map applies to a source code only where that code is within the map's sourceScope.
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 |
| §202 | SHALL | Every match SHALL report in originMap, as {url}|{version} |
| §203 | SHALL | 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 |
| §204 | SHALL | Each mapping SHALL be returned as a match parameter, whose parts are concept (the target Coding),
relationship, originMap, and sourceConcept (the Coding that was translated) |
| §205 | SHALL NOT | 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 |
| §206 | SHALL | sourceComment SHALL be returned where the ConceptMap element carries a comment |
| §207 | SHALL | Where the target concept of a match is not in the normal form of its code system (an ICD-11 map
written with short codes, say, where the normal form uses entity ids), the server SHALL also return
normalized-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 |
| §208 | SHALL | The server SHALL check each target concept it returns against its code system. Where the server
does not know the target code system, the match SHALL carry a note part saying that the code
system is not known and the code has not been validated |
| §209 | SHALL | 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 |
| §210 | SHALL | Where the code to translate is not in the normal form of its code system, the server SHALL look for map elements with the code as given and then with its normal form, so an element written in the normal form applies to the code in any form |
| §211 | SHALL | The server SHALL support all the relationship types, and map them correctly between R4 and R5 |
| §212 | SHALL | Where the ConceptMap explicitly states that a code has no mapping - 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 |
| §213 | SHALL | The server SHALL support ConceptMap.group.unmapped in its modes |
| §214 | SHALL | In R5, the reverse direction is expressed by naming the target concept: targetCode,
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 |
| §215 | SHALL | In R4, the reverse parameter does exist, and an R4 server SHALL support it, as well as the
targetcode form |
| §216 | SHALL | Where the request or the value set names a version, that version SHALL be used |
| §217 | SHALL | Where neither does, the server uses its own default, and SHALL report which version it used |
| §218 | SHALL | check-system-version SHALL produce an error where the value set asks for or resolves to a different version |
| §219 | SHALL | Validating a code against a version it does not exist in SHALL fail |
| §220 | SHALL | Validating a display against the wrong version SHALL fail in the same way: displays are version-specific |
| §221 | SHALL | inactive SHALL be true when an inactive concept is found in an expansion |
| §222 | SHALL | in expansions, the status property SHALL be populated with a status indicating why the concept is inactive (usually 'inactive', 'retired', or 'withdrawn'). This is not optional - a server that knows a concept is inactive SHALL say why |
| §223 | SHALL | the return value from $validate-code for the concept SHALL include a warning that the code is invalid, and the parameters 'inactive' and 'status' SHALL be populated |
| §224 | SHALL | if an inactive designation is included in an expansion, Servers SHALL either have a standards-status extension with a value of either 'withdrawn' or 'deprecated', or a use code of 'http://snomed.org/info#900000000000546006' |
| §225 | SHALL | 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 |
| §226 | SHALL | notSelectable SHALL be usable as a filter, with both the = and the in operators |
| §227 | SHALL | In an expansion, a not-selectable concept SHALL be marked abstract |
| §228 | SHALL | $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 |
| §229 | SHALL NOT | Where the code system says nothing about whether a concept is selectable, the server SHALL NOT assume either answer |
| §230 | SHALL | The listed extensions SHALL be supported |
| §231 | SHOULD | if code system has order, then this SHOULD be echoed |
| §232 | SHOULD | if code system supports 'labels', then this SHOULD be echoed |
| §233 | SHALL | 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 |
| §234 | SHALL | 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 |
| §235 | SHALL | The server SHALL support the implicit value sets: ?fhir_vs (all of SNOMED), ?fhir_vs=isa/{sctid}, ?fhir_vs=refset/{sctid} and ?fhir_vs=ecl/{expression} |
| §236 | SHALL | 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 |
| §237 | SHALL | The implicit value set URL may name an edition, and a version, as well as the generic
http://snomed.info/sct?fhir_vs... form, and the server SHALL draw the value set from the
edition and version so named |
| §238 | SHALL | The server SHALL support the concept filter with in, is-a, descendent-of, descendent-leaf,
is-not-a and child-of, and the SNOMED-specific expressions filter |
| §239 | SHALL | The server SHALL accept code as the same filter property as concept |
| §240 | SHALL | The server SHALL support the display filter with the regex operator |
| §241 | SHALL NOT | Descriptions in other languages SHALL NOT be searched |
| §242 | SHALL | The server SHALL support post-coordinated expressions, and SHALL observe whether the value set allows them |
| §243 | SHALL | where the value set says expressions = false, a well-formed expression SHALL be rejected as not
in the value set |
| §244 | SHALL | where the value set says expressions = true, a well-formed expression whose focus concept is in
the value set SHALL be accepted |
| §245 | SHALL | Expressions SHALL be parsed according to the SNOMED CT compositional grammar (SCG). In particular the comma before an attribute group is optional, so an attribute set followed directly by a group SHALL be accepted, and normalises to the form with the comma |
| §246 | SHALL | $validate-code on an expression SHALL check the expression against the machine-readable concept
model (MRCM) where the server has it |
| §247 | SHALL | An attribute the MRCM marks as grouped but written outside a relationship group (the Close To User
Form of the SNOMED postcoordination guide) is not an error: the server SHALL apply the
"Adding a Self-grouped Attribute" transformation, so that 40468003:363698007=10200004 is
equivalent to 40468003:{363698007=10200004} for validation, rendering and subsumption |
| §248 | SHALL | Where the server cannot fully check an expression, Servers SHALL say so with a processing-note issue
rather than silently passing it |
| §249 | SHALL NOT SHALL | $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 |
| §250 | SHALL | $subsumes SHALL reject an expression that is not valid under the MRCM rather than answering it |
| §251 | SHALL | The server SHALL return the display in the requested language, following the edition's language reference sets - see Languages |
| §252 | SHALL | $lookup SHALL return the properties the SNOMED CT on FHIR page defines |
| §253 | SHALL | property=* SHALL return all of them - parent, child, the defining relationships,
effectiveTime, inactive, moduleId, sufficientlyDefined and semanticTag - except the
normal forms |
| §254 | SHALL | normalForm and normalFormTerse are computed, and SHALL be returned only when they are asked
for by name |
| §255 | SHALL | A concept's concrete values (strengths, counts, and string and boolean values) SHALL be returned as
properties named by the attribute's concept id, with a value of the attribute's type: valueString
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 |
| §256 | SHALL | A server that supports SNOMED CT SHALL meet the minimum requirements |
| §257 | SHALL | Servers SHALL check post-coordinated expressions against the MRCM in $validate-code |
| §258 | SHALL | Servers SHALL return a workable display for an expression when validating it: $validate-code on a valid
expression SHALL return a display that a human can read |
| §259 | SHALL | Servers SHALL expand value sets that enumerate post-coordinated expressions explicitly |
| §260 | MAY | Any value set that does not say expressions = false admits post-coordinated expressions, and for such a value set the server MAY generate post-coordinated expressions in the expansion |
| §261 | SHALL | Servers SHALL generate a normal form for an expression |
| §262 | SHALL | Servers SHALL $translate to and from post-coordinated expressions, catering for the normal form |
| §263 | SHALL | a map target or source that is written in a different but equivalent form SHALL still be matched |
| §264 | SHALL | Servers SHALL correctly convert edition-specific concepts to the International Edition, producing a post-coordinated expression where the International Edition has no equivalent precoordinated concept. Such an expression SHALL use only concepts found in the International Edition |
| §265 | SHALL NOT SHALL SHOULD MAY | Servers SHALL in $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 |
| §266 | SHALL | Servers SHALL support the implicit value set for an answer list, http://loinc.org/vs/[LL code], in $expand and $validate-code |
| §267 | SHALL | Servers SHALL support the filter answers-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 |
| §268 | SHALL | Servers SHALL support the filter answer-list = code: all the answer lists (LL) that the answer (LA) is in |
| §269 | SHALL | The six LOINC axes - COMPONENT, 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 |
| §270 | SHALL | Servers SHALL also accept the Part name as the filter value for an axis (e.g. SCALE_TYP = Qn) |
| §271 | SHALL | CLASS SHALL be a string property whose value is the class name (e.g. PULM), in $lookup and in property
filters |
| §272 | SHALL | Servers SHALL also accept the Part code for the class as the value of a CLASS filter (e.g. CLASS =
LP7840-4) |
| §273 | SHALL | Servers SHALL support the ancestor filter (= and in, the value a Part code) on the multi-axial hierarchy |
| §274 | SHALL | Servers SHALL support LOINC's implicit value sets for the multi-axial hierarchy, http://loinc.org/vs/[partcode] |
| §275 | SHALL | The server SHALL validate UCUM codes by the UCUM grammar |
| §276 | SHALL | The server SHALL support the two special value sets: all UCUM codes, and the canonical units |
| §277 | SHALL | $lookup SHALL work for a UCUM expression |
| §278 | SHALL | $subsumes on UCUM SHALL report equivalent for two spellings of the same unit - a named derived
unit and the expression it is defined as |
| §279 | SHALL | An invalid UCUM code in a $subsumes request SHALL produce an error |
| §280 | SHALL NOT SHALL | The server SHALL support the 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 |
| §281 | SHALL | The server SHALL support the registered filter, selecting media types that are or are not in the
IANA registry |
| §282 | SHALL | The code system cannot be expanded as a whole, and neither can a base 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 |
| §283 | SHALL | $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 |
| §284 | SHALL NOT SHALL | Where the server does not know a parameter, it cannot know whether the parameter narrows the type, and SHALL return an error rather than guessing - unless both codes carry the parameter identically, in which case it cannot affect the answer and SHALL NOT stop the server deciding |
| §285 | SHALL | The server SHALL validate tags against the IANA subtag registry, including the registry's Prefix rules: an extlang or variant may only follow the prefix its registration names |
| §286 | SHALL | Private-use ranges written in the registry as ranges (QM..QZ) SHALL be accepted |
| §287 | SHALL | Grandfathered tags are registered whole, and SHALL be validated whole - they do not decompose into subtags |
| §288 | SHALL | Tags are case-insensitive: a tag in the wrong case is valid, and the server SHALL return the
canonical casing in normalized-code and note the difference |
| §289 | SHALL | $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) |
| §290 | SHALL | The server SHALL support the language, region and script filters |
| §291 | SHALL | A language 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 |
| §292 | SHALL | The server SHALL validate OMOP codes as code+system, Coding and CodeableConcept, with and
without a value set, and SHALL check both the display and the version |
| §293 | SHALL | $lookup SHALL work for standard OMOP concepts. A non-standard concept may be looked up or refused,
depending on the server |
| §294 | SHALL | The server SHALL support value sets filtered by OMOP domain |
| §295 | SHALL | The server SHALL support $lookup and $validate-code against each of the three, by code and by
entity URI, including grouper concepts and residual categories |
| §296 | SHALL | $lookup SHALL echo code as it was asked for |
| §297 | SHALL | The server SHALL support ICD-11 post-coordination in both $lookup and $validate-code, including
clustered and repeated axis values, and SHALL reject an invalid axis |
| §298 | SHALL | The server SHALL support expansion of the post-coordination scales, with count, offset and
filter |
| §299 | SHALL | The server SHALL support language, and reject a language it does not have |
No use of external IP
Note that while the IG itself has no ID dependencies, the test cases have extensive content taken from code systems defined by other parties, many of which are subject to IP restrictions. Content comes from the following organizations:
| IG | Package | FHIR | Comment |
|---|---|---|---|
| hl7.fhir.uv.tx-ecosystem#1.11.1-snapshot | R5 | ||
| hl7.terminology.r5#7.5.0 | R5 | Automatically added as a dependency - all IGs depend on HL7 Terminology | |
| hl7.fhir.uv.extensions.r5#5.4.0 | R5 | Automatically added as a dependency - all IGs depend on the HL7 Extension Pack | |
| hl7.fhir.uv.application-feature#1.0.0 | R5 | ||
| hl7.fhir.uv.tools.r5#1.3.0 | R5 | for example references |
There are no Global profiles defined