Data map API Spec: Difference between revisions
ErgoSoftUK (talk | contribs) (Created blank page) |
ErgoSoftUK (talk | contribs) (Initial draft) |
||
Line 1: | Line 1: | ||
=== 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...<syntaxhighlight lang="json"> | |||
{ | |||
"Context": "/BRTS/CRNR/CDS/EMGCY/department_type" | |||
} | |||
</syntaxhighlight>...a set of identifiers...<syntaxhighlight lang="json"> | |||
{ | |||
"Provider": ":CM_Organisation_Barts", | |||
"System" : ":CM_System_Cerner", | |||
"Schema" : "CDS", | |||
"Table" : "emergency", | |||
"Column" : "department_type" | |||
} | |||
</syntaxhighlight>...or a combinaton of a partial context string with supplimentary identifiers...<syntaxhighlight lang="json"> | |||
{ | |||
"Context": "/BRTS/CRNR", | |||
"Schema" : "CDS", | |||
"Table" : "emergency", | |||
"Column" : "department_type" | |||
} | |||
</syntaxhighlight>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.<syntaxhighlight lang="mysql"> | |||
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, | |||
); | |||
</syntaxhighlight>Table entries for the examples above, all pointing to the same map node, would be as follows | |||
{| class="wikitable" | |||
!Context | |||
!Provider | |||
!System | |||
!Schema | |||
!Table | |||
!Column | |||
|- | |||
|/BRTS/CRNR/CDS/EMGCY/department_type | |||
| | |||
| | |||
| | |||
| | |||
| | |||
|- | |||
| | |||
|:CM_Organisation_Barts | |||
|:CM_System_Cerner | |||
|CDS | |||
|emergency | |||
|department_type | |||
|- | |||
|/BRTS/CRNR | |||
| | |||
| | |||
|CDS | |||
|emergency | |||
|department_type | |||
|- | |||
|/HMRTN/CRNR/EMGNCY/department_type | |||
| | |||
| | |||
| | |||
| | |||
| | |||
|} | |||
==== Node details ==== | |||
The mapping node is the effecive starting point for the maps. It represents a specific 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.<syntaxhighlight lang="mysql"> | |||
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) | |||
); | |||
</syntaxhighlight>Continuing the example above, an entry for the (organisation agnostic) CDS emergency department type mapping node would be | |||
{| class="wikitable" | |||
!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, to an Information Model concept.<syntaxhighlight lang="mysql"> | |||
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) | |||
); | |||
</syntaxhighlight>Entries for the emergency department type would be as follows | |||
{| class="wikitable" | |||
!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 === | |||
<br /> |
Revision as of 13:26, 1 July 2020
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 |
---|---|---|---|---|---|
/BRTS/CRNR/CDS/EMGCY/department_type | |||||
:CM_Organisation_Barts | :CM_System_Cerner | CDS | emergency | department_type | |
/BRTS/CRNR | CDS | emergency | department_type | ||
/HMRTN/CRNR/EMGNCY/department_type |
Node details
The mapping node is the effecive starting point for the maps. It represents a specific 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, 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