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

Ecosystem Definition

This page documents the HL7 terminology ecosystem framework, where a set of servers that serve different code systems on behalf of different code system authorities, and there is a central Coordination Server that routes terminology operations to the correct server.

A terminology server ecosystem is defined by two URLs:

  • the URL of the master registry that registers the servers in the ecosystem
  • the URL of the Coordination Server that handles value set and code system resolution for the ecosystem

There must be at least one Coordination Server for the ecosystem, though may be more than one.

Any organization can define an ecosystem by creating its own pair of registration file and Coordination Server. Individual servers might participate in multiple different ecosystems.

Where an ecosystem's files are, how to register a server in it, and what it requires of a server before it is registered (e.g. that the server passes the test cases, or is an approved server) are matters for that ecosystem, and are described in the ecosystem's own documentation, referenced by the registration property of its master registration file (see below).

HL7 manages one ecosystem, the public one used by the FHIR tools; its locations and registration process are documented at https://github.com/FHIR/ig-registry/blob/master/tx-registry-doco.md.

Registering the Servers

Registration is a two level process:

  • The master registration file lists one or more server registries
  • The server registries list one or more servers

The files may be static json files, or they may be dynamically generated in whatever fashion the manager of the file sees fit.

The master registration file

The master registration file has the following content:

{
  "formatVersion" : "1", // fixed value. Mandatory
  "description" : "some description of this registry set", // purpose etc. Optional
  "documentation" : "See http://hl7.org/fhir/uv/tx-ecosystem/ecosystem.html", // recommended reference to this page. Optional
  "registration" : "https://somewhere/path", // URL of the ecosystem's own documentation: its locations, policy, and how to register a server. Optional
  "ecosystem-documentation" : "http://hl7.org/fhir/uv/tx-ecosystem/ecosystem.html", // URL of the documentation for the ecosystem framework - usually this page. Optional
  "registries" : [{ // list of the registries. Must be present, but may be empty
    "code" : "code",  // code that identifies the registry. A persistent identifier. Alphanumerics only, no spaces. Mandatory
    "name" : "Name",  // human readable name. Can change, can contain any characters (including html type control chars). Mandatory
    "authority" : "Organization name", // name of publishing org. Optional
    "url" : "https://somwhere/path", // actual location of registry. Mandatory
    "disabled" : false // true if the registry is (temporarily) not part of the ecosystem - see Disabling below. Optional
  }]
}

Notes:

  • The formatVersion number is 1. This might be changed in the future if breaking changes are made to the format
  • Each of the entries in the list of registries points to a json document as documented in the next section
  • The code for the registry should be stable, since it may be used to identify the set of servers in the Coordination API (see below)
  • Coordination servers may display the registration and ecosystem-documentation links to users (e.g. as 'Register your own server' and 'Documentation')
  • The disabled property is a later, backwards compatible addition to the format (see Disabling below)

The server registries

This file contains a list of terminology servers.

{
  "formatVersion" : "1",// fixed value. Mandatory
  "description" : "something", // purpose etc. Optional
  "servers" : [{ // list of actual servers
    "code" : "code",  // code that identifies the server. Persistent identifier. Alphanumerics only, no spaces. Mandatory
    "name" : "Name",  // human readable name. Can change; can contain any characters (including html type control chars). Mandatory
    "access_info" : "documentation", // human readable markdown explaining how to get access to the server. Optional
    "url" : "http://server/page", // human landing page for the server. Optional
    "disabled" : false, // true if the server is (temporarily) not part of the ecosystem - see Disabling below. Optional
    "usage" : [ // if present, a list of string usage tags for the intended use of the server. Missing means any use is appropriate. See below for uses. Optional
    ],
    "languages" : { 
      // authoritative claims for particular languages - see Language Specific Claims below. Optional
      // Property names are BCP-47 language tags; a tag covers all more specific tags (de covers de-AT etc.)
      // Property values are mask lists with the same syntax and meaning as authoritative, 
      // applying to requests in that language
      "de" : ["http://domain/*"],
      "de-AT" : ["http://domain/other/*"]
    },
    "authoritative" : [ 
      // a list of CodeSystems the server claims to be authoritative for (see below). Optional
      "http://domain/*", // simple mask, * is a wildcard  
      "http://domain/*|1.0.0", // (may include version masks)
      "http://domain/*|1.*" 
    ],
    "authoritative-valuesets" : [ 
      // a list of ValueSets the server claims to be authoritative for (see below). Optional
      "http://domain/*", // simple mask, * is a wildcard
      "http://domain/*|1.0.0",
      "http://domain/*|1.*" 
    ],
    "exclusions" : [ 
      // a list of CodeSystems and ValueSets to hide from the ecosystem entirely (see Exclusions below). Optional
      "http://domain/*", // simple mask, * is a wildcard
      "http://domain/*|1.0.0",
      "http://domain/*|1.*" 
    ],
    "fhirVersions" : [{ // list of actual endpoint by FHIR version
      "version" : "R4", // can be R(X)
      "url" : "http://server/endpoint" // actual FHIR endpoint of the server for that version
    }]
  }]
}

