sdc-mapper

sdc-mapper

Semantic Data Charter 的 Governed Data Record 映射器的共享核心。它会验证记录，读取记录所指明的模型，根据模型对每个值的定义解析该值，将结果交给目标映射器，并报告每个值：它如何到达目标，或者目标无法容纳它。如果记录说明了值缺失或不可用的原因（即 ISO 21090 空值类型中的 Exceptional Value），报告还会说明目标是否也能表达该原因。每次调用都会追加到哈希链式日志中，日志不包含任何值。

每种目标格式各自作为独立软件包（sdc-gdr2ubl、sdc-gdr2edifact、sdc-gdr2omop 等）发布，并注册在入口点组 sdc_mapper.targets 下。仅支持出站转换。Apache 2.0。

状态： 4.3.1。已发布五种目标映射器：sdc-gdr2ubl（OASIS UBL 2.3）、sdc-gdr2edifact（UN/EDIFACT D.24A）、sdc-gdr2omop（OMOP CDM 5.4）、sdc-gdr2fhir（HL7 FHIR R4）和 sdc-gdr2hl7v2（HL7 v2.5.1）。

使用

sdc-map targets
sdc-map map TARGET record.xml --package DIR [--mapping m.yaml] [-o out/]
sdc-map fidelity record.xml --package DIR          # every installed target, side by side, per Exceptional Value
sdc-map check-mapping m.yaml --package DIR
sdc-map log summary --days 7 | sdc-map log verify
sdc-mapper [--log-dir DIR] [--host URL]            # MCP stdio server (also sdc-mapper-mcp): the primary way agents use the mappers

模型可以是软件包目录（dm-<ct>.jsonld、dm-<ct>.xsd），也可以是已发布模型的 --ct-id，并从 SDCStudio 主机获取；如果两者都未提供，则使用记录自身的根节点命名模型。退出状态：0 表示已映射，1 表示已拒绝，2 表示出错。

三种结果

• 有效： 已映射。
• 含 Exceptional Value 的有效记录： 某个未通过约束的值由 Exceptional Value 覆盖（Invalid，同时保留该约束），记录的其余部分已映射。源数据中写入的 Exceptional Value（例如拒绝或已屏蔽的字段）按原样保留。
• 已拒绝： 结构损坏、模型错误，或出现未被 Exceptional Value 覆盖的错误。不写入任何内容；返回并记录拒绝原因。

映射文件

YAML，根据 schemas/mapping.schema.json 验证，并绑定到一个模型架构版本和一个目标版本。

mapping: {id: credit-note-to-ubl, version: 1}
model: {ct_id: jkuyr38hydqaiwlq5vhp2rjr, schema_sha256: "…"}
target: {name: OASIS UBL, version: "2.3 CreditNote"}
rules:
  - cluster: <Accounting Supplier Party>        # a cluster to a target element
    to: cac:AccountingSupplierParty
  - cluster: <Party>                            # relative to the enclosing mapped cluster
    to: cac:Party
  - component: <Party Identification Value>
    to: cac:PartyIdentification/cbc:ID
    transform: copy
  - component: <Party Identification Scheme>
    to: cac:PartyIdentification/cbc:ID/@schemeName   # an attribute of the same element
    transform: copy
  - component: <Line Extension Amount>
    to: cbc:LineExtensionAmount
    transform: copy
    units: {to: "@currencyID", transform: copy}
  - cluster: <Party Contact>
    to: "-"
    transform: omit
    reason: the target profile carries no contact

转换方式：copy、code（查找表）、format、constant、binding（模型用于定义枚举值的代码）、link（组件所链接概念的代码）、omit；簇使用 group 或 omit。binding 和 link 接受一个 system（http://loinc.org、http://snomed.info/sct、代码列表的 IRI）；其文本来自模型，因此映射器会将其报告为查找（LOOKUP_TRANSFORMS）。路径步骤：.. 表示向上一级，. 表示不移动，+name 表示值自身的一个元素，=name 表示父级已有的同名元素。within: 用于将规则限制在某个上下文内。未被任何规则覆盖的值会被报告，而不会被丢弃。place(record, mapping) 会将记录及其映射转换为映射器写入所需的 placements。

模型命名的代码

sdc_mapper.codes 会将组件库为某个概念使用的 IRI 解析为代码系统和代码：LOINC 代码及答案、SNOMED CT、NCI Thesaurus，以及 IRI 以 #code 结尾的任何代码列表（包括 UBL 和 HL7 的代码列表）。代码系统以 FHIR 使用的 IRI 命名；映射器会将其转换为目标格式所使用的系统名称（例如 OMOP 的 vocabulary_id、HL7 v2 的编码系统）。bound_code(value) 返回枚举值的定义代码，linked_code(value) 返回其组件所链接概念的代码（先查 skos:exactMatch，再查 dcterms:subject），而 model_codes(value) 返回模型为其命名的所有代码：目标代码若在其中，即表示它来自模型。

写入目标

place() 会为每个值提供目标路径。以 =name 书写的路径步骤会加入由其他值创建的元素，因此写入器会暂缓这些写入，直到其他值全部写入，再按从最浅到最深的顺序写入：根据 join_depth(steps) 对其排序。面向行的目标（例如 OMOP 的一组表）可以将每个步骤视为一个表或列，将 +TABLE 视为每个值新建一行，并将记录自身的行（例如其 person 或 document）归入独立命名项；sdc-gdr2omop 便是如此处理的，使用了 RECORD 表。

编写映射器

映射器包含 name、target、target_version、package、version、一个异常值表（ev_table：每个 ISO 21090 代码对应一条 EVRule，状态为保留、降级、携带或丢失）以及 map(record, mapping) -> MapResult。它会为提供给它的每个值返回一个 ValueOutcome，绝不会将被拒绝的值写入为值，并会注册自身：

[project.entry-points."sdc_mapper.targets"]
ubl = "sdc_gdr2ubl:UBLMapper"

测试

python -m pytest tests -q（离线运行）。测试夹具是 HalvorsenDemo 信用票据记录及其模型包；tests/refmapper.py 中的参考映射器是一个扁平 CSV，仅用于测试合约。

许可证

Apache 2.0。有关随附的 SDC4 参考模型架构和测试夹具，请参阅 NOTICE。