Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


The service must host a FHIR terminology service. At least R4 or R5 must be supported. It's server discretion whether to support R2, R3, or R5. At around the time that R5 is finally published, providing an R5 service will probably be required (in place of R4?). The validator and IG publisher will happily interoperate with either an R4 or R5 server irrespective of the version it's working with. Choose R5 if the new features on ConceptMap are compelling.

The service must support:


  • All CodeSystems, ValueSets, and ConceptMaps must be have an associated URL at which a user with a browser can read the definition of the artifact. This should be a human readable web page that describes the artifact of the type that FHIR implementation guides provide (note that the specific presentation used by the IG guides is not required). The page must include a link/method for the user to download the raw definition of the resource. This URL must known for each resource. If it is not algorithmically determined (see below), then it must be specifically identified in the ( Resource ).meta.source property when the resource is accessed (see below).
  • The service is assumed to be the source of truth and trusted expansions for terminology artifacts as defined by the registry (todo: provide link), but it can use the trusted-expansion-source to indicate another service that is the trusted-expansion-source but this will be ignored by FHIR tools unless it's also a registered server




  • Must return a list of all code systems(+versions) that are supported, whether they are explicitly made available as CodeSystem resources or not
$expandsee for details
$translateto be determined at this point
  • valueSets will be identified by the URL parameter and valueSetVersion
  • displayLanguage, activeOnly, and limitedExpansion must be supported
  • system-version, force-system-version & default-to-latest-version must be supported
  • includeDesignations / designation should be supported
  • paging should be supported (but won't be used by the most important tools)
  • if the tools provide the parameter _limit and _incomplete, it should be honored (and the extension returned if appropriate) (note: this requirement may be changed to use count - under investigation)
  • value sets or code systems will be identified by URL and version
  • displayLanguage and activeOnly must be supported
  • system-version, force-system-version & default-to-latest-version must be supported
  • the inputs system, code, coding, and codeableConcept must all be supported
  • in the parameters returned: 
  • A parameter 'cause' must be returned with the valueCode 'unknown' if validation failed because a value set / code system could not be found. If the code isn't valid or in the value set, cause = invalid. Other failures, use some other code from OperationOutcome.issue.cause if a cause is returned 
  • the service must return an 'issues' parameter with an OperationOutcome if any issues are found (for hints and warnings too)


    The service may require authenticationusers to authenticate. If the service requires authentication, it must be in the form of basic authentication (username/password) or an authentication header - usually a bearer token - that the user can determine in advance, and then provide to their FHIR tooling in some configuration (configuration will be different for different tools, but their requirement is to provide the authentication header as configured)their FHIR Tool Settings File. It is assumed that the service will have some mechanism to provide these tokens to appropriate authorised users (which might be anyone who accepts the required license, or any users with appropriate citizenship or business relationship with the entity that provides the service). 

    Note that there must be an arrangement for FHIR tool smiths to get a token that grants access to the service without cost in order to test their support of the these services.

    Registering the service

    Such services are registered following discussion with the FHIR Product Director ( which will also include discussion on the tooling channel on When registering a service, the host that operates the service must declare in a json file that will be public to the FHIR community:

    • The identity or the hosting organization
    • the URL(s) at which the service is provided for which FHIR versions. The URLs may change but changing will require advance notice to the community of at least a month 
    • Whether the service requires authentication, and if it does,
      • who is eligible to get a token
      • a link to a web page that initiates the process of getting a token 
    • a list of canonical patterns that identify resources that the service hosts (see notes below)
    • (optional) an algorithm that defines how to turn resource ids on the service into web pages for a human to read 

    Canonical Patterns

    These are used by the tools to decide whether to use the service. Note that the tools will never consult all the terminology servers in case they know a particular terminology artifact - unless instructed otherwise, the tools will only consult their default terminology server (usually unlesss configured otherwise). The tools will look through the known registered services seeing if the canonical URL of the artifact they are dealing with matches any of the canonical URL patterns that the server provides services for, and if it finds a match, it will use that server.

    A registered server may host more artifacts than it declares itself to be 'the' host for - e.g. the Australian NCTS hosts LOINC etc but it is not the authoritative host for LOINC. 

    The list of canonical patterns may change - changing the list will require a PR to a JSON file managed by the FHIR product director.


    The algorithm is a simple string that may contain the tokens {type} and {id} to define the web page for the resource. Anything more complicated than this will have be done using .meta.source (see above)

    Documentation for toolsmiths


    This is to be described... (a registry of registries)