Notes:

  • The formatVersion number is 1. This might be changed in the future if breaking or significant changes are made to the format
  • The languages property is a later, backwards compatible addition to the format. Readers that do not know it simply do not see the language specific claims, and route language requests to the general authoritative server - which is exactly the pre-language behavior (see Language Specific Claims below)
  • The code for the server should be stable, since it may be used to identify the server in the Coordination API (see below)
  • Most servers will only have one endpoint, that is, they will only support one FHIR version, but some support more than one
  • If the different versions have different authoritative lists, that's really different servers
  • Server endpoints must support FHIR R4 or later; R3 is not supported. Valid values for version: R4, R4B, R5, R6

Conformance Requirements

All endpoints listed in the server registration file SHALL return CapabilityStatement and TerminologyCapabilities resources that conform to the requirements described in this IG§3.

Ecosystems may require more than this before a server is registered - see the documentation for the ecosystem.

Servers may require authentication that restricts their use to an approved subset of users.

Authoritative Servers

Servers may be declared to be authoritative for a set of CodeSystems and/or ValueSets in the registration file. This is a declaration that the server manager believes that the server is the appropriate server in this ecosystem to choose for that set of CodeSystems and ValueSets when they are used.

In general, users will expect that the authoritative servers have the latest versions of the content, and that older versions still in use are also maintained. The authoritative claim is only in regard to the ecosystem, not an absolute claim that the server is the only authoritative server in all contexts.

Note that servers often support multiple code systems for which they are not regard as authoritative e.g. tx.fhir.org has a copy of the Australian edition of SNOMED CT, but the HL7 Australia official server is the authoritative server for the Australian edition. Servers are not restricted to only serving the content for which they are authoritative.

The authoritative flag is used to help resolve which server to use - see below.

Language Specific Claims

Claims in the authoritative list are not language specific: the server is the appropriate destination for the matched code systems whatever language a request asks for (or none), and it responds with whatever languages it actually has, per the usual fallback rules described in Languages. This is not an assertion that the server can supply displays in every language - it is simply the default destination for the code system.

Sometimes, though, a different server is the appropriate destination for particular languages of the same code system, because it has different supplements loaded. For example, one server is the general authoritative server for LOINC, while a different server hosts LOINC with the German language pack loaded, and is the appropriate server for German-language requests.

The languages property makes claims for particular languages: each property name is a BCP-47 language tag, and its value is a list of masks with the same syntax and meaning as authoritative, applying to requests in that language. A single server entry can carry both kinds of claim:

"authoritative" : ["http://fhir.de/CodeSystem/*"], // authoritative, whatever language is asked for
"languages" : {
  "de" : ["http://loinc.org*"] // authoritative for German-language requests
}

This entry means: this server is the authoritative server for the http://fhir.de/ code systems whatever language is asked for, and for German-language requests, it is also the authoritative server for LOINC.

Note that a language specific claim is full authority over the whole operation for requests in that language - it is not authority over displays that is separable from authority over content. There is no such separation in the API: a $validate-code with a German display, or an $expand with displayLanguage: de, is a single indivisible operation that is answered by a single server. Consequences:

  • 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)§4, so that it can execute the operations outright. Registering a server that holds only supplements is not supported: routing part of an operation to a supplement-only server would require cross-server composition (content from one server + supplement from another via tx-resource), and the ecosystem does not (currently) provide this
  • Language specific claims are invisible to requests that do not specify a language - they never bleed into general traffic. A request with no language matches only authoritative claims, which preserves the existing (pre-language) behavior exactly
  • The authoritative list remains the default destination: it applies whatever language is asked for (or none), except where another server makes a more specific claim for the requested language - exactly as before

Language specific claims apply to code systems only; there is (at this time) no language dimension to authoritative-valuesets.

Whether a server actually honours its language specific claims (returning correct displays and designations in the claimed languages for the claimed code systems) is verified by the ecosystem test cases, not by the coordination server - the coordination server only verifies that the server hosts the code systems themselves.

Language Matching

BCP-47 language tags are hierarchical, so a language tag is inherently a mask: a claimed tag matches any request language that is equal to it, or that is more specific than it (matching on - boundaries). A claim for de matches requests for de, de-AT, and de-CH-1996 (but not dent); a claim for de-AT matches de-AT but not plain de.

Where more than one server has a matching language specific claim, the most specific matching tag wins. Servers matched on their authoritative claims rank after all language specific matches (when the request specifies a language).

Where the request language is a weighted list per the Accept-Language syntax (e.g. de-AT, de;q=0.9, en;q=0.1), this matching is applied per language in descending weight order.

Exclusions

