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.
Files changed (33) hide show
  1. {sdc_mapper-4.3.2/src/sdc_mapper.egg-info → sdc_mapper-4.4.0}/PKG-INFO +27 -3
  2. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/README.md +25 -1
  3. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/pyproject.toml +2 -2
  4. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/__init__.py +1 -1
  5. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/engine.py +3 -2
  6. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/gate.py +20 -31
  7. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/mapping.py +54 -14
  8. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/mcp_server.py +10 -3
  9. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/placement.py +5 -3
  10. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/resolve.py +7 -1
  11. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/schemas/mapping.schema.json +66 -4
  12. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0/src/sdc_mapper.egg-info}/PKG-INFO +27 -3
  13. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/SOURCES.txt +1 -0
  14. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/requires.txt +1 -1
  15. sdc_mapper-4.4.0/tests/test_reference_model.py +205 -0
  16. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/LICENSE +0 -0
  17. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/NOTICE +0 -0
  18. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/setup.cfg +0 -0
  19. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/cli.py +0 -0
  20. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/codes.py +0 -0
  21. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/contract.py +0 -0
  22. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/log.py +0 -0
  23. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/report.py +0 -0
  24. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/schemas/log-entry.schema.json +0 -0
  25. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/schemas/sdc4.xsd +0 -0
  26. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper/service.py +0 -0
  27. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/dependency_links.txt +0 -0
  28. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/entry_points.txt +0 -0
  29. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/src/sdc_mapper.egg-info/top_level.txt +0 -0
  30. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/tests/test_codes.py +0 -0
  31. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/tests/test_core.py +0 -0
  32. {sdc_mapper-4.3.2 → sdc_mapper-4.4.0}/tests/test_placement.py +0 -0
  33. {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.2
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.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.3.2. Five target mappers are released: `sdc-gdr2ubl` (OASIS UBL 2.3), `sdc-gdr2edifact` (UN/EDIFACT
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.3.2. Five target mappers are released: `sdc-gdr2ubl` (OASIS UBL 2.3), `sdc-gdr2edifact` (UN/EDIFACT
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.3.2"
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.4,<5", # the package, the model and the record reader (cluster instances: 4.4.0)
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.3.2"
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
- gate = self.gate.check(xml, pkg, model)
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 LEAF_TYPES, Model, ModelPackage
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
- positions = _value_positions(root, model)
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), model)
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
- recoveries.append(Recovery(position=positions[id(comp)], ct_id=comp.tag.split("ms-", 1)[1], code=r.code,
112
- constraint=r.reason))
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, model: Model):
147
- """The leaf component element (`sdc4:ms-<ct_id>` of a value type) that holds `el`, or None."""
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.tag.startswith(f"{{{SDC4_NS}}}ms-"):
151
- comp = model.components.get(el.tag.split("ms-", 1)[1])
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 _value_positions(root, model: Model) -> dict[int, int]:
159
- """Each leaf component element's position among the record's values, in document order: the numbering
160
- sdcreader's `read_record` gives the same record."""
161
- out, n = {}, 0
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 over its type's default, and among several, the one
75
- with the longest `within` that applies. `ancestors` are the enclosing clusters' identifiers, root first."""
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.sdc_type == sdc_type):
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
- found = [r for r in self.rules if r.cluster == ct_id and r.applies_within(ancestors)]
85
- return max(found, key=lambda r: len(r.within)) if found else None
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
- return Mapping(id=doc["mapping"]["id"], version=str(doc["mapping"]["version"]),
118
- sha256=hashlib.sha256(data).hexdigest(), model_ct_id=doc["model"]["ct_id"],
119
- model_schema_sha256=doc["model"]["schema_sha256"], target_name=doc["target"]["name"],
120
- target_version=doc["target"]["version"], rules=rules,
121
- exceptional_values=doc.get("exceptional_values", {}), carry_rejected=doc.get("carry_rejected", False),
122
- profile_of=doc.get("profile_of"), raw=doc)
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 current schema.",
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, ids[:i])
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, ids)
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
- "$ref": "#/$defs/ct_id"
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
- "$ref": "#/$defs/ct_id"
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.2
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.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.3.2. Five target mappers are released: `sdc-gdr2ubl` (OASIS UBL 2.3), `sdc-gdr2edifact` (UN/EDIFACT
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
@@ -27,4 +27,5 @@ src/sdc_mapper/schemas/sdc4.xsd
27
27
  tests/test_codes.py
28
28
  tests/test_core.py
29
29
  tests/test_placement.py
30
+ tests/test_reference_model.py
30
31
  tests/test_service.py
@@ -1,4 +1,4 @@
1
- sdcreader<5,>=4.4
1
+ sdcreader<5,>=4.5
2
2
  sdcvalidator<5,>=4.6
3
3
  xmlschema>=3.0
4
4
  pyyaml>=6.0
@@ -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