sdccdif

sdc_cdif

CDIF で記述された、1 つの Semantic Data Charter モデルです。

sdccdif は公開済みの SDC モデルのパッケージを読み込み、それに準拠する Governed Data Records のコレクションを記述する CDIF JSON-LD を出力します。データセットの Core と Discovery、レコードの各リーフに対する Data Description、列挙された各リーフに対する Codelist、および参照モデルにある 16 個の例外値をまとめた 1 つのセンチネル値ドメインが含まれます。出力は、validation リポジトリの固定コミットにある CDIF 独自のフレーム、JSON Schemas、SHACL、および適合性バリデーターで検証されます。

1. これは何か、どこから来たのか

サンプルドキュメント samples/nhanes-participant/cdif-dm-xy8upneajsb8vdcmnve01g6g.jsonld は、公開済みモデルの 1 つである NHANES Participant（dm-xy8upneajsb8vdcmnve01g6g）のレコードを記述しています。このモデルは、FAIR Data Demo の一部であり、米国国立健康・栄養調査（CDC）の人口統計、検査、臨床検査の記録です。モデルは公開されています。

• カタログレコード：https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/xy8upneajsb8vdcmnve01g6g/
• レコードが準拠するスキーマ：https://sdcstudio.axius-sdc.com/dmlib/dm-xy8upneajsb8vdcmnve01g6g.xsd
• Semantic Data Charter：https://semanticdatacharter.com

ライターは、パッケージ（モデルの JSON-LD とスキーマ）、公開カタログレコード、および公開済みのスキーマバージョンを読み込みます。アカウントは不要です。パッケージが一度もビルドされていないモデルは受け付けません。スキーマと JSON-LD が記述対象の根拠であり、それらに含まれないものは何も出力されません。

pip install -e ".[fetch]"
sdccdif write --package samples/nhanes-participant --out cdif.jsonld
sdccdif write --ct-id xy8upneajsb8vdcmnve01g6g --save-package pkg/ --out cdif.jsonld   # any published model, from the catalog

NHANES Participant モデルについて、このドキュメントに含まれる内容は次のとおりです。

schema:Dataset	モデルに準拠するレコードのコレクション。名前、説明、識別子、URL、日付、言語、モデルの権利情報に基づくライセンス、作成者、連絡先を含む発行者、キーワードを含みます。また、モデラーがモデルの Dublin Core に記載した場合は、発行者の名前、主題キーワード、寄稿者、対象範囲（名前付きの Place としての schema:spatialCoverage）も含みます
schema:publishingPrinciples	永続性に関するページ。公開済みのモデルは不変であり、変更は、改訂元のモデルを示す新しいモデルとして公開されます
dcterms:conformsTo	公開 URL に ?sha256= を付けたスキーマと、バイト列の spdx:Checksum
schema:variableMeasured	153 個の cdi:InstanceVariable。レコードの各リーフについてドキュメント順に 1 つずつあり、パス、ライブラリのスロットを示す schema:propertyID、cdif:uses としての skos:exactMatch の概念、XSD データ型、単位、範囲、実質的な値ドメイン、共有のセンチネルドメインを含みます
cdif:role	回答者の連番が UnitIdentifier です。ガバナンスに関するリーフ（監査イベント、PROV アクティビティ、エージェント）は、それを修飾する Attribute です。それ以外はすべて Measure です
cdif:hasPrimaryKey	単位識別子
67 個の skos:ConceptScheme	列挙されたコンポーネントごとに 1 つずつあります。各値は定義と、定義元のコードとともに skos:notation として記載されます。3 回使われるコンポーネントも、1 つのコードリストを 3 回参照します
1 個の cdif:SentinelValueDomain	SDC4 の例外値（NI、MSK、INV、DER、UNC、OTH、NINF、PINF、UNK、ASKR、NASK、QS、TRC、ASKU、NAV、NA）を skos:ConceptScheme としてまとめたもので、すべての変数から参照されます
dcat:CatalogRecord	cdif/core/1.1、cdif/discovery/1.1、cdif/data_description/1.1 を宣言します

