Mappings
Overview
The API exposes a representation of mappings
to represent relationships between 2 concepts. The type of relationship is defined by the map_type
attribute. Relationships are unidirectional, originating from the from_concept
to the to_concept
, even if the inverse mapping is equivalent (e.g. “Same As” relationship). Note that the inverse mappings can be retrieved from the “to_concept” by setting the “includeInverseMappings” to true
. mappings
are also used to store hierarchical relationships (such as parent/child), and OpenMRS-specific relationships such as Question/Answer and Concept Sets.
The from_concept
must be a concept within an OCL source, while the to_concept
may refer to a concept stored in OCL or to an external code. Regardless, the definition for the source must be in OCL. If the to_concept
refers to a concept in OCL, it is referenced using the to_concept_url
field. If the to_concept
refers to an external concept, it is referenced using the to_source_url
, to_concept_code
, and (optionally) to_concept_name
fields. In other words, there are two types of to_concepts:
Internal - The
to_concept
is stored in OCLExternal - The
to_source
is defined in OCL (as an “external” source), but theto_concept
is not.
Following are the fields that are required for Internal and External mappings:
Field | Type | Notes |
---|---|---|
from_concept_url |
1, 2 | Required for both types of mappings. |
to_concept_url |
1 | Required for internal mappings. |
to_source_url |
2 | Required for external mappings. URL in OCL of the to_concept source (e.g. /orgs/Regenstrief/sources/LOINC/). |
to_concept_code |
2 | Required for external mappings. Identifier for the external to_concept . |
to_concept_name |
(2) | Optional for external mappings. The human-readable name for the external to_concept . |
Editing of mappings is supported, but edits that substantively change the meaning of a mapping is discouraged. For example, instead of changing the “from” or “to” concept of an existing mapping, retire the mapping and create a new one.
mappings
are owned by sources
, not by their from_concept
. Modifications to mappings do not directly effect the concepts to which they are linked. Like concepts
, mappings
will be saved as part of source versions. Mappings may point to concepts from any source, meaning that neither the “from” or “to” concept needs to be in the source that owns the mapping. This allows sources to be used as containers of a set of mappings.
Versioning of mappings
All changes to mappings are tracked and can be accessed via a mapping’s history
Get a single mapping
Get a single mapping
GET /orgs/:org/sources/:source/[:sourceVersion/]mappings/:mapping/
GET /users/:user/sources/:source/[:sourceVersion/]mappings/:mapping/
GET /user/sources/:source/[:sourceVersion/]mappings/:mapping/
Example
GET /orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/
Response
Status: 200 OK
{
"type": "Mapping",
"uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
"external_id": "a9d93ffjjen9dnfekd9",
"retired": "false",
"map_type": "Same As",
"from_source_owner": "Regenstrief",
"from_source_owner_type": "Organization",
"from_source_name": "loinc2",
"from_concept_code": "32700-7",
"from_concept_name": "Malarial Smear",
"from_source_url": "/orgs/Regenstrief/sources/loinc2/",
"from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
"to_source_owner": "WHO",
"to_source_owner_type": "Organization",
"to_source_name": "ICPC-2",
"to_concept_code": "A73",
"to_concept_name": "Malaria",
"to_source_url": "/orgs/WHO/sources/ICPC-2/",
"source": "loinc2",
"owner": "Regenstrief",
"owner_type": "Organization",
"owner_url": "/orgs/Regenstrief/",
"url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
"extras": {},
"created_on": "2008-01-14T04:33:35Z",
"created_by": "johndoe",
"updated_on": "2008-02-18T09:10:16Z",
"updated_by": "johndoe"
}
List mappings for a concept within a single source
List mappings or inverse mappings for a concept that are contained in the same source as the concept
GET /user/sources/:source/[:sourceVersion/]concepts/:concept/mappings/
GET /users/:user/sources/:source/[:sourceVersion/]concepts/:concept/mappings/
GET /orgs/:org/sources/:source/[:sourceVersion/]concepts/:concept/mappings/
Notes
Use the
/mappings/
endpoint to view mappings across public sources or use/orgs/:org/sources/:source/mappings/
for private sources.
Parameters
verbose (optional) string - default is false; set to true to return full mapping details instead of the summary
includeRetired (optional) string - default - “false”; set to “true” to return retired mappings
includeInverseMappings (optional) string - default is “false”; set to “true” to return inverse mappings
Response
Status: 200 OK
[
{
"map_type": "Same As",
"retired": "false",
"source": "loinc2",
"owner": "Regenstrief",
"owner_type": "Organization",
"from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
"to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
"url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
},
{
"map_type": "Narrower Than",
"retired": "false",
"source": "loinc2",
"owner": "Regenstrief",
"owner_type": "Organization",
"from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
"to_concept_code": "A73",
"to_concept_name": "Malaria",
"to_source_code": "ICPC-2",
"url": "/orgs/Regenstrief/sources/loinc2/def3fe-c2cc-11de-8d13-asdf9393930/",
},
{
"map_type": "Same As",
"retired": "false",
"source": "loinc2",
"owner": "Regenstrief",
"owner_type": "Organization",
"to_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
"from_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
"url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffdea/",
}
]
List all mappings within a specific source
List all mappings within an organization or user’s source
GET /orgs/:org/sources/:source/[:sourceVersion/]mappings/
GET /users/:user/sources/:source/[:sourceVersion/]mappings/
GET /user/sources/:source/[:sourceVersion/]mappings/
Notes
Retired mappings are excluded by default
Parameters
verbose (optional) string - default is false; set to true to return full mapping details instead of the summary
q (optional) string - ID of the “from” or “to” concept
includeRetired (optional) string - default is “false”; set to “true” to return retired mappings
mapType (optional) string - mapType descriptor, such as “Same As”, “Parent”, “Child”, etc.
Sources
conceptSource (optional) string - comma-separated list of sources for the “from” or “to” source; can be the “code” for the source (e.g. “SNOMED-CT” or “ICPC-2”) or the fully specified URL
fromConceptSource (optional) string - comma-separated list of source IDs for the “from” source (e.g. “SNOMED-CT” or “ICPC-2”)
toConceptSource (optional) string - comma-separated list of source IDs for the “to” source (e.g. “SNOMED-CT” or “ICPC-2”)
Concepts
concept (optional) string - comma-separated list of concept IDs for the “from” or “to” concept (e.g. A57)
fromConcept (optional) string - comma-separated list of concept IDs for the “from” concept (e.g. A57)
toConcept (optional) string - comma-separated list of concept IDs for the “to” concept (e.g. A57)
Example
GET /orgs/Regenstrief/sources/loinc2/mappings/
Response
Status: 200 OK
[
{
"map_type": "Same As",
"retired": "false",
"source": "loinc2",
"owner": "Regenstrief",
"owner_type": "Organization",
"from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
"to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
"url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
}
]
List mappings across public sources
List mappings across all public sources
GET /mappings/
Parameters
q (optional) string - ID of the “from” or “to” concept
includeRetired (optional) string - default is “false”; set to “true” to return retired mappings
mapType (optional) string - map type descriptor, such as “Same As”, “Parent”, “Child”, etc.
Sources
conceptSource (optional) string - comma-separated list of source IDs for the “from” or “to” source (e.g. “SNOMED-CT” or “ICPC-2”)
fromConceptSource (optional) string - comma-separated list of source IDs for the “from” source (e.g. “SNOMED-CT” or “ICPC-2”)
toConceptSource (optional) string - comma-separated list of source IDs for the “to” source (e.g. “SNOMED-CT” or “ICPC-2”)
Concepts
concept (optional) string - comma-separated list of concept IDs for the “from” or “to” concept (e.g. A57)
fromConcept (optional) string - comma-separated list of concept IDs for the “from” concept (e.g. A57)
toConcept (optional) string - comma-separated list of concept IDs for the “to” concept (e.g. A57)
Response
Status: 200 OK
[
{
"map_type": "Same As",
"retired": "false",
"source": "loinc2",
"owner": "Regenstrief",
"owner_type": "Organization",
"from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
"to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
"url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
}
]
Create a new mapping
Create a new mapping
POST /user/sources/:source/mappings/
POST /users/:user/sources/:source/mappings/
POST /orgs/:org/sources/:source/mappings/
Input
Internal Mapping:
from_concept
andto_concept
are stored in OCLid (optional) string - ID is auto-generated if not provided
map_type (required) string - map type
external_id (optional) string - external unique identifier for import/export
from_concept_url (required) string - relative URL of the “from” concept
to_concept_url (required) string - relative URL for the “to” concept
External Mapping:
from_concept
is stored in OCL;to_source
is defined in OCL, butto_concept
is notid (optional) string - ID is auto-generated if not provided
map_type (required) string - map type
external_id (optional) string - external unique identifier for import/export
from_concept_url (required) string - relative URL of the “from” concept
to_source_url (required) string - relative URL of the “to” source (must be stored in OCL)
to_concept_code (required) string - code for the external
to_concept
to_concept_name (optional) string - name of the external
to_concept
Examples
Internal mapping:
to_concept
is stored in OCL:
{
"map_type": "Same As",
"from_concept_url": "/orgs/Columbia/sources/CIEL/concepts/161426/",
"to_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/"
}
External mapping:
to_concept
is not stored in OCL (butto_source_url
is defined in OCL):
{
"map_type": "Narrower Than",
"from_concept_url": "/orgs/Columbia/sources/CIEL/concepts/116125/",
"to_source_url": "/orgs/WHO/sources/ICPC-2/",
"to_concept_code": "A73",
"to_concept_name": "Malaria"
}
Response
Status: 201 Created
Location: http://api.openconceptlab.com/orgs/Columbia/sources/CIEL/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/
Returns the JSON representation of the new mapping in the same format as Get a single mapping
Edit a mapping
Edit a mapping
PUT /user/sources/:source/mappings/:mapping/
PUT /users/:user/sources/:source/mappings/:mapping/
PUT /orgs/:org/sources/:source/mappings/:mapping/
Input
Internal Mapping:
to_concept
is stored in OCLmap_type (optional) string - map type
external_id (optional) string - external unique identifier for import/export
from_concept_url (optional) string - relative URL of the “from” concept
to_concept_url (optional) string - relative URL of the “to” concept
External Mapping:
to_concept
is not stored in OCLmap_type (optional) string - map type
external_id (optional) string - external unique identifier for import/export
from_concept_url (optional) string - relative URL of the “from” concept
to_source_url (optional) string - relative URL of the “to” source - note that the source must be defined in OCL
to_concept_code (optional) string - code for the external
to_concept
to_concept_name (optional) string - name of the external
to_concept
Examples
Internal Mapping:
to_concept
is stored in OCL
{
"map_type": "Same As",
"to_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/"
}
External Mapping:
to_concept
is not stored in OCL
{
"map_type": "Narrower Than",
"to_source_code": "ICPC-2",
"to_concept_code": "A73",
"to_concept_name": "Malaria",
}
Response
Status: 200 OK
Returns the updated JSON representation of the mapping in the same format as Get a single mapping
Retire mapping
Retire a mapping
DELETE /user/sources/:source/mappings/:mapping/
DELETE /users/:user/sources/:source/mappings/:mapping/
DELETE /orgs/:org/sources/:source/mappings/:mapping/
Parameters
purge (optional) string - default is “false”; set to “true” to actually delete the mapping from all source versions
Notes
DELETE does not actually delete the mapping unless “purge” is set to “true”; rather, it sets its “retired” attribute to “true” so that it does not show up by default in results, and it indicates to users that the mapping should no longer be used.
Response
Status: 204 No Content
Search and Filter Behavior
Text Search (e.g.
q=criteria
) - NOTE: Number of plus-signs (+) indicates relative relevancy weight of the termNote that search criteria should be surrounded by quotes to appropriately handle whitespace, e.g.
https://api.openconceptlab.org/mappings/?concept=%22Disorder%20of%20Lymphatic%20System
mapping.from_concept_code (++++), mapping.to_concept_code (++++), mapping.from_concept_name (++), mapping.to_concept_name (++)
external_id (+)
Facets
retired - mapping.retired
mapType - mapping.map_type
source - mapping.source
owner - mapping.owner
ownerType - mapping.owner_type
conceptSource - mapping.from_concept.source OR mapping.to_concept.source
fromConceptSource - mapping.from_concept.source
toConceptSource - mapping.to_concept.source
conceptOwner - mapping.from_concept.owner OR mapping.to_concept.owner
fromConceptOwner - mapping.to_concept.owner
toConceptOwner - mapping.to_concept.owner
conceptOnwerType - mapping.from_concept_owner_type OR mapping.to_concept_owner_type
fromConceptOnwerType - mapping.from_concept_owner_type
toConceptOnwerType - mapping.to_concept_owner_type
Filters
concept - mapping.from_concept_code OR mapping.to_concept_code OR mapping.from_concept_name OR mapping.to_concept_name
fromConcept - mapping.from_concept_code OR mapping.from_concept_name
toConcept - mapping.to_concept_code OR mapping.to_concept_name
Sort
bestMatch (default) - see text search fields above
name (Asc/Desc) - mapping.name
lastUpdated (Asc/Desc) - mapping.updated_on
Issues and Potential Future Features
Add support for URL parameters for filtering mappings (e.g. “fromConcept=/orgs/CIEL/sources/CIEL/concepts/3/”)