> For the complete documentation index, see [llms.txt](https://docs.b2ihealthcare.com/snow-owl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.b2ihealthcare.com/snow-owl/rest-apis/fhir/conceptmaps.md). # ConceptMap ## Introduction ![](https://1894725842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUjFUePuVzxE3xh52ynpe%2Fuploads%2FS7UONfwYsC7dXDjZYfhW%2Fpaid_badge.svg?alt=media\&token=1f66c56a-71a1-4fed-a20a-96bb67e55772) The paid version of Snow Owl TS supports interactions and operations that target concept map resources. ## Interactions ### read (instance) GET requests that include the concept map identifier as the final path segment return the resource's current (non-versioned) state: ```http GET /snowowl/fhir/ConceptMap/52ABAkwTIAPG4H7DVE5dV6JY [Response headers] Content-Type: application/fhir+json { "resourceType" : "ConceptMap", "id" : "52ABAkwTIAPG4H7DVE5dV6JY", "meta" : { "lastUpdated" : "2026-06-30T11:09:26.313Z" }, "text" : { "status" : "empty" }, "url" : "https://b2ihealthcare.com/conceptmaps/52ABAkwTIAPG4H7DVE5dV6JY", "title" : "Example Concept Map", "status" : "active", "group" : [{ "source" : "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/20231001", "target" : "https://b2ihealthcare.com/codesystems/example-lcs-1|v1", "element" : [{ "code" : "103015000", "display" : "Thoracic nerve root pain", "target" : [{ "code" : "TNP001", "display" : "Thoracic nerve root pain", "relationship" : "equivalent" }] }] }] } ``` Just as with CodeSystem or ValueSet `read` interactions, query parameters `_format`, `_summary`, `_elements` and `_pretty` are applicable. [FHIR API](/snow-owl/rest-apis/fhir.md#common-request-parameters) expands on these settings. ### vread (instance) To retrieve a single historical version of the resource, use the following GET request: 
GET /snowowl/fhir/ConceptMap/52ABAkwTIAPG4H7DVE5dV6JY/_history/1.0.0

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType" : "ConceptMap",
  "id" : "52ABAkwTIAPG4H7DVE5dV6JY",
  "meta" : {
    "lastUpdated" : "2026-06-30T11:09:26.313Z"
  },
  "text" : {
    "status" : "empty"
  },
  "url" : "https://b2ihealthcare.com/conceptmaps/52ABAkwTIAPG4H7DVE5dV6JY/version/1.0.0", // [1]
  "version" : "1.0.0", // [2]
  "title" : "Example Concept Map",
  "status" : "active",
  "date" : "2026-06-30T00:00:00Z", // [3]
  "effectivePeriod" : {
    "start" : "2026-06-30T00:00:00Z" // [4]
  },
  "group" : [{
    "source" : "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/20231001",
    "target" : "https://b2ihealthcare.com/codesystems/example-lcs-1|v1",
    "element" : [{
      "code" : "103015000",
      "display" : "Thoracic nerve root pain",
      "target" : [{
        "code" : "TNP001",
        "display" : "Thoracic nerve root pain",
        "relationship" : "equivalent"
      }, {
        "code": "TNP", // [5]
        "display": "Thoracic nerve pain",
        "relationship" : " source-is-narrower-than-target"
      }]
    }]
  }]
}
Notable differences between a versioned and the current representation are marked with a comment in the code block above: 1. If a FHIR URL override value was set in resource settings at the time the version was created, it will be reflected in the response (in this case no such setting has been applied) 2. Similarly, if the resource was configured to use its native `url` value as the FHIR version at the time it was created, it will also be reflected in the response (in this example the value of the version ID matches the value returned as the FHIR resource version) 3. The effective time appears as the value of `date` 4. The effective time also appears as the value of `effectivePeriod.start` 5. Changes in mapping will reflect the state of the resource at version creation time The version path parameter accepts the following values: | Value | Behavior | | ---------------------------------- | ------------------------------------------- | | `HEAD` | Returns the current resource representation | | `LATEST` | Returns the most recent historical revision | | Any other valid version identifier | Returns the specified historical revision | `HEAD` is implemented as a fallback to the regular resource read operation, while `LATEST` selects the latest historical version based on version timestamps. ### history (instance) GET requests that include a resource identifier with a `_history` path segment added to the end return a FHIR `Bundle` of type `history`, containing historical revisions of the specified resource: ```http GET /snowowl/fhir/ConceptMap/52ABAkwTIAPG4H7DVE5dV6JY/_history?_summary=text [Response headers] Content-Type: application/fhir+json { "resourceType" : "Bundle", "id" : "17Xn4giXKnR9PHOGogSJsQ", "meta" : { "lastUpdated" : "2026-09-21T10:01:24.368Z", "tag" : [{ "system" : "http://hl7.org/fhir/v3/ObservationValue", "code" : "SUBSETTED", "display" : "As requested, resource is not fully detailed." }] }, "type" : "history", "total" : 1, "entry" : [{ "fullUrl" : "https://{host}/snowowl/fhir/ConceptMap/52ABAkwTIAPG4H7DVE5dV6JY/_history/1.0.0?_pretty=true", "resource" : { "resourceType" : "ConceptMap", "id" : "52ABAkwTIAPG4H7DVE5dV6JY", "meta" : { "lastUpdated" : "2026-06-30T11:09:26.313Z" }, "status" : "active" } }] } ``` Only versioned revisions are returned, not individual edits. The `HEAD` revision is also omitted from the history bundle. Supported search parameters are:
NameDescription
_countLimits the number of returned history entries (50 by default)
_sinceReturns revisions created on or after the supplied ISO-8601 instant
_atReturns revisions created on or before the supplied ISO-8601 instant​Note that while the specification allows a wider set of comparisons for date(time) inputs, Snow Owl currently only supports instant values without a comparison operator prefix.
Allowed values for the `_sort` parameter:
ValueBehavior
-_lastUpdatedNewest revisions first (default)
_lastUpdatedOldest revisions first
noneDoes not effectively override the default sort
Any other value400 Bad Request is returned
### update (instance) PUT requests that include a resource identifier will update an existing resource (or create a new one if it didn't exist earlier): ```http PUT /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2 [Request headers] X-Author: user@host.domain Content-Type: application/fhir+json [Request body] { "resourceType": "ConceptMap", "id": "69YWt6qc1ydgwARjh8XNw2", "meta": { "lastUpdated": "2023-11-30T16:36:31.653Z" }, "language": "en", "text": { "status": "empty" }, "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map", "name": "ExampleConceptMap", "title": "Example Concept Map", "status": "draft", "description": "# Example Concept Map", "group": [ { "source": "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/20231001", "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1", "element": [ { "code": "103015000", "display": "Thoracic nerve root pain", "target": [ { "code": "C00", "display": "Root concept", "relationship": "equivalent" } ] }, // Added mapping { "code": "102506008", "display": "Well child (finding)", "target": [ { "code": "C00-1", "display": "Child concept", "relationship": "equivalent" } ] } ] } ] } ``` The response code is `201 Created` if the resource did not exist previously, and the URL is included in the `Location` response header. Existing concept maps (like in the example above) are updated and a `200 OK` response is returned instead. The actual content of `Location` will differ depending on whether a versioned resource is sent in as the input or a draft one. The former will generate a `vread` interaction with the version value included, while the latter will be a URL that can be used to issue a `read` interaction on the most recent content. If an error occurs during the update, a `400 Bad Request` response with an `OperationOutcome` resource as the response body is emitted instead. The following non-standard request headers can be used to control certain aspects of the commit process:
NameDescription
X-Effective-DateThe effective date to use if a version identifier is present in the resource without a corresponding date element (defaults to the current date if neither the resource nor this header specifies a value)
X-AuthorSets the user identifier that the commit should be attributed to (defaults to the authenticated user)
X-OwnerSets the owner of the resource, for access control purposes in external systems (defaults to the author or the authenticated user if the former is not set)
X-Owner-ProfileSets the human-readable name of the owner of the resource, for presentation purposes in external systems (optional)
X-Bundle-IdSpecifies the parent bundle's resource identifier (defaults to the root bundle if not set)
{% hint style="warning" %} Concept maps are currently limited to a single source and target code system and version (group) they can use to map concepts. {% endhint %} When a ConceptMap contains multiple mapping elements with the same source code, Snow Owl consolidates them into a single FHIR `element` and combines the corresponding target mappings into the `target` array associated with this element. This behavior reduces duplication in the generated ConceptMap representation while preserving all mapped target concepts and their associated mapping properties. {% hint style="info" icon="burst-new" %} Snow Owl now preserves the `name` property supplied in imported `ConceptMap` resources. Previously generated or derived names are no longer used when a resource name is provided by the import payload. {% endhint %} ### delete (instance) A DELETE request removes an existing concept map: ```http DELETE /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2 [Request headers] X-Author: user@host.domain [Response] 204 No Content ``` Successful removal of a resource results in a `204 No Content` response. Concept maps that have already been versioned can not be removed without adding the `force=true` query parameter to signal a forced deletion (this option is only available to administrators however). {% hint style="info" icon="burst-new" %} The `X-Author` request header is optional, the default value corresponds to the authenticated user. {% endhint %} ### create (type) In `create` interactions a POST request is sent to the path corresponding to the resource type. Any identifier included in the request body is ignored and a new, random one is generated from scratch. ```http POST /snowowl/fhir/ConceptMap [Request headers] X-Effective-Date: 2023-11-29 X-Author: user@host.domain X-Owner: owner@host.domain X-Owner-Profile-Name: Resource Owner X-Bundle-Id: parent-bundle-id Content-Type: application/fhir+json [Request body] { "resourceType": "ConceptMap", // "id": "..." is not used by the server "text": { "status": "empty" }, "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map-2", "title": "Example Concept Map", "status": "draft", "group": [ { "source": "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/20231001", "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1", "element": [ { "code": "103015000", "display": "Thoracic nerve root pain (finding)", "target": [ { "code": "C00", "display": "Root concept", "relationship": "equivalent" } ] } ] } ] } [Response] 201 Created [Response headers] Location: http://{host}/snowowl/fhir/ConceptMap/cndkDE31kfeXw8 ``` {% hint style="warning" %} FHIR URLs in Snow Owl must be unique. If a resource is submitted to the `create` interaction where the URL matches the value in an already persisted resource, an `update` will take place instead. {% endhint %} The response code is `201 Created` if the interaction is successful and a new resource has been created, `200 OK` if a resource update was performed. The request URL in the response header named `Location` can be used in follow-up `read` or `vread` interactions; the latter is provided if the input resource also contained version information. ### search (type) GET requests with a request path that points to the resource type returns all concept maps that satisfy the specified search criteria, in the form of query parameters. The following example uses the `count` summary mode to determine the number of active concept maps in the system, without returning any of the matches: ```http GET /snowowl/fhir/ConceptMap?status=active&_summary=count [Response headers] Content-Type: application/fhir+json { "resourceType": "Bundle", "id": "conceptmaps", "meta": { "lastUpdated": "2023-11-30T16:52:08.443803Z" }, "type": "searchset", "total": 22 } ``` {% hint style="danger" %} Just as with code system and value set resources, POST requests for `search` interactions are unsupported in Snow Owl and will result in a `405 Method Not Allowed` response. {% endhint %} The following search parameters are supported:
NameDescription
_id Matches concept maps by logical identifier
name Matches concept maps by name (in Snow Owl this is set to the logical identifier)
titleMatches concept maps by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)
urlMatches concept maps by their assigned url value
version Matches concept maps by their version value
status Matches concept maps by resource status (e.g. draft, active, etc.)
## Operations ### $translate Snow Owl TS uses the path parameter (and optionally, `conceptMapVersion`) to identify the concept map used for the operation. Supplying a concept map resource "inline" as input parameter `conceptMap` is not supported. Parameters `sourceScope` and `targetScope` are also ignored. The presence of a `source*` parameter (code, coding or `CodeableConcept`) implies that the translation needs to find "forward" (target) matches, while `target*` codes, codings or `CodeableConcept`s will run the translation in reverse. An example translation request can be seen below: ```http GET /snowowl/fhir/ConceptMap/cndkDE31kfeXw8/$translate?system=http://snomed.info/sct&code=103015000 [Query parametes (repeated for clarity)] system: http://snomed.info/sct code: 103015000 [Response headers] Content-Type: application/fhir+json { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "message", "valueString": "1 member(s) from concept map: cndkDE31kfeXw8" }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "codesystems/example-lcs-1", "code": "C00", "display": "Root concept" } }, { "name": "originMap", "valueUri": "cndkDE31kfeXw8" } ] } ] } ``` If you need to run the operation on a versioned resource representation, add a `conceptMapVersion` parameter to its input: [Operation $translate on ConceptMap, In Parameters](https://www.hl7.org/fhir/conceptmap-operation-translate.html) SNOMED CT Implicit Concept Maps are also supported for translation: ```http GET /snowowl/fhir/ConceptMap/$translate?url=http://snomed.info/sct/900000000000207008?fhir_cm=447562003&sourceCode=86299006 [Query parametes (repeated for clarity)] // SNOMED CT to ICD-10 extended map url: http://snomed.info/sct/900000000000207008?fhir_cm=447562003 // Tetralogy of Fallot sourceCode: 86299006 [Response headers] Content-Type: application/fhir+json { "resourceType" : "Parameters", "parameter" : [{ "name" : "result", "valueBoolean" : true }, { "name" : "message", "valueString" : "1 member(s) from concept map: http://snomed.info/sct/900000000000207008?fhir_cm=447562003" }, { "name" : "match", "part" : [{ "name" : "originMap", "valueUri" : "http://snomed.info/sct/900000000000207008?fhir_cm=447562003" }, { "name" : "relationship", "valueCode" : "related-to" }, { "name" : "concept", "valueCoding" : { "code" : "Q21.3" } }] }] } ```