2. 検証方法

テストでは、data/からCDIFのバリデーターを実行します。アーティファクトは固定したコミット（validation 129085c、metadataBuildingBlocks 61f24aa）でコピーされます（コピー前にbuild/snapshot_cdif.pyがコミットを検証します）。

pip install -e ".[dev]"
python -m pytest tests -q

または、サンプルに対して適合性バリデーターを直接実行します。

cd data/cdif-129085c
python ConformanceValidate.py ../../samples/nhanes-participant/cdif-dm-xy8upneajsb8vdcmnve01g6g.jsonld --source local --frame CDIF-frame-2026.jsonld

固定したコミットでの結果：Core SHACLに合格、Discovery JSON SchemaとSHACLに合格、Data Description JSON SchemaとSHACLに合格、違反は0件、宣言された3つのプロファイルは検出器がコンテンツ内で見つけたプロファイルと整合しています。すべてのコードリストノードが、cdifCodelistビルディングブロックのJSON Schema、rules.shaclおよびconformance.shaclに合格します。

3. このプロジェクションで表現できなかったこと

パッケージに含まれていない情報は、補わずに省略しています。レコードの分布（レコードは公開されていませんが、モデルは公開されています）、時間的範囲、統計情報です。CDIFでは、これらはいずれも必須ではなく、推奨項目として定められています。モデル自体のDublin Core（subject、coverage、publisher、contributors、relation）はスキーマヘッダーから読み取り、モデラーが記述したとおりに公開されます。SDCStudioのフィールドのデフォルト値（coverageの「Universal」、relationの「None」、空欄）は未設定として扱われます。そのため、NHANESのドキュメントにはこれらの情報がありません。モデラーがデフォルト値のままにしたためです。推奨項目のうち1つはパッケージから読み取るのではなく宣言されているため、その旨をここに記載しています。発行者の連絡先（サンプルではsrc/sdccdif/data/declared.jsonにある[email protected]。--contact-nameと--contact-emailで上書きでき、アドレスが空の場合は省略されます）。

一方、レコードには含まれているものの、記述には記載箇所がない情報についても説明します。どちらかの欠点ではなく、読者が参照先を把握できるようにするためです。

• ガバナンスを構成する情報は、すべてのレコードにデータとして含まれています。 各Governed Data Recordには、監査イベント、PROVアクティビティ、PROVエージェントがリーフとして含まれており、ほかの項目と併せて検証されます。CDIFの来歴情報はデータセットの属性です。ライターはこれらのリーフをAttributeロールの変数として一覧にするため、読者はその存在を確認できます。レコードごとの値はレコード内にあります。
• スキーマはコレクションだけでなく、各レコードにも紐付けられています。 各レコードには、検証に使用したスキーマが記載されており、スキーマは公開後に変更されることはありません。記述では、データセットに一度記載すればよく、それを担うのがSHA-256を含むdcterms:conformsToとschema:publishingPrinciplesです。
• 値が欠損している理由は、レコード内で型として示されます。 リーフの値の代わりに、16種類の例外値のいずれかを格納できます。これにより、回答の拒否、質問されていない値、プライバシー保護のためにマスキングされた値を、それぞれ異なる事実として扱えます。CDIFのセンチネル値ドメインではその集合を説明し、どの理由がどこに当てはまるかはレコード内に示されます。

4. CDIF プロファイルについてわかったこと

上記のピン留めされた成果物を使って実装した際の実装者向けメモです。成果物の動作を説明しているため、次の実装者がこれらではなく、自分のドキュメントに時間を費やせるようにしています。

