FHIR Terminology Ecosystem IG
1.11.1-snapshot - Release International flag

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

Formal Conformance Statements

Conformance Expectations

IdExpectationRule
 SHALL
 SHALL NOT
 MAY
 SHOULD
 SHOULD NOT
§1SHALLThe standard discovery parameters SHALL be supported by all servers
§2SHALLThe standard resolution parameters SHALL be supported by all servers
§3SHALLAll endpoints listed in the server registration file SHALL return CapabilityStatement and TerminologyCapabilities resources that conform to the requirements described in this IG
§4SHALLA server making language specific claims SHALL host the content of the claimed code systems (complete or fragment) as well as the relevant supplement(s)
§5SHALLServers SHALL support all four approaches to specifying languages
§6SHALLClients SHALL resolve the display language (from the four sources above, in priority order) before server selection
§7SHALLThe language used for routing and the language used in the subsequent operation SHALL be the same
§8SHALLThe server SHALL either support the $versions operation at the root, or return a CapabilityStatement from /metadata that populates CapabilityStatement.fhirVersion
§9SHALLThe server SHALL support either R4 or R5
§10SHALLThe server SHALL be consistent: the version it reports is the version in which it will accept requests and return responses
§11SHALLThe server SHALL support the JSON format (application/fhir+json)
§12SHALLThe server SHALL accept operation parameters as a Parameters resource POSTed to the operation endpoint
§13SHALLThe server SHALL return HTTP 200 when the operation completed
§14SHALLThe server SHALL return a 4xx status with an OperationOutcome when it could not carry out the operation at all
§15SHALL NOTThe server SHALL NOT return a 5xx status for any of the test cases
§16SHALLEach issue SHALL have severity, code, details.coding, and details.text
§17SHALLdetails.coding SHALL include a coding from http://hl7.org/fhir/tools/CodeSystem/tx-issue-type
§18SHALLIssues that relate to a particular part of the request SHALL carry expression naming it
§19MAYdiagnostics MAY be populated
§20MAYServers MAY populate the http://hl7.org/fhir/StructureDefinition/operationoutcome-message-id extension
§21SHALLWhere 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
§22SHALLWhere 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
§23SHALL 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
§24SHOULDThe server SHOULD support $versions at the root, returning the FHIR versions it supports
§25SHALLIf the server supports $versions, Servers SHALL declare it in CapabilityStatement.rest.operation
§26SHALLServer SHALL return a CapabilityStatement from {root}/metadata
§27SHALLServers SHALL populate url, version, name, title, status (active), date, and kind (instance)
§28SHALLServers SHALL populate software.name, software.version and software.releaseDate. The name is what the test runner uses to identify the server in its output
§29SHALLServers SHALL populate fhirVersion, and rest[mode = server].security.service
§30SHALLServers SHALL include application/fhir+json in format
§31SHALLServers SHALL include a CapabilityStatement.instantiates value of http://hl7.org/fhir/CapabilityStatement/terminology-server
§32SHALLServers SHALL declare, under rest.resource for CodeSystem, the operations lookup, subsumes and validate-code
§33SHALLServers SHALL declare, under rest.resource for ValueSet, the read and search-type interactions and the operations expand and validate-code
§34SHALLWhere the server supports the caching protocol, Servers SHALL declare the cache-control operation at the system level in rest.operation
§35SHALLServers 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
§36SHALLServers SHALL carry a feature extension reporting the version of the test cases the server passes
§37SHALLThe server SHALL return a TerminologyCapabilities from {root}/metadata?mode=terminology
§38SHALLServers SHALL populate version, name, title, status and date
§39SHALLServers 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
§40SHALLServers 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
§41SHOULDServers SHOULD also list any of the optional parameters it supports there, in particular default-valueset-version
§42SHALLThe 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
§43SHOULDThe server SHOULD make all the code systems it supports available through the /CodeSystem endpoint for search and read operations
§44SHALLThe server SHALL support the url and version search parameters
§45MAYCodeSystems available at /CodeSystem MAY have content = not-present
§46SHOULDServers SHOULD generally allow multiple resources for the same canonical URL with different Resource.version
§47SHOULDServers can choose to support update/create if they want, though it SHOULD only do so for authenticated clients
§48SHALLServers SHALL ensure that they only send correct results for the code systems for which they is registered as 'authoritative'
§49SHALLAll predefined code systems SHALL have a web representation that is appropriate for a human to look at
§50SHALLGeneral purpose servers SHALL accept CodeSystems (and are required to do this to pass the general tests)
§51SHALLServers SHALL indicate their support or not for passing CodeSystem resources in the tx-resource parameter using the CodeSystemAsParameter feature in the CapabilityStatement
§52SHALLTerminology servers SHALL support passing CodeSystem supplements, particularly language packs
§53SHALLServers SHALL support global language packs, including as tx-resource parameters, except where CodeSystems do not allow this
§54SHALLA 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
§55SHALLA server SHALL report a global language pack as a used-supplement in $lookup and $expand when it contributes a display or a designation
§56SHALLAny other supplement SHALL only be used when it is referenced
§57SHALLAn 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
§58SHALLServers intended to be used as the primary server for the validator and IG publisher SHALL accept CodeSystems in the tx-resource parameter
§59SHALL
MAY
Servers SHALL not ignore supplements, though they MAY choose to return errors rather than process them correctly
§60SHALLThe server SHALL host the content of the claimed code systems (complete or fragment), not just the supplements
§61SHALLThe 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)
§62SHALLCodeSystem.caseSensitive SHALL be supported: validation SHALL correctly check case
§63SHOULDIn the case of non-case sensitive code systems, expansions SHOULD just contain the code as defined
§64SHALLIf the code system defines a hierarchy, both $expand and $validate SHALL correctly handle the hierarchy when interpreting filters and validating codes
§65SHALLA server SHALL not accept compositional grammars for codes unless the CodeSystem is marked as Compositional
§66SHALLServers that do not know the grammar for a CodeSystem that is marked as compositional SHALL note this in validation errors for the CodeSystem
§67SHALLIf 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
§68SHALLServers SHALL not process $expand or $validate-code requests on CodeSystems that have content = not-present or example
§69SHALL 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
§70SHALLServers SHALL not mistake supplements and code systems for each other
§71SHALLA number of concept properties defined at concept-properties change how a concept behaves, and a server SHALL honour them
§72SHALLWhere 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
§73SHALLWhere the CodeSystem declares no property definition at all, the server SHALL recognise the property by its standard code
§74SHALL NOTWhere 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
§75SHALLThe server SHALL make all the predefined value sets it supports available through the /ValueSet endpoints for search and read operations
§76SHALLThe server SHALL support the url and version search parameters
§77SHALLThe server SHALL support the _summary search parameter
§78SHOULDServers SHOULD generally allow multiple resources for the same canonical URL with different Resource.version, but this is subject to business rules on the server
§79SHOULDServers can choose to support update/create if they want, though it SHOULD only do so for authenticated clients
§80SHALLAll predefined value sets SHALL have a web representation that is appropriate for a human to look at
§81SHALLServers SHALL accept ValueSets passed in the tx-resource parameter to both $expand and $validate-code operations
§82SHALLServers SHALL use these value sets when resolving imports in other ValueSet resources
§83SHALLServers SHALL indicate their support for passing ValueSet resources in the tx-resource parameter in TerminologyCapabilities.expansion.parameter
§84SHALLServers SHALL support ValueSet.compose
§85SHALLServers SHALL support ValueSet.compose.include and ValueSet.compose.exclude
§86SHALLServers SHALL support imported value sets
§87SHALLServers SHALL support extensionally defined value sets
§88SHALLServers SHALL support intensionally defined value sets
§89SHALLServers SHALL support all the filters defined in the base specification for all code systems
§90SHALLServers SHALL return an error if a ValueSet uses a filter they do not understand
§91SHALLServers SHALL only return an existing expansion if it is the correct expansion for the definition of the value set
§92SHALLServers 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
§93MAYServers MAY reject resources that contain contained CodeSystems and ConceptMaps, but are not required to
§94SHALLThe server SHALL accept ConceptMap resources in the tx-resource parameter, and use them for $translate requests in the same call
§95SHALL
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
§96SHALLThe server SHALL support ConceptMaps that declare sourceScope / targetScope and ConceptMaps that do not
§97SHALLAll pre-defined code systems, value sets and concept maps SHALL have a web representation
§98SHOULD
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
§99MAYthe server MAY choose to make additional process/provenance/context information available
§100MAYThe server MAY choose to make this content available at the end-point for the relevant resource
§101MAYServers are not required to do this; they MAY choose to make the content available elsewhere
§102SHALLIf 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)
§103SHALLThe server SHALL support the tx-resource parameter for passing related terminology
§104SHALLIf a server receives a terminology resource it does not process correctly, Servers SHALL return an error
§105SHALLThe server SHALL support supplements for the purposes of designations in different languages
§106SHALLServers 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
§107SHALLThe 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
§108SHOULD NOTNote 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
§109SHALL
SHOULD
Servers SHOULD support $cache-control. This is not yet a SHALL
§110SHALLA server that supports Servers SHALL declare the cache-control operation at the system level in CapabilityStatement.rest.operation
§111SHALLThe operation declares affectsState = true; servers SHALL accept start and end by POST
§112SHOULDThe 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
§113SHALLThe cache-id SHALL be allocated by the server, and returned in the cache-id output parameter of a mode=start call
§114SHALL NOTA server SHALL NOT honour a cache-id on an endpoint other than the one that issued it
§115SHALLA mode=start response SHALL report sealed, so that a client never has to assume a default
§116SHALL NOTA 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
§117SHALLAn 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
§118SHALLWhere 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
§119SHALL NOTmode=end for a cache the server does not have SHALL NOT be an error
§120SHOULDServers SHOULD record why each cache-id they retired went away, and say which in the diagnostics
§121SHALLmode=check SHALL return HTTP 200 whatever the answer
§122SHALL
SHOULD
For a valid cache, the response SHALL carry valid = true and sealed, and SHOULD carry resource-count and idle
§123SHOULDThe response SHOULD carry timeout, the server's idle timeout in seconds, where the server is willing to state one
§124SHALLFor 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
§125SHALLA successful check counts as use, and SHALL reset the cache's idle timer
§126SHALLA 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
§127MAYEvery 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
§128SHALL 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
§129SHALL 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
§130SHOULDContent in the ecosystem SHOULD therefore pin versions explicitly on references between terminology resources wherever the exact version matters
§131SHALLThe 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
§132SHALLThe server SHALL echo all parameters - including ones it assumed a value for - in ValueSet.expansion.parameter
§133SHALLThe 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
§134SHALLThe server SHALL populate expansion.identifier and expansion.timestamp
§135SHOULDThe server SHOULD populate expansion.total where it knows the total
§136SHOULDThe server SHOULD return hierarchical expansions when possible
§137SHALLThe server SHALL support excludeNested, which forces a flat expansion
§138SHALLWhere 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
§139SHALLThe server SHALL support count and offset
§140SHALLThe server SHALL support activeOnly, includeDesignations, includeDefinition, property and designation
§141SHALLA 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)
§142SHALLThe server SHALL support displayLanguage, and the Accept-Language header, and ValueSet.language
§143SHALLThe server SHALL support filter (text search)
§144SHALLThe server SHALL support abstract in the sense described under notSelectable
§145SHOULDThe server SHOULD support default-valueset-version, which supplies a version for imported value sets that are referenced without one
§146SHALLWhere 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
§147SHALLThe 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)
§148SHALLA regex filter SHALL match the whole value
§149SHALLHierarchy 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
§150SHALLA filter the server does not understand, or a filter with no value where one is required, SHALL produce an error
§151SHALLWhere 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
§152SHALLValueSet.compose.property SHALL be supported in both its forms: an enumerated list of property codes, and * meaning every property the code system defines
§153SHALLThe server SHALL declare the properties it returned in ValueSet.expansion.property
§154SHALLThe server SHALL return the values in ValueSet.expansion.contains.property
§155MAYValueSet.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
§156SHALLIn 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
§157SHALLThe server SHALL support compose.exclude in all its forms: excluding enumerated codes, excluding by filter, and excluding by importing another value set (suite: exclude)
§158SHALLThe server SHALL support a value set that includes two versions of the same code system, and SHALL keep the versions distinct
§159SHALL NOTWhere 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
§160SHALLThe server SHALL support validating code + system (+ version) (+ display), Coding, and CodeableConcept
§161SHALLA 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
§162SHALLThe server SHALL support valueset-membership-only
§163SHALLThe server SHALL support language correctly
§164SHALLThe server SHALL support the inferSystem parameter
§165SHALLWhere 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
§166SHALLThe 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
§167SHALLThe server SHALL support abstract
§168SHALLthe server SHALL return a result parameter, along with a message summarising the reason why if result = false
§169SHALLany errors and warnings SHALL be itemised in an issues parameter with paths to the actual locations so a validator can locate the issue correctly
§170SHALLany 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
§171SHALLthe server SHALL return the code system and code against which validation was based
§172SHOULDThe server SHOULD return the version against which validation was based
§173SHOULDThe server SHOULD return a display for the code (display parameter)
§174SHALLThe server SHALL return a x-caused-by-unknown-system parameter for each code system it did not support
§175SHOULDThe server SHOULD return a normalized-code parameter where appropriate
§176SHOULDThe server SHOULD return an issue with tx issue type processing-note when it has not fully validated the code
§177SHALLThe 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
§178SHOULDThe server SHOULD support batch validation: a $validate-code request carrying repeated validation parameters, each one a Parameters resource describing one code to validate
§179SHALLA 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
§180SHALL NOTOne bad validation in a batch SHALL NOT fail the batch
§181SHALLThe server SHALL return display, and the name of the code system, and its version
§182SHALLThe server SHALL support the property parameter, including property=*, which asks for every property the code system defines for the concept
§183SHALLWhere 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
§184SHALLThe server SHALL return designations, with their use and, where known, their language
§185SHOULDThe server SHOULD return abstract
§186SHALLcode SHALL be echoed as it was asked for, not normalised. Where the server normalises the code, the normal form belongs in the code property
§187SHALLWhere the code is not valid, the server SHALL return a 4xx and an OperationOutcome
§188SHALLThe server SHALL support $subsumes on CodeSystem, in both forms: system + codeA + codeB, and codingA + codingB
§189SHALLThe server SHALL return an outcome parameter with one of equivalent, subsumes, subsumed-by, not-subsumed, or unknown
§190SHALLequivalent 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
§191SHALLSubsumption SHALL be transitive: a code subsumes its distant descendants, not just its direct children
§192SHALLSubsumption 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
§193SHALLWhere 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
§194SHALLWhere the code system's structure does not settle the question, the server SHALL say so rather than guessing
§195SHALLA server that holds ConceptMaps SHALL support ConceptMap/$translate
§196SHALLThe server SHALL accept the source concept as sourceCode + sourceSystem, as sourceCoding, or as sourceCodeableConcept
§197SHALLIn 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
§198SHALL
SHOULD
The server SHALL accept targetSystem, and SHOULD accept targetScope (target in R4), to constrain what the answer may be
§199SHALLWhere the request names a map with url, the server SHALL use that map and no other
§200SHALL
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
§201SHALL NOTA 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
§202SHALLEvery match SHALL report in originMap, as {url}|{version}
§203SHALLresult 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
§204SHALLEach mapping SHALL be returned as a match parameter, whose parts are concept (the target Coding), relationship, originMap, and sourceConcept (the Coding that was translated)
§205SHALL NOTIn R4 the relationship is reported in equivalence, using the R4 codes (equivalent, narrower, wider, relatedto …), and the R5 relationship element SHALL NOT be present
§206SHALLsourceComment SHALL be returned where the ConceptMap element carries a comment
§207SHALLWhere 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
§208SHALLThe 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
§209SHALLWhere 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
§210SHALLWhere 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
§211SHALLThe server SHALL support all the relationship types, and map them correctly between R4 and R5
§212SHALLWhere 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
§213SHALLThe server SHALL support ConceptMap.group.unmapped in its modes
§214SHALLIn 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
§215SHALLIn R4, the reverse parameter does exist, and an R4 server SHALL support it, as well as the targetcode form
§216SHALLWhere the request or the value set names a version, that version SHALL be used
§217SHALLWhere neither does, the server uses its own default, and SHALL report which version it used
§218SHALLcheck-system-version SHALL produce an error where the value set asks for or resolves to a different version
§219SHALLValidating a code against a version it does not exist in SHALL fail
§220SHALLValidating a display against the wrong version SHALL fail in the same way: displays are version-specific
§221SHALLinactive SHALL be true when an inactive concept is found in an expansion
§222SHALLin 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
§223SHALLthe 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
§224SHALLif 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'
§225SHALLA 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
§226SHALLnotSelectable SHALL be usable as a filter, with both the = and the in operators
§227SHALLIn an expansion, a not-selectable concept SHALL be marked abstract
§228SHALL$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
§229SHALL NOTWhere the code system says nothing about whether a concept is selectable, the server SHALL NOT assume either answer
§230SHALLThe listed extensions SHALL be supported
§231SHOULDif code system has order, then this SHOULD be echoed
§232SHOULDif code system supports 'labels', then this SHOULD be echoed
§233SHALLA 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
§234SHALLThe 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
§235SHALLThe 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}
§236SHALLWhere 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
§237SHALLThe 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
§238SHALLThe 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
§239SHALLThe server SHALL accept code as the same filter property as concept
§240SHALLThe server SHALL support the display filter with the regex operator
§241SHALL NOTDescriptions in other languages SHALL NOT be searched
§242SHALLThe server SHALL support post-coordinated expressions, and SHALL observe whether the value set allows them
§243SHALLwhere the value set says expressions = false, a well-formed expression SHALL be rejected as not in the value set
§244SHALLwhere the value set says expressions = true, a well-formed expression whose focus concept is in the value set SHALL be accepted
§245SHALLExpressions 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
§246SHALL$validate-code on an expression SHALL check the expression against the machine-readable concept model (MRCM) where the server has it
§247SHALLAn 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
§248SHALLWhere the server cannot fully check an expression, Servers SHALL say so with a processing-note issue rather than silently passing it
§249SHALL 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
§250SHALL$subsumes SHALL reject an expression that is not valid under the MRCM rather than answering it
§251SHALLThe server SHALL return the display in the requested language, following the edition's language reference sets - see Languages
§252SHALL$lookup SHALL return the properties the SNOMED CT on FHIR page defines
§253SHALLproperty=* SHALL return all of them - parent, child, the defining relationships, effectiveTime, inactive, moduleId, sufficientlyDefined and semanticTag - except the normal forms
§254SHALLnormalForm and normalFormTerse are computed, and SHALL be returned only when they are asked for by name
§255SHALLA 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
§256SHALLA server that supports SNOMED CT SHALL meet the minimum requirements
§257SHALLServers SHALL check post-coordinated expressions against the MRCM in $validate-code
§258SHALLServers 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
§259SHALLServers SHALL expand value sets that enumerate post-coordinated expressions explicitly
§260MAYAny 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
§261SHALLServers SHALL generate a normal form for an expression
§262SHALLServers SHALL $translate to and from post-coordinated expressions, catering for the normal form
§263SHALLa map target or source that is written in a different but equivalent form SHALL still be matched
§264SHALLServers 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
§265SHALL 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
§266SHALLServers SHALL support the implicit value set for an answer list, http://loinc.org/vs/[LL code], in $expand and $validate-code
§267SHALLServers 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
§268SHALLServers SHALL support the filter answer-list = code: all the answer lists (LL) that the answer (LA) is in
§269SHALLThe 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
§270SHALLServers SHALL also accept the Part name as the filter value for an axis (e.g. SCALE_TYP = Qn)
§271SHALLCLASS SHALL be a string property whose value is the class name (e.g. PULM), in $lookup and in property filters
§272SHALLServers SHALL also accept the Part code for the class as the value of a CLASS filter (e.g. CLASS = LP7840-4)
§273SHALLServers SHALL support the ancestor filter (= and in, the value a Part code) on the multi-axial hierarchy
§274SHALLServers SHALL support LOINC's implicit value sets for the multi-axial hierarchy, http://loinc.org/vs/[partcode]
§275SHALLThe server SHALL validate UCUM codes by the UCUM grammar
§276SHALLThe server SHALL support the two special value sets: all UCUM codes, and the canonical units
§277SHALL$lookup SHALL work for a UCUM expression
§278SHALL$subsumes on UCUM SHALL report equivalent for two spellings of the same unit - a named derived unit and the expression it is defined as
§279SHALLAn invalid UCUM code in a $subsumes request SHALL produce an error
§280SHALL 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
§281SHALLThe server SHALL support the registered filter, selecting media types that are or are not in the IANA registry
§282SHALLThe 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
§283SHALL$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
§284SHALL 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
§285SHALLThe 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
§286SHALLPrivate-use ranges written in the registry as ranges (QM..QZ) SHALL be accepted
§287SHALLGrandfathered tags are registered whole, and SHALL be validated whole - they do not decompose into subtags
§288SHALLTags 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
§289SHALL$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)
§290SHALLThe server SHALL support the language, region and script filters
§291SHALLA 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
§292SHALLThe 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
§293SHALL$lookup SHALL work for standard OMOP concepts. A non-standard concept may be looked up or refused, depending on the server
§294SHALLThe server SHALL support value sets filtered by OMOP domain
§295SHALLThe server SHALL support $lookup and $validate-code against each of the three, by code and by entity URI, including grouper concepts and residual categories
§296SHALL$lookup SHALL echo code as it was asked for
§297SHALLThe 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
§298SHALLThe server SHALL support expansion of the post-coordination scales, with count, offset and filter
§299SHALLThe server SHALL support language, and reject a language it does not have

IP Statements

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:

  • SNOMED CT (under a special 'testing' license)
  • WHO
  • IETF
  • LOINC

Dependency Summary

IGPackageFHIRComment
FHIR Terminology Ecosystem IGhl7.fhir.uv.tx-ecosystem#1.11.1-snapshotR5
FHIR Terminology Ecosystem IG / HL7 Terminology (THO)hl7.terminology.r5#7.5.0R5Automatically added as a dependency - all IGs depend on HL7 Terminology
FHIR Terminology Ecosystem IG / FHIR Extensions Packhl7.fhir.uv.extensions.r5#5.4.0R5Automatically added as a dependency - all IGs depend on the HL7 Extension Pack
FHIR Terminology Ecosystem IG / FHIR Application Feature Framework Implementation Guidehl7.fhir.uv.application-feature#1.0.0R5
FHIR Terminology Ecosystem IG / FHIR Tooling Extensions IGhl7.fhir.uv.tools.r5#1.3.0R5for example references

Global Profiles Statement

There are no Global profiles defined