Servers may hold code systems or value sets that should not be used through the ecosystem at all - for example, a copy of a code system that is incomplete, out of date, or not intended for use beyond the server's own community. The exclusions list hides such content: anything matching one of the masks is removed from the server's presence in the ecosystem entirely:

  • The coordination server ignores matching code systems and value sets when scanning the server
  • The server is never returned by the Resolution API for a matching code system or value set - neither as authoritative nor as a candidate - even if one of the server's authoritative claims (including language specific claims) would otherwise match it

An exclusion is the opposite of an authoritative claim: an authoritative claim says 'prefer this server for this content', an exclusion says 'never use this server for this content' (within this ecosystem). Note that exclusions are about the server's fitness to serve the content, not about the authority to serve it; a server that simply doesn't want to be the preferred destination for something should instead write its authoritative masks so that they don't cover it.

Disabling

A registry or a server can be taken out of the ecosystem without deleting its registration, by adding "disabled" : true to its entry - in the master registration file for a registry, or in the server registry for a server. This is for when the registration needs to be kept but the registry or server shouldn't be used for now - e.g. the server is down for an extended period, is being migrated, or is failing the ecosystem's requirements - and it's expected that it will be re-enabled later, by removing the property (or setting it to false).

A disabled entry is treated as though it were not there:

  • The coordination server does not read a disabled registry, nor contact (scan) a disabled server
  • A disabled registry, and all the servers it lists, are not part of the ecosystem; a disabled server is not part of the ecosystem, and is not returned by the Discovery or Resolution APIs (see Client API)

Only the JSON value true disables an entry; a missing disabled, false, or any other value means that the entry is enabled. Note that readers that predate the property will treat a disabled entry as enabled.

Further Details:

SNOMED CT Implicit ValueSets

There's a limitation of use associated with the ecosystem, which is a little tricky to explain.

The page Using SNOMED CT with HL7 Standards defines a series of implicit SNOMED CT value set URLs. These implicit value sets are very useful since profiles, ValueSets, etc., can just refer to them directly without having to ensure that they are created, and they are supported by all the terminology servers in the ecosystem. However there's a limitation on their use associated with the need to decide which SNOMED CT server is the correct one to use for any particular request.

The implicit value set URL has two parts:

  • base: the SNOMED CT edition/version on which the value set is based, e.g. http://snomed.info/sct/20611000087101 is any Canadian version
  • specifier: the details of the value set, e.g. ?fhir_vs=refset/22071000087104

Given the way that the value sets are defined, they are only valid against a given edition and version, and can only be evaluated (and even instantiated) against that known version. One way to manage this is to bind the value set to a specific version in the definition itself, e.g. http://snomed.info/sct/20611000087101/version/20240731?fhir_vs=refset/22071000087104 identifies a specific version.

But it's often more useful to allow late binding of the value set to a specific version. E.g. http://snomed.info/sct/20611000087101?fhir_vs=refset/22071000087104 is whatever is the applicable SNOMED CT version, where that might be specified using a system-version parameter in the expansion parameters, or the server might just use the latest version of the Canadian edition that it has.

In the same way, http://snomed.info/sct?fhir_vs=refset/22071000087104 means 'whatever version of whatever edition', as decided by the infrastructure when the reference is used. (this particular example neatly shows the risk of this approach, because 22071000087104 is a Canadian specific reference set, but it would be fine for most SCT content).

Unfortunately, the ecosystem infrastructure doesn't know how to route http://snomed.info/sct?fhir_vs=refset/22071000087104 to the correct server - at the point the decision is made, the actual SNOMED CT edition isn't known, and can't be known, and the correct server can't be picked. Any evaluation of this value set will be done by the ecosystem's default server (tx.fhir.org, in the HL7 ecosystem), not one of the designated SNOMED CT servers (in this case, the Canadian server would be desired).

Hence, in the terminology ecosystem, all SNOMED CT implicit value sets must include the edition if they're not based on the international edition, and if evaluation by the correct server is desired.

This restriction applies to value set references in StructureDefinitions, Questionnaires, ValueSets, and other resources used in IGs, packages, etc. It does not apply to value sets used by import on one of the servers - the ecosystem does not resolve such a value set, and it's up to the server to do so.

Note: this restriction might change in the future e.g. if there's only one SNOMED CT server for all editions, but there's no plan for that at this time.

Language and Routing

A similar limitation applies to languages: the router can only act on what is in the resolve call, so the language must be known at routing time. Clients resolve their display language (from the request parameter, value set extension, HTTP header, or ValueSet.language, per Languages) before asking the ecosystem which server to use, and pass that language in the resolve call.

If the language is not known or not specified at routing time, the client gets default routing (the unqualified authoritative server) and the default language behavior of that server - which is the correct outcome for a request that never specified a language, but means that a language specified only after server selection (e.g. decided later in an expansion workflow) will not influence which server was chosen.