• フレームには、参照されるノードがすべて埋め込まれます。 CDIF-frame-2026.jsonld では全体を通して @embed: @always が指定されているため、多くの場所から参照されるノード（ここでは、153 個の変数から参照される 1 つのセンチネルドメイン）は、フレーム化されたツリー内の各参照箇所で繰り返されます。検証上は問題ありませんが、フレーム化されたドキュメントのサイズはソースの何倍にもなります。schema:Dataset ではない兄弟の @graph ノード（コードリスト）はフレーム化された出力には現れず、コードリストのビルディングブロックに対して別途検証されます。
• cdif:role: Attribute には cdif:qualifies が必要です。 Data Description の SHACL は、DDI-CDI に従って、すべての属性にその属性が該当する変数を指定するよう求めます。レコードレベルの属性では、指し示すレコードの単位識別子があり、このライターはそれを使用します。
• 適合性検出器は、インスタンス変数のルールに基づいて Data Description の判定を行います。 detect_conformance.py は、クラスごとの SHACL に合格した場合にのみプロファイルが存在すると報告するため、Data Description を宣言していてもそれらのルールに違反するドキュメントは、プロファイルへの適合失敗ではなく、プロファイルを過剰に主張していると報告されます。SHACL セクションを先に読むと、適合性セクションの内容がわかりやすくなります。
• ローカルの適合性マップには、Discovery、Data Description、Complete の JSON Schema があります。 Core は SHACL のみで検証され（no schema mapped が想定される行です）、Codelist プロファイルにはエントリーがありません。そのため、コードリストをカタログレコード上で宣言し、ConformanceValidate.py を通じて検証することはできません。ビルディングブロック独自のスキーマとルールで直接検証します。
• cdif:physicalDataType には文字列または参照を指定します。 CDIF 独自の例では両方（"xsd:integer" と XML Schema の完全な URL）が使われています。ここでは文字列形式を使用しています。
• IRI 形式の値は、IRI 参照でなければなりません。 IRI または CURIE のように見える文字列として記述された schema:propertyID と schema:additionalType は SHACL 違反になります。受け入れられる形式は {"@id": ...} です。通常のラベルは文字列のままです。
• SKOS プレフィックスはフレームのコンテキストに含まれていないため、フレーム化された出力では、バリデーターの圧縮処理で追加されるまで SKOS の完全な IRI が表示されます。 これは想定どおりです。中間出力を見ても慌てないよう、ここに記しておきます。

MCP サーバー

sdccdif は MCP サーバーでもあり、io.github.SemanticDataCharter/sdccdif として登録されています。そのため、sdcreader を使って公開済みのモデルを読み取れるアシスタントは、その CDIF の説明を問い合わせることができます。ツールは 1 つで、write_cdif が CLI と同じ関数を呼び出します。stdio を使用し、返すドキュメント以外は読み取り専用です。アカウントは不要です。ツールが URL を受け取ることはありません（カタログホストは起動時に --host で固定します）。プロトコルのひな型は sdcreader.mcp で、すべての SDC 投影サーバーで共有されています。

uvx sdccdif mcp            # or: sdccdif-mcp, or sdccdif mcp

ディレクトリ構成

• モデルのパッケージは sdcreader（load_package、fetch_package、read_model）で読み取ります。レコードツリーとそのリーフ、コード付きの列挙値、SDCStudio のデフォルト値を未設定として扱ったモデルの Dublin Core が含まれます。パッケージ形式は一度だけ、そこで説明されています。
• src/sdccdif/：cdif.py（JSON-LD）、cli.py、data/sdc4-exceptional-values.json（SDC4 リファレンスモデルのスキーマから抽出した 16 個の例外値）。
• data/cdif-129085c/：CDIF のコンテキスト、フレーム、JSON Schema、SHACL、適合性マップ、バリデーター。data/mbb-61f24aa/：cdifCodelist ビルディングブロックと、検出器が判定に使うクラス別の 3 つのルール。
• samples/nhanes-participant/：取得したモデルのパッケージと、そこから作成したドキュメント。
• build/snapshot_cdif.py：ピン留めされたコミットの CDIF リポジトリを読み取り専用でクローンし、data/ を再作成します。

ライセンス

Apache-2.0（LICENSE、NOTICEを参照）。data/内のCDIF成果物は、それぞれ独自のライセンスを適用しています。validation リポジトリはCC0、building blocksはCC BY 4.0、CODATAおよびCross-Domain Interoperability Frameworkのライセンスです。