sdc-mapper 4.3.2__tar.gz → 4.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {sdc_mapper-4.3.2/src/sdc_mapper.egg-info → sdc_mapper-4.4.0}/PKG-INFO +27 -3
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/README.md +25 -1
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/pyproject.toml +2 -2
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/__init__.py +1 -1
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/engine.py +3 -2
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/gate.py +20 -31
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/mapping.py +54 -14
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/mcp_server.py +10 -3
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/placement.py +5 -3
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/resolve.py +7 -1
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/schemas/mapping.schema.json +66 -4
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0/src/sdc_mapper.egg-info}/PKG-INFO +27 -3
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/SOURCES.txt +1 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/requires.txt +1 -1
- sdc_mapper-4.4.0/tests/test_reference_model.py +205 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/LICENSE +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/NOTICE +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/setup.cfg +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/cli.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/codes.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/contract.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/log.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/report.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/schemas/log-entry.schema.json +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/schemas/sdc4.xsd +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/service.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/dependency_links.txt +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/entry_points.txt +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/top_level.txt +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/tests/test_codes.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/tests/test_core.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/tests/test_placement.py +0 -0
- {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/tests/test_service.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: sdc-mapper
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.4.0
|
|
4
4
|
Summary: The shared core of the Semantic Data Charter's Governed Data Record mappers: validate, resolve, map, and report every value; MCP server included.
|
|
5
5
|
Author: Axius SDC, Inc.
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -11,7 +11,7 @@ Requires-Python: >=3.12
|
|
|
11
11
|
Description-Content-Type: text/markdown
|
|
12
12
|
License-File: LICENSE
|
|
13
13
|
License-File: NOTICE
|
|
14
|
-
Requires-Dist: sdcreader<5,>=4.
|
|
14
|
+
Requires-Dist: sdcreader<5,>=4.5
|
|
15
15
|
Requires-Dist: sdcvalidator<5,>=4.6
|
|
16
16
|
Requires-Dist: xmlschema>=3.0
|
|
17
17
|
Requires-Dist: pyyaml>=6.0
|
|
@@ -33,7 +33,7 @@ target could say it too. Every call is appended to a hash-chained log that holds
|
|
|
33
33
|
Each target format is its own package (`sdc-gdr2ubl`, `sdc-gdr2edifact`, `sdc-gdr2omop`, ...) registered under the
|
|
34
34
|
entry-point group `sdc_mapper.targets`. Outbound only. Apache 2.0.
|
|
35
35
|
|
|
36
|
-
**Status:** 4.
|
|
36
|
+
**Status:** 4.4.0. Five target mappers are released: `sdc-gdr2ubl` (OASIS UBL 2.3), `sdc-gdr2edifact` (UN/EDIFACT
|
|
37
37
|
D.24A), `sdc-gdr2omop` (OMOP CDM 5.4), `sdc-gdr2fhir` (HL7 FHIR R4) and `sdc-gdr2hl7v2` (HL7 v2.5.1).
|
|
38
38
|
|
|
39
39
|
## Use
|
|
@@ -50,6 +50,8 @@ sdc-mapper [--log-dir DIR] [--host URL] # MCP stdio server (also sdc-
|
|
|
50
50
|
A model is a package directory (`dm-<ct>.jsonld`, `dm-<ct>.xsd`) or a published model's `--ct-id`, fetched from the
|
|
51
51
|
SDCStudio host; with neither, the record's own root names it. Exit status: 0 mapped, 1 refused, 2 error.
|
|
52
52
|
|
|
53
|
+
Also listed on [mcprush](https://mcprush.com/semanticdatacharter/sdc-mapper-mcp).
|
|
54
|
+
|
|
53
55
|
## The three outcomes
|
|
54
56
|
|
|
55
57
|
- **valid:** mapped.
|
|
@@ -95,6 +97,28 @@ reports it as a lookup (`LOOKUP_TRANSFORMS`). Steps: `..` up, `.` none, `+name`
|
|
|
95
97
|
the element of that name the parent already has. `within:` restricts a rule to a context. A value no rule reaches is
|
|
96
98
|
reported, never dropped. `place(record, mapping)` turns a record and its mapping into placements a mapper writes from.
|
|
97
99
|
|
|
100
|
+
**The reference-model parts (4.4.0).** `reference_model: true` reads a record's subject, providers, Participations,
|
|
101
|
+
protocol, workflow, acs, Audits and attestation as well as its data cluster. A Party, its details cluster and their
|
|
102
|
+
components are named by identifier, as anywhere; `cluster` and `within` may also name the reference-model element a part
|
|
103
|
+
stands in, and `element` a reference-model element that holds a value:
|
|
104
|
+
|
|
105
|
+
```yaml
|
|
106
|
+
reference_model: true
|
|
107
|
+
rules:
|
|
108
|
+
- cluster: <Author> # the record's provider Party
|
|
109
|
+
to: /entry#author/resource
|
|
110
|
+
- component: <Given Name (Person)>
|
|
111
|
+
within: [<Author>] # the Author's details, not the Patient's
|
|
112
|
+
to: name/given
|
|
113
|
+
transform: copy
|
|
114
|
+
- cluster: subject # whatever Party the record's subject is
|
|
115
|
+
to: /entry#patient/resource
|
|
116
|
+
- element: start # a Participation's start (xsd:dateTime, read as a temporal value)
|
|
117
|
+
within: [<Attester Participation>]
|
|
118
|
+
to: time
|
|
119
|
+
transform: copy
|
|
120
|
+
```
|
|
121
|
+
|
|
98
122
|
## Codes the model names
|
|
99
123
|
|
|
100
124
|
`sdc_mapper.codes` reads the IRIs the component libraries use for a concept as a code system and a code: LOINC codes
|
|
@@ -11,7 +11,7 @@ target could say it too. Every call is appended to a hash-chained log that holds
|
|
|
11
11
|
Each target format is its own package (`sdc-gdr2ubl`, `sdc-gdr2edifact`, `sdc-gdr2omop`, ...) registered under the
|
|
12
12
|
entry-point group `sdc_mapper.targets`. Outbound only. Apache 2.0.
|
|
13
13
|
|
|
14
|
-
**Status:** 4.
|
|
14
|
+
**Status:** 4.4.0. Five target mappers are released: `sdc-gdr2ubl` (OASIS UBL 2.3), `sdc-gdr2edifact` (UN/EDIFACT
|
|
15
15
|
D.24A), `sdc-gdr2omop` (OMOP CDM 5.4), `sdc-gdr2fhir` (HL7 FHIR R4) and `sdc-gdr2hl7v2` (HL7 v2.5.1).
|
|
16
16
|
|
|
17
17
|
## Use
|
|
@@ -28,6 +28,8 @@ sdc-mapper [--log-dir DIR] [--host URL] # MCP stdio server (also sdc-
|
|
|
28
28
|
A model is a package directory (`dm-<ct>.jsonld`, `dm-<ct>.xsd`) or a published model's `--ct-id`, fetched from the
|
|
29
29
|
SDCStudio host; with neither, the record's own root names it. Exit status: 0 mapped, 1 refused, 2 error.
|
|
30
30
|
|
|
31
|
+
Also listed on [mcprush](https://mcprush.com/semanticdatacharter/sdc-mapper-mcp).
|
|
32
|
+
|
|
31
33
|
## The three outcomes
|
|
32
34
|
|
|
33
35
|
- **valid:** mapped.
|
|
@@ -73,6 +75,28 @@ reports it as a lookup (`LOOKUP_TRANSFORMS`). Steps: `..` up, `.` none, `+name`
|
|
|
73
75
|
the element of that name the parent already has. `within:` restricts a rule to a context. A value no rule reaches is
|
|
74
76
|
reported, never dropped. `place(record, mapping)` turns a record and its mapping into placements a mapper writes from.
|
|
75
77
|
|
|
78
|
+
**The reference-model parts (4.4.0).** `reference_model: true` reads a record's subject, providers, Participations,
|
|
79
|
+
protocol, workflow, acs, Audits and attestation as well as its data cluster. A Party, its details cluster and their
|
|
80
|
+
components are named by identifier, as anywhere; `cluster` and `within` may also name the reference-model element a part
|
|
81
|
+
stands in, and `element` a reference-model element that holds a value:
|
|
82
|
+
|
|
83
|
+
```yaml
|
|
84
|
+
reference_model: true
|
|
85
|
+
rules:
|
|
86
|
+
- cluster: <Author> # the record's provider Party
|
|
87
|
+
to: /entry#author/resource
|
|
88
|
+
- component: <Given Name (Person)>
|
|
89
|
+
within: [<Author>] # the Author's details, not the Patient's
|
|
90
|
+
to: name/given
|
|
91
|
+
transform: copy
|
|
92
|
+
- cluster: subject # whatever Party the record's subject is
|
|
93
|
+
to: /entry#patient/resource
|
|
94
|
+
- element: start # a Participation's start (xsd:dateTime, read as a temporal value)
|
|
95
|
+
within: [<Attester Participation>]
|
|
96
|
+
to: time
|
|
97
|
+
transform: copy
|
|
98
|
+
```
|
|
99
|
+
|
|
76
100
|
## Codes the model names
|
|
77
101
|
|
|
78
102
|
`sdc_mapper.codes` reads the IRIs the component libraries use for a concept as a code system and a code: LOINC codes
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "sdc-mapper"
|
|
7
|
-
version = "4.
|
|
7
|
+
version = "4.4.0"
|
|
8
8
|
description = "The shared core of the Semantic Data Charter's Governed Data Record mappers: validate, resolve, map, and report every value; MCP server included."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.12"
|
|
@@ -15,7 +15,7 @@ classifiers = [
|
|
|
15
15
|
"Programming Language :: Python :: 3",
|
|
16
16
|
]
|
|
17
17
|
dependencies = [
|
|
18
|
-
"sdcreader>=4.
|
|
18
|
+
"sdcreader>=4.5,<5", # the package, the model and the record reader (cluster instances: 4.4.0; reference-model parts: 4.5.0)
|
|
19
19
|
"sdcvalidator>=4.6,<5", # the validation gate: recover() (4.6.0) keeps source Exceptional Values
|
|
20
20
|
"xmlschema>=3.0", # XMLResource, so prefixed QNames in content (xsi:type) resolve
|
|
21
21
|
"pyyaml>=6.0", # mapping files
|
|
@@ -20,7 +20,7 @@ from .placement import JOIN, LOOKUP_TRANSFORMS, ClusterPlacement, Extra, Placeme
|
|
|
20
20
|
from .report import CoverageReport, IncompleteMapping, build_report
|
|
21
21
|
from .resolve import Exceptional, ResolvedRecord, ResolvedValue, Units, resolve
|
|
22
22
|
|
|
23
|
-
__version__ = "4.
|
|
23
|
+
__version__ = "4.4.0"
|
|
24
24
|
__all__ = [
|
|
25
25
|
"Engine", "CallResult", "Gate", "GateResult", "Recovery", "Log", "entry_hash", "Mapping", "MappingError", "Rule",
|
|
26
26
|
"load_mapping", "place", "Placement", "ClusterPlacement", "Extra", "JOIN", "join_depth", "LOOKUP_TRANSFORMS", "CodeRef", "code_of",
|
|
@@ -76,12 +76,13 @@ class Engine:
|
|
|
76
76
|
except MappingError as e:
|
|
77
77
|
return self._finish(CallResult(ERROR, errors=[{"kind": "mapping", "reason": str(e)}]), base)
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
rm = bool(mapping and mapping.reference_model) # the reference-model parts, read only when the mapping asks
|
|
80
|
+
gate = self.gate.check(xml, pkg, model, reference_model=rm)
|
|
80
81
|
if gate.outcome == REFUSED:
|
|
81
82
|
return self._finish(CallResult(REFUSED, errors=gate.errors), base)
|
|
82
83
|
|
|
83
84
|
try:
|
|
84
|
-
resolved = resolve(read_record(gate.xml, model), model, pkg, gate)
|
|
85
|
+
resolved = resolve(read_record(gate.xml, model, reference_model=rm), model, pkg, gate)
|
|
85
86
|
result = mapper.map(resolved, mapping)
|
|
86
87
|
report = build_report(resolved, result, mapper, mapping)
|
|
87
88
|
except IncompleteMapping as e:
|
|
@@ -20,7 +20,8 @@ import threading
|
|
|
20
20
|
from dataclasses import dataclass, field
|
|
21
21
|
from pathlib import Path
|
|
22
22
|
|
|
23
|
-
from sdcreader import
|
|
23
|
+
from sdcreader import Model, ModelPackage
|
|
24
|
+
from sdcreader.record import walk_values
|
|
24
25
|
from sdcvalidator import (SDC4StructuralValidationError, SDC4Validator, build_xsd11_schema, etree_tostring,
|
|
25
26
|
validate_sdc4_schema_compliance)
|
|
26
27
|
from xmlschema import XMLResource
|
|
@@ -83,7 +84,9 @@ class Gate:
|
|
|
83
84
|
self._validators[sha] = v
|
|
84
85
|
return v
|
|
85
86
|
|
|
86
|
-
def check(self, xml: bytes, pkg: ModelPackage, model: Model) -> GateResult:
|
|
87
|
+
def check(self, xml: bytes, pkg: ModelPackage, model: Model, reference_model: bool = False) -> GateResult:
|
|
88
|
+
"""`reference_model`: number values as sdcreader does when it also reads the reference-model parts (4.4.0), so
|
|
89
|
+
a recovery inside a Party's details or a Participation's function lands on the value the reader gives."""
|
|
87
90
|
try:
|
|
88
91
|
resource = XMLResource(io.BytesIO(xml))
|
|
89
92
|
except Exception as e: # noqa: BLE001 xmlschema raises its own and the parser's errors
|
|
@@ -101,15 +104,16 @@ class Gate:
|
|
|
101
104
|
return GateResult(VALID, xml=xml)
|
|
102
105
|
|
|
103
106
|
root = result.tree.getroot()
|
|
104
|
-
|
|
107
|
+
values = _value_elements(root, model, reference_model)
|
|
108
|
+
positions = {id(el): i for i, (el, _) in enumerate(values)}
|
|
105
109
|
recoveries = []
|
|
106
110
|
for r in result.inserted: # an Exceptional Value the record already carried is the source's, not the gate's
|
|
107
|
-
comp = _component_element(root, _find(root, r.path),
|
|
111
|
+
comp = _component_element(root, _find(root, r.path), positions)
|
|
108
112
|
if comp is None:
|
|
109
113
|
return GateResult(REFUSED, errors=[{"kind": "not recoverable", "path": r.path,
|
|
110
114
|
"reason": "the recovered value is not inside a value component"}])
|
|
111
|
-
|
|
112
|
-
|
|
115
|
+
i = positions[id(comp)]
|
|
116
|
+
recoveries.append(Recovery(position=i, ct_id=values[i][1], code=r.code, constraint=r.reason))
|
|
113
117
|
recovered = etree_tostring(root, namespaces=resource.get_namespaces(root_only=False) or {"sdc4": SDC4_NS},
|
|
114
118
|
xml_declaration=True, encoding="utf-8")
|
|
115
119
|
return GateResult(VALID_WITH_EV, xml=recovered if isinstance(recovered, bytes) else recovered.encode("utf-8"),
|
|
@@ -143,37 +147,22 @@ def _find(root, path: str):
|
|
|
143
147
|
return el
|
|
144
148
|
|
|
145
149
|
|
|
146
|
-
def _component_element(root, el,
|
|
147
|
-
"""The leaf component
|
|
150
|
+
def _component_element(root, el, positions: dict[int, int]):
|
|
151
|
+
"""The value element (a leaf component's `sdc4:ms-<ct_id>`, or since 4.4.0 a reference-model element such as a
|
|
152
|
+
Participation's function) that holds `el`, or None."""
|
|
148
153
|
parents = {c: p for p in root.iter() for c in p}
|
|
149
154
|
while el is not None:
|
|
150
|
-
if el
|
|
151
|
-
|
|
152
|
-
if comp is not None and comp.sdc_type in LEAF_TYPES:
|
|
153
|
-
return el
|
|
155
|
+
if id(el) in positions:
|
|
156
|
+
return el
|
|
154
157
|
el = parents.get(el)
|
|
155
158
|
return None
|
|
156
159
|
|
|
157
160
|
|
|
158
|
-
def
|
|
159
|
-
"""
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
def walk(el):
|
|
164
|
-
nonlocal n
|
|
165
|
-
for c in el:
|
|
166
|
-
if not (isinstance(c.tag, str) and c.tag.startswith(f"{{{SDC4_NS}}}ms-")):
|
|
167
|
-
continue
|
|
168
|
-
comp = model.components.get(c.tag.split("ms-", 1)[1])
|
|
169
|
-
if comp is not None and comp.sdc_type in LEAF_TYPES:
|
|
170
|
-
out[id(c)] = n
|
|
171
|
-
n += 1
|
|
172
|
-
else:
|
|
173
|
-
walk(c)
|
|
174
|
-
|
|
175
|
-
walk(root)
|
|
176
|
-
return out
|
|
161
|
+
def _value_elements(root, model: Model, reference_model: bool = False) -> list[tuple]:
|
|
162
|
+
"""Every value element in document order with its component's identifier: the numbering sdcreader's
|
|
163
|
+
`read_record` gives the same record (its own walk, so the two cannot drift). The elements are held in the list,
|
|
164
|
+
so their ids stay valid while it lives."""
|
|
165
|
+
return [(t[0], t[1].ct_id) for t in walk_values(root, model, reference_model)]
|
|
177
166
|
|
|
178
167
|
|
|
179
168
|
def sha256(data: bytes) -> str:
|
|
@@ -11,6 +11,7 @@ from typing import Any
|
|
|
11
11
|
|
|
12
12
|
import yaml
|
|
13
13
|
from jsonschema import Draft202012Validator
|
|
14
|
+
from sdcreader.model import RM_ELEMENTS, RM_PARTS
|
|
14
15
|
|
|
15
16
|
SCHEMA_PATH = Path(__file__).with_name("schemas") / "mapping.schema.json"
|
|
16
17
|
|
|
@@ -44,10 +45,12 @@ class Rule:
|
|
|
44
45
|
system: str | None = None # binding, link: the code system the code must be in
|
|
45
46
|
predicates: list[str] = field(default_factory=list) # link: the links to read, in order
|
|
46
47
|
order: int | None = None
|
|
48
|
+
element: str | None = None # a reference-model element (4.4.0): "start", "party-name", "committed", ...
|
|
47
49
|
|
|
48
50
|
def applies_within(self, ancestors: list[str]) -> bool:
|
|
49
51
|
"""`within` names clusters that must enclose the target, outermost first; each must appear among the
|
|
50
|
-
ancestors in that order (not necessarily adjacent).
|
|
52
|
+
ancestors in that order (not necessarily adjacent). Since 4.4.0 an ancestor is a cluster's identifier or the
|
|
53
|
+
reference-model element it stands in ("subject", "performer", "party-details"); see `ancestor_tokens`."""
|
|
51
54
|
i = 0
|
|
52
55
|
for ct in ancestors:
|
|
53
56
|
if i < len(self.within) and ct == self.within[i]:
|
|
@@ -69,20 +72,39 @@ class Mapping:
|
|
|
69
72
|
carry_rejected: bool = False
|
|
70
73
|
profile_of: str | None = None
|
|
71
74
|
raw: dict[str, Any] = field(default_factory=dict)
|
|
75
|
+
reference_model: bool = False # read the record's reference-model parts beyond the data cluster (4.4.0)
|
|
72
76
|
|
|
73
|
-
def rule_for(self, ct_id: str, sdc_type: str, ancestors: list[str] | None = None) -> Rule | None:
|
|
74
|
-
"""The rule for a value: its component's own rule wins
|
|
75
|
-
|
|
77
|
+
def rule_for(self, ct_id: str, sdc_type: str, ancestors: list[str] | None = None, role: str = "") -> Rule | None:
|
|
78
|
+
"""The rule for a value: its component's own rule wins, then the rule for the reference-model element it
|
|
79
|
+
stands in (`role`, 4.4.0), then its type's default; among several, the one with the longest `within` that
|
|
80
|
+
applies. `ancestors` are the enclosing clusters' identifiers, root first (`ancestor_tokens`)."""
|
|
76
81
|
ancestors = ancestors or []
|
|
77
|
-
for pick in (lambda r: r.component == ct_id, lambda r: r.
|
|
82
|
+
for pick in (lambda r: r.component == ct_id, lambda r: bool(role) and r.element == role,
|
|
83
|
+
lambda r: r.sdc_type == sdc_type):
|
|
78
84
|
found = [r for r in self.rules if pick(r) and r.applies_within(ancestors)]
|
|
79
85
|
if found:
|
|
80
86
|
return max(found, key=lambda r: len(r.within))
|
|
81
87
|
return None
|
|
82
88
|
|
|
83
|
-
def cluster_rule(self, ct_id: str, ancestors: list[str]) -> Rule | None:
|
|
84
|
-
|
|
85
|
-
|
|
89
|
+
def cluster_rule(self, ct_id: str, ancestors: list[str], role: str = "") -> Rule | None:
|
|
90
|
+
"""The rule for a cluster instance: one naming its identifier wins over one naming the reference-model element
|
|
91
|
+
it stands in (`role`: "subject", "performer", 4.4.0); among several, the longest `within` that applies."""
|
|
92
|
+
for pick in (lambda r: r.cluster == ct_id, lambda r: bool(role) and r.cluster == role):
|
|
93
|
+
found = [r for r in self.rules if pick(r) and r.applies_within(ancestors)]
|
|
94
|
+
if found:
|
|
95
|
+
return max(found, key=lambda r: len(r.within))
|
|
96
|
+
return None
|
|
97
|
+
|
|
98
|
+
@property
|
|
99
|
+
def names_reference_model(self) -> list[str]:
|
|
100
|
+
"""The reference-model names the rules use (an `element`, or a `cluster` or `within` entry that is an element
|
|
101
|
+
name rather than an identifier)."""
|
|
102
|
+
names = []
|
|
103
|
+
for r in self.rules:
|
|
104
|
+
for n in [r.element, r.cluster, *r.within]:
|
|
105
|
+
if n and n in RM_NAMES and n not in names:
|
|
106
|
+
names.append(n)
|
|
107
|
+
return names
|
|
86
108
|
|
|
87
109
|
@property
|
|
88
110
|
def cluster_order(self) -> dict[str, int]:
|
|
@@ -114,9 +136,27 @@ def load_mapping(source: str | Path | bytes) -> Mapping:
|
|
|
114
136
|
raise MappingError("the mapping file does not validate: " + "; ".join(
|
|
115
137
|
f"{'/'.join(str(p) for p in e.path) or '(root)'}: {e.message}" for e in errors))
|
|
116
138
|
rules = [Rule(**r) for r in doc.get("rules", [])]
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
139
|
+
m = Mapping(id=doc["mapping"]["id"], version=str(doc["mapping"]["version"]),
|
|
140
|
+
sha256=hashlib.sha256(data).hexdigest(), model_ct_id=doc["model"]["ct_id"],
|
|
141
|
+
model_schema_sha256=doc["model"]["schema_sha256"], target_name=doc["target"]["name"],
|
|
142
|
+
target_version=doc["target"]["version"], rules=rules,
|
|
143
|
+
exceptional_values=doc.get("exceptional_values", {}), carry_rejected=doc.get("carry_rejected", False),
|
|
144
|
+
profile_of=doc.get("profile_of"), raw=doc, reference_model=doc.get("reference_model", False))
|
|
145
|
+
if m.names_reference_model and not m.reference_model:
|
|
146
|
+
# such a rule could never apply: the record's reference-model parts are read only when the mapping asks
|
|
147
|
+
raise MappingError(f"mapping {m.id}: rules name reference-model elements ({', '.join(m.names_reference_model)}) "
|
|
148
|
+
"but the mapping does not set `reference_model: true`")
|
|
149
|
+
return m
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
#: The reference-model element names a rule may use (sdcreader 4.5.0): parts that hold further elements, for `cluster`
|
|
153
|
+
#: and `within`, and elements that hold a value, for `element`.
|
|
154
|
+
RM_NAMES = RM_PARTS | RM_ELEMENTS
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def ancestor_tokens(path, roles) -> list[list[str]]:
|
|
158
|
+
"""Per step of a value's path, the names a rule's `within` or `cluster` matches it by: the reference-model element
|
|
159
|
+
the step stands in, if any, then its identifier. A step whose identifier is the element's own name (a part the
|
|
160
|
+
schema types by no component) is named once."""
|
|
161
|
+
roles = tuple(roles) or ("",) * len(path)
|
|
162
|
+
return [[n for n in (role, c.ct_id) if n] if role != c.ct_id else [c.ct_id] for c, role in zip(path, roles)]
|
|
@@ -25,7 +25,7 @@ from sdcreader.mcp import Server, ToolError, source_properties
|
|
|
25
25
|
|
|
26
26
|
from . import __version__
|
|
27
27
|
from .engine import Engine
|
|
28
|
-
from .mapping import MappingError, load_mapping
|
|
28
|
+
from .mapping import RM_NAMES, MappingError, load_mapping
|
|
29
29
|
from .service import ServiceError, describe, fidelity, fidelity_text, map_one, targets
|
|
30
30
|
|
|
31
31
|
SERVER_NAME = "sdc-mapper"
|
|
@@ -83,7 +83,10 @@ TOOLS = [
|
|
|
83
83
|
},
|
|
84
84
|
{
|
|
85
85
|
"name": "check_mapping",
|
|
86
|
-
"description": "Validate a mapping file against the mapping schema, and, given a model, check it is bound to that model's
|
|
86
|
+
"description": ("Validate a mapping file against the mapping schema, and, given a model, check it is bound to that model's "
|
|
87
|
+
"current schema. Since 4.4.0 also reports whether the mapping reads the record's reference-model parts "
|
|
88
|
+
"beyond the data cluster (reference_model) and the reference-model element names its rules use, and, "
|
|
89
|
+
"given a model, which identifiers its rules name that the model does not have."),
|
|
87
90
|
"inputSchema": {"type": "object", "properties": {"mapping": MAPPING, **source_properties()},
|
|
88
91
|
"required": ["mapping"], "additionalProperties": False},
|
|
89
92
|
},
|
|
@@ -136,13 +139,17 @@ def _handle_check_mapping(args: dict[str, Any]) -> Any:
|
|
|
136
139
|
except (MappingError, OSError) as e:
|
|
137
140
|
return {"ok": False, "error": str(e)}
|
|
138
141
|
out = {"ok": True, "id": m.id, "version": m.version, "sha256": m.sha256, "model": m.model_ct_id,
|
|
139
|
-
"target": f"{m.target_name} {m.target_version}", "rules": len(m.rules)
|
|
142
|
+
"target": f"{m.target_name} {m.target_version}", "rules": len(m.rules),
|
|
143
|
+
"reference_model": m.reference_model, "reference_model_names": m.names_reference_model}
|
|
140
144
|
source = {k: args[k] for k in ("ct_id", "directory") if args.get(k)}
|
|
141
145
|
if source:
|
|
142
146
|
pkg, model = _engine().packages.one(source)
|
|
143
147
|
if (m.model_ct_id, m.model_schema_sha256) != (model.ct_id, pkg.sha256):
|
|
144
148
|
out.update(ok=False, error=f"bound to {m.model_ct_id} schema {m.model_schema_sha256[:12]}; "
|
|
145
149
|
f"the model is {model.ct_id} schema {pkg.sha256[:12]}")
|
|
150
|
+
else:
|
|
151
|
+
named = {n for r in m.rules for n in (r.component, r.cluster, *r.within) if n and n not in RM_NAMES}
|
|
152
|
+
out["unknown_identifiers"] = sorted(named - set(model.components))
|
|
146
153
|
return out
|
|
147
154
|
|
|
148
155
|
|
|
@@ -16,7 +16,7 @@ from datetime import date, datetime, time
|
|
|
16
16
|
from decimal import Decimal
|
|
17
17
|
|
|
18
18
|
from .codes import CONCEPT_LINKS, bound_code, linked_code
|
|
19
|
-
from .mapping import Mapping, MappingError, Rule
|
|
19
|
+
from .mapping import Mapping, MappingError, Rule, ancestor_tokens
|
|
20
20
|
from .resolve import ResolvedRecord, ResolvedValue
|
|
21
21
|
|
|
22
22
|
#: A step of a target path: the element name, and the key of the instance that owns it. Steps with equal names and
|
|
@@ -188,11 +188,13 @@ def place(record: ResolvedRecord, mapping: Mapping) -> tuple[list[Placement], li
|
|
|
188
188
|
placements: list[Placement] = []
|
|
189
189
|
for v in record.values:
|
|
190
190
|
ids = [c.ct_id for c in v.path]
|
|
191
|
+
tokens = ancestor_tokens(v.path, v.roles) # identifiers, and the reference-model elements steps stand in
|
|
192
|
+
roles = tuple(v.roles) or ("",) * len(ids)
|
|
191
193
|
# the enclosing clusters' rules, outermost first, each resolved in its own context
|
|
192
194
|
base: list[Step] = []
|
|
193
195
|
omitted_by = None
|
|
194
196
|
for i, cid in enumerate(ids):
|
|
195
|
-
rule = mapping.cluster_rule(cid,
|
|
197
|
+
rule = mapping.cluster_rule(cid, [t for step in tokens[:i] for t in step], roles[i])
|
|
196
198
|
if rule is None:
|
|
197
199
|
continue
|
|
198
200
|
if rule.transform == "omit":
|
|
@@ -203,7 +205,7 @@ def place(record: ResolvedRecord, mapping: Mapping) -> tuple[list[Placement], li
|
|
|
203
205
|
if attr:
|
|
204
206
|
raise MappingError(f"mapping {mapping.id}: cluster rule for {cid} ends in an attribute ({rule.to})")
|
|
205
207
|
clusters.setdefault(key, ClusterPlacement(key=key, steps=list(base), attributes=dict(rule.attributes)))
|
|
206
|
-
leaf = None if omitted_by else mapping.rule_for(v.ct_id, v.sdc_type,
|
|
208
|
+
leaf = None if omitted_by else mapping.rule_for(v.ct_id, v.sdc_type, [t for step in tokens for t in step], v.role)
|
|
207
209
|
p = Placement(value=v, rule=leaf, omitted_by=omitted_by)
|
|
208
210
|
if leaf is not None and leaf.transform == "omit":
|
|
209
211
|
p.omitted_by = leaf
|
|
@@ -49,6 +49,9 @@ class ResolvedValue:
|
|
|
49
49
|
exceptional: Exceptional | None = None
|
|
50
50
|
rejected: dict = field(default_factory=dict) # recovery only: the value as the record held it; never a value
|
|
51
51
|
instances: tuple[int, ...] = () # parallel to `path`: each cluster's instance (sdcreader 4.4.0)
|
|
52
|
+
roles: tuple[str, ...] = () # parallel to `path`: the reference-model element each step stands
|
|
53
|
+
# in ("subject", "performer", "party-details"), "" for a component
|
|
54
|
+
role: str = "" # the reference-model element the value stands in ("start")
|
|
52
55
|
|
|
53
56
|
@property
|
|
54
57
|
def instance_key(self) -> tuple[tuple[str, int], ...]:
|
|
@@ -81,6 +84,7 @@ class ResolvedRecord:
|
|
|
81
84
|
attributes: dict[str, str]
|
|
82
85
|
outcome: str # the gate's: valid or valid_with_ev
|
|
83
86
|
values: list[ResolvedValue]
|
|
87
|
+
reference_model: bool = False # read with the reference-model parts beyond the data cluster (4.4.0)
|
|
84
88
|
|
|
85
89
|
@property
|
|
86
90
|
def instance_id(self) -> str:
|
|
@@ -105,6 +109,7 @@ def resolve(record: Record, model: Model, pkg: ModelPackage, gate: GateResult) -
|
|
|
105
109
|
ct_id=model.ct_id, title=model.title, schema_sha256=pkg.sha256, schema_url=pkg.schema_url_pinned,
|
|
106
110
|
dublin_core={k: v for k in DC_FIELDS if (v := (model.contributors if k == "contributor" else model.dc(k)))},
|
|
107
111
|
attributes=dict(record.attributes), outcome=gate.outcome, values=values,
|
|
112
|
+
reference_model=getattr(record, "reference_model", False),
|
|
108
113
|
)
|
|
109
114
|
|
|
110
115
|
|
|
@@ -130,7 +135,8 @@ def _resolve(v, model: Model, constraints: dict[int, str]) -> ResolvedValue:
|
|
|
130
135
|
value=value, detail=detail, units=units, code=code, links=dict(comp.links),
|
|
131
136
|
context=dict(v.context), exceptional=exceptional,
|
|
132
137
|
rejected=dict(v.elements) if exceptional and exceptional.origin == "recovery" else {},
|
|
133
|
-
instances=tuple(getattr(v, "instances", ())) or tuple(0 for _ in v.path)
|
|
138
|
+
instances=tuple(getattr(v, "instances", ())) or tuple(0 for _ in v.path),
|
|
139
|
+
roles=tuple(getattr(v, "roles", ())) or tuple("" for _ in v.path), role=getattr(v, "role", ""))
|
|
134
140
|
|
|
135
141
|
|
|
136
142
|
def _text(x) -> str | None:
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://semanticdatacharter.com/schemas/sdc-mapper/mapping-4.json",
|
|
4
4
|
"title": "sdc-mapper mapping file",
|
|
5
|
-
"description": "How one model's components reach one target where the model alone does not settle it. Bound to one model schema version and one target version; immutable once published. No expressions or code. Since 4.1.0, rules may map a cluster to a target element (with a `within` context for a cluster used in several places), target paths are relative to the enclosing mapped cluster unless they start with '/', a final '@name' step places an attribute, and a `units` sub-rule places a quantity's unit. A '..' step goes up from the enclosing mapped cluster's element, a '.' step is no step, and a step prefixed '+' makes a new element for each value rather than sharing one by name. `also` writes the same value to further places; `on_miss: omit` leaves a code-table miss unwritten instead of failing. The `binding` transform writes the code the model binds a value to (the fragment of the IRI its enumeration value is defined by, under `prefix`): the model, not the mapping, supplies the value. A step written '=name' joins the element of that name its parent already has (one a nested cluster makes), or makes one when there is none. A cluster rule's `order` ranks the elements made under it among same-named elements made under its sibling clusters. Since 4.3.0, `binding` reads every IRI form the component libraries use (LOINC, SNOMED CT, NCIt, a code list's fragment) and takes the code system as `system`; `link` writes the code of the concept the component links to (skos:exactMatch, then dcterms:subject, or `predicates`).",
|
|
5
|
+
"description": "How one model's components reach one target where the model alone does not settle it. Bound to one model schema version and one target version; immutable once published. No expressions or code. Since 4.1.0, rules may map a cluster to a target element (with a `within` context for a cluster used in several places), target paths are relative to the enclosing mapped cluster unless they start with '/', a final '@name' step places an attribute, and a `units` sub-rule places a quantity's unit. A '..' step goes up from the enclosing mapped cluster's element, a '.' step is no step, and a step prefixed '+' makes a new element for each value rather than sharing one by name. `also` writes the same value to further places; `on_miss: omit` leaves a code-table miss unwritten instead of failing. The `binding` transform writes the code the model binds a value to (the fragment of the IRI its enumeration value is defined by, under `prefix`): the model, not the mapping, supplies the value. A step written '=name' joins the element of that name its parent already has (one a nested cluster makes), or makes one when there is none. A cluster rule's `order` ranks the elements made under it among same-named elements made under its sibling clusters. Since 4.3.0, `binding` reads every IRI form the component libraries use (LOINC, SNOMED CT, NCIt, a code list's fragment) and takes the code system as `system`; `link` writes the code of the concept the component links to (skos:exactMatch, then dcterms:subject, or `predicates`). Since 4.4.0, `reference_model: true` reads the record's reference-model parts beyond the data cluster (the DM's subject and providers, Participations, protocol, workflow, acs, Audits and attestation, and each Party's name, reference and details); a part the schema types by a component (a Party, its details cluster, a Participation's function) is named by its identifier as any component is, a `cluster` or `within` entry may also name the reference-model element a part stands in (subject, provider, performer, committer, party-details, ...), and `element` names a reference-model element that holds a value (start, end, party-name, committed, pending, ...).",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"required": [
|
|
8
8
|
"mapping",
|
|
@@ -84,6 +84,11 @@
|
|
|
84
84
|
"type": "boolean",
|
|
85
85
|
"default": false
|
|
86
86
|
},
|
|
87
|
+
"reference_model": {
|
|
88
|
+
"description": "Read the record's reference-model parts beyond the data cluster (sdcreader 4.5.0): every value read there must then reach a rule or be reported, as data-cluster values are. Off by default; rules that name reference-model elements need it.",
|
|
89
|
+
"type": "boolean",
|
|
90
|
+
"default": false
|
|
91
|
+
},
|
|
87
92
|
"rules": {
|
|
88
93
|
"type": "array",
|
|
89
94
|
"items": {
|
|
@@ -163,6 +168,11 @@
|
|
|
163
168
|
"required": [
|
|
164
169
|
"cluster"
|
|
165
170
|
]
|
|
171
|
+
},
|
|
172
|
+
{
|
|
173
|
+
"required": [
|
|
174
|
+
"element"
|
|
175
|
+
]
|
|
166
176
|
}
|
|
167
177
|
],
|
|
168
178
|
"properties": {
|
|
@@ -173,16 +183,34 @@
|
|
|
173
183
|
"type": "string",
|
|
174
184
|
"pattern": "^Xd[A-Za-z]+$"
|
|
175
185
|
},
|
|
186
|
+
"element": {
|
|
187
|
+
"$ref": "#/$defs/rm_element",
|
|
188
|
+
"description": "A reference-model element that holds a value (4.4.0), for a value the schema types by no component of its own or wherever the element, not the component, should decide: a Participation's start or end, a Party's party-name, an Attestation's committed or pending. Needs `reference_model: true`."
|
|
189
|
+
},
|
|
176
190
|
"cluster": {
|
|
177
|
-
"
|
|
191
|
+
"anyOf": [
|
|
192
|
+
{
|
|
193
|
+
"$ref": "#/$defs/ct_id"
|
|
194
|
+
},
|
|
195
|
+
{
|
|
196
|
+
"$ref": "#/$defs/rm_part"
|
|
197
|
+
}
|
|
198
|
+
]
|
|
178
199
|
},
|
|
179
200
|
"within": {
|
|
180
201
|
"type": "array",
|
|
181
202
|
"items": {
|
|
182
|
-
"
|
|
203
|
+
"anyOf": [
|
|
204
|
+
{
|
|
205
|
+
"$ref": "#/$defs/ct_id"
|
|
206
|
+
},
|
|
207
|
+
{
|
|
208
|
+
"$ref": "#/$defs/rm_part"
|
|
209
|
+
}
|
|
210
|
+
]
|
|
183
211
|
},
|
|
184
212
|
"minItems": 1,
|
|
185
|
-
"description": "Ancestor clusters that must enclose the component or cluster, outermost first, for the rule to apply."
|
|
213
|
+
"description": "Ancestor clusters that must enclose the component or cluster, outermost first, for the rule to apply: by identifier, or (4.4.0) by the reference-model element a part stands in."
|
|
186
214
|
},
|
|
187
215
|
"to": {
|
|
188
216
|
"$ref": "#/$defs/path"
|
|
@@ -503,6 +531,40 @@
|
|
|
503
531
|
"minLength": 1,
|
|
504
532
|
"description": "Target steps separated by '/'; a leading '/' is absolute; a final step '@name' is an attribute of the element before it (or of the enclosing element when it is the only step).",
|
|
505
533
|
"pattern": "^(/?[^/@\\s]+(/[^/@\\s]+)*(/@[^/@\\s]+)?|@[^/@\\s]+)$"
|
|
534
|
+
},
|
|
535
|
+
"rm_part": {
|
|
536
|
+
"description": "A reference-model element that holds further elements (sdc4.xsd DMType, PartyType, ParticipationType, AttestationType, AuditType).",
|
|
537
|
+
"enum": [
|
|
538
|
+
"attestation",
|
|
539
|
+
"committer",
|
|
540
|
+
"location",
|
|
541
|
+
"party-details",
|
|
542
|
+
"performer",
|
|
543
|
+
"provider",
|
|
544
|
+
"subject",
|
|
545
|
+
"system-user",
|
|
546
|
+
"workflow"
|
|
547
|
+
]
|
|
548
|
+
},
|
|
549
|
+
"rm_element": {
|
|
550
|
+
"description": "A reference-model element that holds a value (sdc4.xsd DMType, PartyType, ParticipationType, AttestationType, AuditType).",
|
|
551
|
+
"enum": [
|
|
552
|
+
"acs",
|
|
553
|
+
"committed",
|
|
554
|
+
"end",
|
|
555
|
+
"function",
|
|
556
|
+
"mode",
|
|
557
|
+
"party-name",
|
|
558
|
+
"party-ref",
|
|
559
|
+
"pending",
|
|
560
|
+
"proof",
|
|
561
|
+
"protocol",
|
|
562
|
+
"reason",
|
|
563
|
+
"start",
|
|
564
|
+
"system-id",
|
|
565
|
+
"timestamp",
|
|
566
|
+
"view"
|
|
567
|
+
]
|
|
506
568
|
}
|
|
507
569
|
}
|
|
508
570
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: sdc-mapper
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.4.0
|
|
4
4
|
Summary: The shared core of the Semantic Data Charter's Governed Data Record mappers: validate, resolve, map, and report every value; MCP server included.
|
|
5
5
|
Author: Axius SDC, Inc.
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -11,7 +11,7 @@ Requires-Python: >=3.12
|
|
|
11
11
|
Description-Content-Type: text/markdown
|
|
12
12
|
License-File: LICENSE
|
|
13
13
|
License-File: NOTICE
|
|
14
|
-
Requires-Dist: sdcreader<5,>=4.
|
|
14
|
+
Requires-Dist: sdcreader<5,>=4.5
|
|
15
15
|
Requires-Dist: sdcvalidator<5,>=4.6
|
|
16
16
|
Requires-Dist: xmlschema>=3.0
|
|
17
17
|
Requires-Dist: pyyaml>=6.0
|
|
@@ -33,7 +33,7 @@ target could say it too. Every call is appended to a hash-chained log that holds
|
|
|
33
33
|
Each target format is its own package (`sdc-gdr2ubl`, `sdc-gdr2edifact`, `sdc-gdr2omop`, ...) registered under the
|
|
34
34
|
entry-point group `sdc_mapper.targets`. Outbound only. Apache 2.0.
|
|
35
35
|
|
|
36
|
-
**Status:** 4.
|
|
36
|
+
**Status:** 4.4.0. Five target mappers are released: `sdc-gdr2ubl` (OASIS UBL 2.3), `sdc-gdr2edifact` (UN/EDIFACT
|
|
37
37
|
D.24A), `sdc-gdr2omop` (OMOP CDM 5.4), `sdc-gdr2fhir` (HL7 FHIR R4) and `sdc-gdr2hl7v2` (HL7 v2.5.1).
|
|
38
38
|
|
|
39
39
|
## Use
|
|
@@ -50,6 +50,8 @@ sdc-mapper [--log-dir DIR] [--host URL] # MCP stdio server (also sdc-
|
|
|
50
50
|
A model is a package directory (`dm-<ct>.jsonld`, `dm-<ct>.xsd`) or a published model's `--ct-id`, fetched from the
|
|
51
51
|
SDCStudio host; with neither, the record's own root names it. Exit status: 0 mapped, 1 refused, 2 error.
|
|
52
52
|
|
|
53
|
+
Also listed on [mcprush](https://mcprush.com/semanticdatacharter/sdc-mapper-mcp).
|
|
54
|
+
|
|
53
55
|
## The three outcomes
|
|
54
56
|
|
|
55
57
|
- **valid:** mapped.
|
|
@@ -95,6 +97,28 @@ reports it as a lookup (`LOOKUP_TRANSFORMS`). Steps: `..` up, `.` none, `+name`
|
|
|
95
97
|
the element of that name the parent already has. `within:` restricts a rule to a context. A value no rule reaches is
|
|
96
98
|
reported, never dropped. `place(record, mapping)` turns a record and its mapping into placements a mapper writes from.
|
|
97
99
|
|
|
100
|
+
**The reference-model parts (4.4.0).** `reference_model: true` reads a record's subject, providers, Participations,
|
|
101
|
+
protocol, workflow, acs, Audits and attestation as well as its data cluster. A Party, its details cluster and their
|
|
102
|
+
components are named by identifier, as anywhere; `cluster` and `within` may also name the reference-model element a part
|
|
103
|
+
stands in, and `element` a reference-model element that holds a value:
|
|
104
|
+
|
|
105
|
+
```yaml
|
|
106
|
+
reference_model: true
|
|
107
|
+
rules:
|
|
108
|
+
- cluster: <Author> # the record's provider Party
|
|
109
|
+
to: /entry#author/resource
|
|
110
|
+
- component: <Given Name (Person)>
|
|
111
|
+
within: [<Author>] # the Author's details, not the Patient's
|
|
112
|
+
to: name/given
|
|
113
|
+
transform: copy
|
|
114
|
+
- cluster: subject # whatever Party the record's subject is
|
|
115
|
+
to: /entry#patient/resource
|
|
116
|
+
- element: start # a Participation's start (xsd:dateTime, read as a temporal value)
|
|
117
|
+
within: [<Attester Participation>]
|
|
118
|
+
to: time
|
|
119
|
+
transform: copy
|
|
120
|
+
```
|
|
121
|
+
|
|
98
122
|
## Codes the model names
|
|
99
123
|
|
|
100
124
|
`sdc_mapper.codes` reads the IRIs the component libraries use for a concept as a code system and a code: LOINC codes
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
"""The reference-model parts beyond the data cluster (4.4.0): `reference_model: true` reads them, rules reach a Party's
|
|
2
|
+
details by the same identifiers as data-cluster components, `cluster`/`within` may name the reference-model element a
|
|
3
|
+
part stands in, and `element` names one that holds a value.
|
|
4
|
+
|
|
5
|
+
Fixture: SDCHealth's Laboratory Report (production, public) and two synthetic records of it
|
|
6
|
+
(samples/sdchealth-lab-report); labrep05 carries an Asked and Refused Date of Birth in the subject's details.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
import pytest
|
|
14
|
+
import yaml
|
|
15
|
+
from lxml import etree
|
|
16
|
+
|
|
17
|
+
from refmapper import CSVMapper
|
|
18
|
+
from sdc_mapper import Engine, Gate, MappingError, VALID, VALID_WITH_EV, load_mapping, place, resolve
|
|
19
|
+
from sdc_mapper.mapping import RM_NAMES, ancestor_tokens
|
|
20
|
+
from sdcreader import load_package, read_model
|
|
21
|
+
from sdcreader.model import RM_ELEMENTS, RM_PARTS, RM_SLOTS
|
|
22
|
+
from sdcreader.record import read_record
|
|
23
|
+
|
|
24
|
+
ROOT = Path(__file__).resolve().parents[1]
|
|
25
|
+
SAMPLE = ROOT / "samples" / "sdchealth-lab-report"
|
|
26
|
+
CT = "zptekdommw56yiz9lqjy5dga"
|
|
27
|
+
PKG = load_package(SAMPLE, CT)
|
|
28
|
+
MODEL = read_model(PKG)
|
|
29
|
+
RECORD = (SAMPLE / "records" / "labrep00synthxxxxxxxxxxx.xml").read_bytes()
|
|
30
|
+
RECORD_EV = (SAMPLE / "records" / "labrep05synthxxxxxxxxxxx.xml").read_bytes()
|
|
31
|
+
SDC4_XSD = ROOT / "src" / "sdc_mapper" / "schemas" / "sdc4.xsd"
|
|
32
|
+
XSD = "{http://www.w3.org/2001/XMLSchema}"
|
|
33
|
+
|
|
34
|
+
PATIENT, AUTHOR = "uficdtk6vpsgvpeyr1sevj9j", "qau8mx32a2d0v54jrc2q7y9y"
|
|
35
|
+
PATIENT_DETAILS, PROFESSIONAL = "k2ph54lwfdtlrm7p5gw4s3tt", "geuvvqy9qol4t10s231a4ezo"
|
|
36
|
+
HUMAN_NAME, GIVEN_NAME, SURNAME = "g50zuf7amwobbgifx7o52i5l", "l9l169co9r23e6fftpvdz4e3", "jc1lfk3ovt6l8frhxvx8b669"
|
|
37
|
+
ATTESTER_PARTICIPATION, ATTESTER_FUNCTION = "e7jes8an7n8t58qyabk1nnm2", "z0gm7qs3bvdt2s1tie2gcrue"
|
|
38
|
+
DATE_OF_BIRTH = "js564tazefb6udqlh12rj04l"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def mapping(tmp_path, rules, **extra):
|
|
42
|
+
doc = {"mapping": {"id": "t", "version": 1}, "model": {"ct_id": CT, "schema_sha256": PKG.sha256},
|
|
43
|
+
"target": {"name": CSVMapper.target, "version": CSVMapper.target_version}, "rules": rules, **extra}
|
|
44
|
+
p = tmp_path / "m.yaml"
|
|
45
|
+
p.write_text(yaml.safe_dump(doc, sort_keys=False))
|
|
46
|
+
return load_mapping(p)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def resolved(xml: bytes = RECORD, rm: bool = True):
|
|
50
|
+
g = Gate().check(xml, PKG, MODEL, reference_model=rm)
|
|
51
|
+
assert g.outcome in (VALID, VALID_WITH_EV), g.errors
|
|
52
|
+
return resolve(read_record(g.xml, MODEL, reference_model=rm), MODEL, PKG, g)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def names(steps):
|
|
56
|
+
return "/".join(s for s, _ in steps)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
RULES = [
|
|
60
|
+
{"cluster": AUTHOR, "to": "/author"},
|
|
61
|
+
{"cluster": "subject", "to": "/patient"}, # by the element the Party stands in
|
|
62
|
+
{"component": GIVEN_NAME, "within": [AUTHOR], "to": "name/given", "transform": "copy"},
|
|
63
|
+
{"component": GIVEN_NAME, "within": ["subject"], "to": "name/given", "transform": "copy"},
|
|
64
|
+
{"component": SURNAME, "within": [AUTHOR, HUMAN_NAME], "to": "name/family", "transform": "copy"},
|
|
65
|
+
{"component": DATE_OF_BIRTH, "within": ["subject"], "to": "birthDate", "transform": "copy"},
|
|
66
|
+
{"cluster": ATTESTER_PARTICIPATION, "to": "/attester"},
|
|
67
|
+
{"component": ATTESTER_FUNCTION, "to": "mode", "transform": "copy"},
|
|
68
|
+
{"element": "start", "within": [ATTESTER_PARTICIPATION], "to": "time", "transform": "format", "format": "%Y-%m-%d"},
|
|
69
|
+
{"element": "pending", "to": "/attestation/pending", "transform": "copy"},
|
|
70
|
+
]
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
# ------------------------------------------------------------------ the mapping file
|
|
74
|
+
|
|
75
|
+
def test_rules_naming_reference_model_elements_need_the_flag(tmp_path):
|
|
76
|
+
with pytest.raises(MappingError, match="reference_model"):
|
|
77
|
+
mapping(tmp_path, [{"element": "start", "to": "time", "transform": "copy"}])
|
|
78
|
+
with pytest.raises(MappingError, match="reference_model"):
|
|
79
|
+
mapping(tmp_path, [{"cluster": "subject", "to": "/patient"}])
|
|
80
|
+
m = mapping(tmp_path, RULES, reference_model=True)
|
|
81
|
+
assert m.reference_model and set(m.names_reference_model) == {"subject", "start", "pending"}
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def test_a_mapping_without_the_flag_reads_as_before(tmp_path):
|
|
85
|
+
m = mapping(tmp_path, [{"cluster": AUTHOR, "to": "/author"}])
|
|
86
|
+
assert not m.reference_model and not m.names_reference_model
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def test_the_schema_refuses_an_unknown_element_name(tmp_path):
|
|
90
|
+
with pytest.raises(MappingError, match="does not validate"):
|
|
91
|
+
mapping(tmp_path, [{"element": "stat", "to": "time", "transform": "copy"}], reference_model=True)
|
|
92
|
+
with pytest.raises(MappingError, match="does not validate"):
|
|
93
|
+
mapping(tmp_path, [{"element": "start", "component": ATTESTER_FUNCTION, "to": "t", "transform": "copy"}],
|
|
94
|
+
reference_model=True)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def test_the_schema_names_are_sdcreaders():
|
|
98
|
+
schema = json.loads((ROOT / "src" / "sdc_mapper" / "schemas" / "mapping.schema.json").read_text())
|
|
99
|
+
assert set(schema["$defs"]["rm_part"]["enum"]) == RM_PARTS
|
|
100
|
+
assert set(schema["$defs"]["rm_element"]["enum"]) == RM_ELEMENTS
|
|
101
|
+
assert RM_NAMES == RM_PARTS | RM_ELEMENTS
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def test_sdcreaders_slot_table_is_the_reference_models():
|
|
105
|
+
"""Every named element sdc4.xsd gives DMType, PartyType, ParticipationType, AttestationType and AuditType beyond
|
|
106
|
+
the record attributes, the label and the data cluster is in sdcreader's table, with its type."""
|
|
107
|
+
tree = etree.parse(str(SDC4_XSD)).getroot()
|
|
108
|
+
types = {"DMType": "DM", "PartyType": "Party", "ParticipationType": "Participation", "AttestationType": "Attestation",
|
|
109
|
+
"AuditType": "Audit"}
|
|
110
|
+
kinds = {"sdc4:PartyType": "Party", "sdc4:ClusterType": "Cluster", "sdc4:AttestationType": "Attestation",
|
|
111
|
+
"sdc4:XdStringType": "XdString", "sdc4:XdLinkType": "XdLink", "sdc4:XdFileType": "XdFile",
|
|
112
|
+
"xsd:string": "string", "xsd:dateTime": "dateTime", "xsd:boolean": "boolean"}
|
|
113
|
+
skip = {"label", "dm-label", "dm-language", "dm-encoding", "creation_timestamp", "instance_id", "instance_version",
|
|
114
|
+
"source_instance_id", "source_version_id", "current-state"}
|
|
115
|
+
for name, rm in types.items():
|
|
116
|
+
ct = next(c for c in tree.iter(f"{XSD}complexType") if c.get("name") == name)
|
|
117
|
+
declared = {e.get("name"): kinds[e.get("type")] for e in ct.iter(f"{XSD}element")
|
|
118
|
+
if e.get("name") and e.get("name") not in skip}
|
|
119
|
+
assert declared == RM_SLOTS[rm], name
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
# ------------------------------------------------------------------ placement
|
|
123
|
+
|
|
124
|
+
def test_a_partys_details_land_by_the_party_that_holds_them(tmp_path):
|
|
125
|
+
ps, clusters = place(resolved(), mapping(tmp_path, RULES, reference_model=True))
|
|
126
|
+
given = {names(p.steps): p.text for p in ps if p.value.ct_id == GIVEN_NAME and p.rule}
|
|
127
|
+
assert given == {"author/name/given": "Elena", "patient/name/given": "Ana"}
|
|
128
|
+
family = [(names(p.steps), p.text) for p in ps if p.value.ct_id == SURNAME and p.rule]
|
|
129
|
+
assert family == [("author/name/family", "Moreau")]
|
|
130
|
+
# the Attester's and the Legal Authenticator's names share the components but no rule reaches them
|
|
131
|
+
assert any(p.unmapped for p in ps if p.value.ct_id == GIVEN_NAME)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def test_a_participations_function_and_start(tmp_path):
|
|
135
|
+
ps, _ = place(resolved(), mapping(tmp_path, RULES, reference_model=True))
|
|
136
|
+
function = next(p for p in ps if p.value.ct_id == ATTESTER_FUNCTION)
|
|
137
|
+
assert names(function.steps) == "attester/mode" and function.text == "attester"
|
|
138
|
+
start = next(p for p in ps if p.value.role == "start" and p.value.path[0].ct_id == ATTESTER_PARTICIPATION)
|
|
139
|
+
assert names(start.steps) == "attester/time" and start.text == "2026-10-01"
|
|
140
|
+
others = [p for p in ps if p.value.role == "start" and p.value.path[0].ct_id != ATTESTER_PARTICIPATION]
|
|
141
|
+
assert others and all(p.unmapped for p in others)
|
|
142
|
+
pending = next(p for p in ps if p.value.role == "pending")
|
|
143
|
+
assert names(pending.steps) == "attestation/pending" and pending.text == "false"
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def test_an_exceptional_value_in_a_partys_details_is_placed_and_never_written(tmp_path):
|
|
147
|
+
ps, _ = place(resolved(RECORD_EV), mapping(tmp_path, RULES, reference_model=True))
|
|
148
|
+
dob = next(p for p in ps if p.value.ct_id == DATE_OF_BIRTH and p.value.roles[0] == "subject")
|
|
149
|
+
assert dob.value.exceptional.code == "ASKR" and dob.value.exceptional.origin == "source"
|
|
150
|
+
assert names(dob.steps) == "patient/birthDate" and dob.text is None
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def test_the_ancestor_tokens_name_a_step_by_its_element_and_its_identifier():
|
|
154
|
+
v = next(v for v in resolved().values if v.ct_id == GIVEN_NAME and v.roles[:1] == ("subject",))
|
|
155
|
+
assert ancestor_tokens(v.path, v.roles) == [["subject", PATIENT], ["party-details", PATIENT_DETAILS], [HUMAN_NAME]]
|
|
156
|
+
plain = next(v for v in resolved(rm=False).values)
|
|
157
|
+
assert all(len(t) == 1 for t in ancestor_tokens(plain.path, plain.roles))
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def test_a_component_rule_wins_over_an_element_rule(tmp_path):
|
|
161
|
+
m = mapping(tmp_path, [{"element": "function", "to": "f", "transform": "copy"},
|
|
162
|
+
{"component": ATTESTER_FUNCTION, "to": "g", "transform": "copy"}], reference_model=True)
|
|
163
|
+
ps, _ = place(resolved(), m)
|
|
164
|
+
assert {names(p.steps) for p in ps if p.value.role == "function"} == {"f", "g"}
|
|
165
|
+
assert names(next(p for p in ps if p.value.ct_id == ATTESTER_FUNCTION).steps) == "g"
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
# ------------------------------------------------------------------ end to end
|
|
169
|
+
|
|
170
|
+
def test_the_engine_reads_the_parts_only_when_the_mapping_asks(tmp_path):
|
|
171
|
+
engine = Engine(schema_dir=tmp_path / "schemas")
|
|
172
|
+
plain = engine.map_record(RECORD, CSVMapper(), mapping(tmp_path, [{"cluster": AUTHOR, "to": "/author"}]),
|
|
173
|
+
directory=str(SAMPLE))
|
|
174
|
+
assert plain.outcome == VALID, plain.errors
|
|
175
|
+
asked = engine.map_record(RECORD, CSVMapper(), mapping(tmp_path, RULES, reference_model=True), directory=str(SAMPLE))
|
|
176
|
+
assert asked.outcome == VALID, asked.errors
|
|
177
|
+
assert len(plain.report.values) == 22 and len(asked.report.values) == 126
|
|
178
|
+
rows = {(tuple(r["path"]), r["label"]) for r in asked.report.values}
|
|
179
|
+
assert (("Author", "Health Professional", "Human Name"), "Given Name (Person)") in rows
|
|
180
|
+
assert (("Attester Participation",), "start") in rows
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def test_a_recovery_inside_a_participations_function_lands_on_its_value(tmp_path):
|
|
184
|
+
"""The Attester's function is fixed to 'attester' by its pattern: the gate recovers a wrong one with an Exceptional
|
|
185
|
+
Value, and numbers it as the reader does when the mapping reads the parts. Without them, as in 4.3, a recovery
|
|
186
|
+
outside the data cluster is not inside a value the mapping can see, and the record is refused."""
|
|
187
|
+
bad = RECORD.replace(b"<xdstring-value>attester</xdstring-value>", b"<xdstring-value>attestor</xdstring-value>")
|
|
188
|
+
assert bad != RECORD
|
|
189
|
+
g = Gate().check(bad, PKG, MODEL, reference_model=True)
|
|
190
|
+
assert g.outcome == VALID_WITH_EV, g.errors
|
|
191
|
+
(rec,) = g.recoveries
|
|
192
|
+
r = resolve(read_record(g.xml, MODEL, reference_model=True), MODEL, PKG, g)
|
|
193
|
+
v = r.values[rec.position]
|
|
194
|
+
assert rec.ct_id == ATTESTER_FUNCTION and v.ct_id == ATTESTER_FUNCTION and v.role == "function"
|
|
195
|
+
assert v.exceptional.origin == "recovery" and v.exceptional.constraint and v.value is None
|
|
196
|
+
assert Gate().check(bad, PKG, MODEL).outcome == "refused"
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def test_check_mapping_reports_the_parts_a_mapping_reads(tmp_path):
|
|
200
|
+
from sdc_mapper import mcp_server as srv
|
|
201
|
+
mapping(tmp_path, RULES + [{"component": "zzzzzzzzzzzzzzzzzzzzzzzz", "to": "x", "transform": "copy"}], reference_model=True)
|
|
202
|
+
out = srv._handle_check_mapping({"mapping": str(tmp_path / "m.yaml"), "directory": str(SAMPLE)})
|
|
203
|
+
assert out["ok"] and out["reference_model"] is True
|
|
204
|
+
assert set(out["reference_model_names"]) == {"subject", "start", "pending"}
|
|
205
|
+
assert out["unknown_identifiers"] == ["zzzzzzzzzzzzzzzzzzzzzzzz"]
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|