sdc-mapper

sdc-mapper

Semantic Data Charter の Governed Data Record マッパーの共有コアです。レコードを検証し、レコードが指定するモデルを読み込み、モデルの定義に照らして各値を解決し、その結果をターゲットマッパーに渡して、各値について、どのようにターゲットに到達したか、またはターゲットでは保持できないことを報告します。レコードに値が欠落している、または使用できない 理由（ISO 21090 の null flavor に基づく Exceptional Value）が記されている場合は、ターゲットでもその理由を表現できるかどうかもレポートに示します。呼び出しはすべて、値を含まないハッシュチェーンログに追記されます。

各ターゲット形式は独立したパッケージ（sdc-gdr2ubl、sdc-gdr2edifact、sdc-gdr2omop、...）であり、エントリーポイントグループ sdc_mapper.targets に登録されます。アウトバウンド専用です。Apache 2.0。

ステータス： 4.3.1。5 つのターゲットマッパーをリリースしています。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 はエラーです。

3 つの結果

• valid： マッピング済みです。
• valid with Exceptional Values： 制約に違反した値が Exceptional Value（Invalid。制約は保持されます）で表され、レコードの残りはマッピングされます。ソースに記録された Exceptional Value（拒否、マスキングされたフィールド）は、記録されたとおりに保持されます。
• refused： 構造の破損、モデルの不一致、または Exceptional Value でカバーされないエラーです。何も書き込まれず、理由が返され、ログに記録されます。

マッピングファイル

YAML 形式です。schemas/mapping.schema.json に対して検証され、1 つのモデルスキーマバージョンと 1 つのターゲットバージョンに紐付けられます。

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）として報告します。ステップ：.. は 1 つ上、. は変更なし、+name は値自身の要素、=name は親がすでに持つ同名の要素です。within: はルールの適用範囲をコンテキスト内に限定します。どのルールにも該当しない値は、決して破棄されず、報告されます。place(record, mapping) は、レコードとそのマッピングを、マッパーが書き込みに使う配置情報に変換します。

モデルが指定するコード

sdc_mapper.codes は、コンポーネントライブラリが概念のコードシステムとコードとして使用する IRIs を読み込みます。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 を値ごとに新しい行として扱い、レコード自身の行（その人、そのドキュメント）を独自の名前で保持できます。sdc-gdr2omop は RECORD テーブルを使ってこれを実現しています。

マッパーの作成

マッパーには、name、target、target_version、package、version、Exceptional Value テーブル（ev_table：ISO 21090 の各コードに対応する EVRule。保持、劣化、引き継ぎ、または喪失を指定）と、map(record, mapping) -> MapResult が必要です。渡された値ごとに 1 つの ValueOutcome を返し、拒否された値を値として書き込むことはありません。また、自身を登録します。

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

テスト

python -m pytest tests -q（オフライン）。フィクスチャは HalvorsenDemo の Credit Note レコードと、そのモデルのパッケージです。tests/refmapper.py の参照マッパーは、契約のテストにのみ使用するフラットな CSV です。

ライセンス

Apache 2.0。付属の SDC4 参照モデルスキーマとフィクスチャについては、NOTICE を参照してください。