Concept Map

Ontoserver supports the $translate and $closure operations for ConceptMaps.

Concept Maps support SCRUD (Search, Create, Read, Update and Delete) operations as per the FHIR Specification rules for REST and ConceptMaps.

Search for concept maps is limited to the following parameters:

  • the name, _id, description and publisher parameters (these 3 additionally support the :exact, :contains and :missing modifiers)

  • the url, source-system, target-system, source-uri and target-uri parameters, including the :missing, :above and :below modifiers, and

  • the identifier, version, source-code, target-code, status, _tag, context and context-type parameters, including code, |code, system| and system|code formats, and the :missing modifier

  • the _lastUpdated parameter, including the lt, gt, ge, le and eq prefixes, and the :missing modifier. This parameter can be provided multiple times for AND semantics, to support use cases such as searching between 2 times

  • the context-type-value parameter

  • the extension x-syndication-status parameter with values true and false

Composite search parameters are supported, so all parameters can be used multiple times, for AND semantics, or with comma-separated values for OR semantics.

Of these, name, _id, description, publisher, url, source-uri, target-uri, version and status can be used to sort search results. _lastUpdated may also be used to sort results, but not as a search parameter.


The translate operation shows how a code in one value set relates to codes in another according to known concept maps. It can be invoked using a GET or POST request to

http://ontoserver.base.url/fhir/ConceptMap/[id]/$translate (instance level)

http://ontoserver.base.url/fhir/ConceptMap/$translate (type level)

The code, system and optional version (or alternatively a coding in a POST request) of the concept to be translated, as well the source & target value sets, are specified either as parameters to a GET request, or within a Parameters resource in the body of a POST request. The translation can be run in reverse by setting the optional reverse parameter to true.

Instance-level invocations work using the explicit ConceptMap with the given id. Type-level invocations that specify the url parameter work using the explicit or implicit ConceptMap corresponding to that url.

Type-level invocations can provide a url to reference an explicit ConceptMap, an implicit ConceptMap, or an algorithmic ConceptMap.

The conceptMapVersion parameter can be used to either specify or confirm the version of the ConceptMap to be used.

Type-level invocations that do not provide a url invoke a default mapping feature, which makes a best attempt to match the code, coding or CodeableConcept, based on whatever text is available (codes, descriptions, synonyms, etc).

More details about the translate operation can be found in the FHIR Specification.

In addition to the standard output parameters defined in the FHIR Specification, Ontoserver will also produce dependsOn parameters for matches that have a dependsOn element in the underlying ConceptMap.


The closure operation allows for ongoing maintenance of client-side closure tables for a set of codes, represented as a ConceptMap.

The operation can be accessed by sending a GET or POST request to


The name of the client's closure table is provided as a parameter to a GET request, or in the body of a POST request.

The first call to $closure with a given name will create an empty closure table.

Subsequent requests may specify one or more concepts to add to the table as codings using the concept parameter; the result of such a request will be a ConceptMap including the list of new subsumption relationships that result from the addition of the concepts. Requests may see the complete list of subsumption relationships in the closure table by passing a version parameter with value 0 (inspecting intermediate versions of the closure table is not currently supported).

More details on the closure operation can be found in the FHIR Specification, and its section on Closure Table maintenance.

Implicit Concept Maps

Ontoserver supports implicit concept maps for the following SNOMED historical association reference sets, with the corresponding URLs, as per the FHIR Specification.

  • Possibly Equivalent To :[/edition[/version]]?fhir_cm=900000000000523009 (target ValueSet is

  • Replaced By :[/edition[/version]]?fhir_cm=900000000000526001 (target ValueSet is

  • Same As :[/edition[/version]]?fhir_cm=900000000000527005 (target ValueSet is

  • Alternative :[/edition[/version]]?fhir_cm=900000000000530003 (target ValueSet is

In addition to these, we also support the following implicit concept maps for SNOMED CT that are not included in the FHIR spec:

  • SNOMED Concept Inactivation Indicators :[/edition[/version]]?fhir_cm=900000000000489007 (target ValueSet is

  • SNOMED to ICD-O :[/edition[/version]]?fhir_cm=446608001 (target ValueSet is

  • SNOMED to READ CTV-3 :[/edition[/version]]?fhir_cm=900000000000497000 (target ValueSet is

  • AMT to ARTG Id (SNOMED CT AU only) :[/edition[/version]]?fhir_cm=11000168105 (target ValueSet is

  • Australian Substance to International Substance map (SNOMED CT AU only) :[/edition[/version]]?fhir_cm==281000036105 (target ValueSet is

These concept maps can be used by providing the implicit ConceptMap URLs as the URL parameter to a type-level invocation of the $translate operation.

Algorithmic Concept Maps

Ontoserver supports the algorithmic concept maps listed below. These all extract the display text from a supplied Coding and CodeableConcept items (no code or system required) and attempt to find the best match in the target ValueSet.

Additionally, these strategies understand a special CodeSystem with URI which represents the code system of all strings (without leading/trailing whitespace). Hence, simple (cacheable) GET request style invocation is possible. For example, to automap “heart attack” to codes in SNOMED CT:

GET /ConceptMap/$translate
  • Ontoserver's default automapping strategy. It does not require all words to match, and also attempts simple spelling correction. It is designed for reasonably well-formed textual input, and is not suitable for arbitrary free text.

  • A matching strategy much closer to that used by Ontoserver for the filter parameter to $expand. It is designed for reasonably well-formed textual input, and is not suitable for arbitrary free text.

  • A re-implementation approximation of the MetaMapLite strategy. It is designed for reasonably well-formed textual input, and is somewhat suitable for short spans of arbitrary free text.

  •;name)+ This is a sequenced-strategy. The semi-colon separated sequence of names may include any of automapstrategy-default, automapstrategy-strict, and automapstrategy-MML. Each strategy will be attempted in turn until a match is found. Once a strategy has syccessfully found a match, the evaluation terminates (i.e., short-circuit evaluation).
    For example,;automapstrategy-default;automapstrategy-MML

  • (deprecated) The same as