Data map API Spec

Overview

The API should take a JSON which is conforms to one of the following Information Model Schema Structures.

MapRequest
MapColumnRequest
MapColumnValueRequest

The request will contain the mapping source, provided as either

A full context string only
A partial context string and supplimentary identifiers
Identifiers only

Database Implementation

Node identification

Note: Contexts are given below in a path notation for clarity. They could just as easily be UUID's, concept IRI's or hash values, and therefore not computable. Database table data examples may also contain names or Iris in place of numeric identifiers, for clarity.

The first step of the mapping process is to identify the correct mapping node and for that, a mapping context is required. A given mapping context can be provided in a number of different ways, for example, for a Barts Cerner CDS Emergency Department type map, it could be given as a full context string...

{
    "Context": "/BRTS/CRNR/CDS/EMGCY/department_type"
}

...a set of identifiers...

{
    "Provider": ":CM_Organisation_Barts",
    "System"  : ":CM_System_Cerner",
    "Schema"  : "CDS",
    "Table"   : "emergency",
    "Column"  : "department_type"
}

...or a combinaton of a partial context string with supplimentary identifiers...

{
    "Context": "/BRTS/CRNR",
    "Schema" : "CDS",
    "Table"  : "emergency",
    "Column" : "department_type"
}

It should also be possible to map multiple contexts to a single mapping node in the event of a common map. In the above example, because the CDS Emergency department type data is an NHS Data Dictionary value set (rather than local code set), then they are organisation agnostic therefore a context of "/HMRTN/CRNR/CDS/EMGCY/department_type" should point to the same node. Indeed, if the client knows the data to be organisation agnostic, they could indeed provide only a partial set of identifier, omitting both context and provider. A map_context table is therefore required identify a node given any combination of the above.

CREATE TABLE map_context (
    `id`          INT AUTO_INCREMENT,
    `context`     VARCHAR(200) NOT NULL,
    `provider`    INT,
    `system`      INT,
    `schema`      VARCHAR(50),
    `table`       VARCHAR(100),
    `column`      VARCHAR(250),
    `node`        INT,
    `draft`       BOOLEAN NOT NULL DEFAULT TRUE,
);

Table entries for the examples above, all pointing to the same map node, would be as follows

Context	Provider	System	Schema	Table	Column	Node
/BRTS/CRNR/CDS/EMGCY/department_type						/CDS/EMGCY/department_type
	:CM_Organisation_Barts	:CM_System_Cerner	CDS	emergency	department_type	/CDS/EMGCY/department_type
/BRTS/CRNR			CDS	emergency	department_type	/CDS/EMGCY/department_type
/HMRTN/CRNR/EMGNCY/department_type						/CDS/EMGCY/department_type

Node details

The mapping node is the effecive starting point for the maps. It represents a set of codes or values within a specific context scenario. The node has associated with it its own identifier for convenience and a concept representing the data model property of that node.

CREATE TABLE map_node (
    id          INT AUTO_INCREMENT,
    node        VARCHAR(200),
    concept     INT NOT NULL,
    draft       BOOLEAN NOT NULL DEFAULT TRUE,

    PRIMARY KEY map_node_pk (id),
    UNIQUE INDEX map_node_uq (node)
);

Continuing the example above, an entry for the (organisation agnostic) CDS emergency department type mapping node would be

Node	Concept
/CDS/EMGCY/department_type	:DM_aAndEDepartmentType

Node mappings

For each node, a number of mappings exist, from either a code or a term within that node context, to an Information Model concept.

CREATE TABLE map_node_value (
    id          INT AUTO_INCREMENT,
    node        INT NOT NULL,
    value       VARCHAR(250),
    concept     INT NOT NULL,
    draft       BOOLEAN NOT NULL DEFAULT TRUE,

    PRIMARY KEY map_node_value_pk (id),
    UNIQUE INDEX map_node_value_uq (node, value)
);

Entries for the emergency department type would be as follows

Node	Value	Concept
/CDS/EMGCY/department_type	01	:CM_AEDepType1
/CDS/EMGCY/department_type	02	:CM_AEDepType2
/CDS/EMGCY/department_type	03	:CM_AEDepType3
/CDS/EMGCY/department_type	04	:CM_AEDepType4

Functional implementation

A single general mapping api will be exposed which can be called with any of the standard Map????Request structures. The existing IM client wrapper library will be extended to include mapping api calls for simplified internal use.

Node identification

Fore property concept lookups, a distinct node search is performed on the map_context table, matching on all available columns. If multiple matches are found (for example where provider is not supplied but 2 provider rows exist and point to different nodes) then an exception is thrown.

If no match is found then a new (draft) map_context row is inserted along with corresponding map_node and concept entries, using all available data.

Once the node is identified (or created), the associated property concept can be retrieved.

Node mappings

For value mappings, an additional search is performed on the map_node_value table, based on the node id and the code/term. Again if no match is found, a new (draft) concept is created and added to the mapping list.