sdcreader

sdcreader

公開された Semantic Data Charter モデルのパッケージを読み込み、他の標準規格に投影します。

投影とは、モデルが管理するデータレコードを別の標準規格の用語で記述するものです。対象は CDIF、DCAT-US 3.0、DCAT-AP 3.0.1、HealthDCAT-AP、そして今後登場する規格です。どの投影も同じ根拠資料、つまりモデルのパッケージを記述し、同じ形式に読み込みます。sdcreader は、その根拠資料と形式を一度だけ定義したもので、いずれの投影にも関する要素は含みません。このパッケージができるまで、4 つの投影ライター（sdc_cdif、sdc_dcat3_us、sdc_dcat3_ap、sdc_healthdcat_ap）は、同一のものをそれぞれコピーして保持していました。

pip install sdcreader            # the reader, with HTTP for fetching from the public catalog (since 4.1.0 no extra is needed)

from sdcreader import fetch_package, load_package, read_model

pkg = load_package("samples/nhanes-participant")          # a package on disk
pkg = fetch_package("xy8upneajsb8vdcmnve01g6g", save_to="pkg/")   # or from SDCStudio's public catalog, no account
model = read_model(pkg)

pkg.schema_url_pinned        # https://sdcstudio.axius-sdc.com/dmlib/dm-xy8u...xsd?sha256=0df4...   the exact bytes the records are validated against
model.title, model.leaves    # 'NHANES Participant', 153 leaves in document order, each with its path of clusters
model.codes[ct_id]           # the enumerated values of a component with the IRI, definition and code the schema annotates them with
model.dc("publisher")        # what the modeler wrote, None where SDCStudio's default sits

パッケージとは

SDCStudio は公開されたモデルごとにパッケージを生成し、公開プロジェクト内のモデルについては一般に公開します。

GET /api/v1/catalog/dm/<ct>/	カタログレコード：タイトル、説明、プロジェクト、アーティファクト一覧（catalog.json）
GET /api/v1/catalog/dm/<ct>/<artifact>/	{"download_url": ..., "filename": ..., "storage": "gcs"} 形式のストレージポインター。jsonld、xsd などを対象とし、リーダーがそのポインターをたどります
dm-<ct>.jsonld	モデルとその構成要素：型、ラベル、説明、カーディナリティ、制約（列挙値、単位、範囲、パターン）、セマンティックリンク（dcterms:identifier はライブラリのスロット、dcterms:source、dcterms:publisher、skos:exactMatch、rdfs:seeAlso、prov:wasRevisionOf）、contains
GET /dmlib/dm-<ct>.xsd	スキーマのバイト列：モデルの Dublin Core ヘッダーと、各列挙値の定義およびその定義元コード（dm-<ct>.xsd）
GET /dmlib/dm-<ct>.versions.json	SHA-256 ごとのスキーマの公開済みバージョンと、現在のバージョン（versions.json）

パッケージディレクトリには、これら 4 つのファイルが格納されます。リーダーは、JSON-LD またはスキーマのないディレクトリ、識別子がディレクトリのモデルと一致しない JSON-LD、公開中の現行バージョンとバイト列が一致しないスキーマを拒否します。投影ではスキーマを URL と SHA-256 で参照するため、その URL が提供するバイト列でなければなりません。

パッケージには 2 つの不足点があり、SDCStudio の課題トラッカーに記録されています。JSON-LD のメタデータからスキーマヘッダーにあるフィールドが欠落していること（#748）と、ヘッダーに dc:source がないこと（#749）です。リーダーはモデルの Dublin Core を、完全なヘッダーから取得します。

リーダーが提供するもの

• ModelPackage：4 つのファイル、SHA-256、スキーマ URL とその固定形式（?sha256=）、公開カタログ URL、および check()。
• Model：title、description、root（管理対象レコードのクラスター）、識別子ごとの components、文書順の leaves（各 Leaf は component、クラスターの path、およびレコード内で一意なそのパスの slug を持ちます）、codes（コンポーネントごとの列挙値。Code として、値、IRI、定義、定義元のコードを保持）、metadata（JSON-LD のもの）、header（スキーマの Dublin Core）。
• Model.dc(name)：モデル作成者が記述した値を、まずヘッダー、次に JSON-LD の順で取得します。SDCStudio のフィールド既定値は未設定として扱います。coverage は「Universal」、relation は「None」、type は「SDC Data Model (DM)」、その他は空欄です。投影で既定値を事実として公開することはありません。contributors、subjects（セミコロン区切りのリスト）、rights_url、rights_statement はこれに基づきます。
• Component：sdc_type、label、description、data_type、constraints、述語ごとの links（最初のリンクを取得する link(p)）、contains、iri。
• 定数：リーフ型、数値型、数量型、述語の IRI IDENTIFIER、SOURCE、PUBLISHER、EXACT、CLOSE、SEE_ALSO、HAS_UNIT、および DC_DEFAULTS。

MCP サーバー

sdcreader は MCP サーバーでもあり、io.github.SemanticDataCharter/sdcreader として登録されているため、アシスタントは、sdcvalidator、sdcgovernance、sdcreceipt を使ってレコードの検証、ガバナンス、精算を行うのと同じように、公開済みのモデルを読み取れます。 stdio、SDK 不要、アカウント不要、読み取り専用です。

uvx sdcreader                    # or: sdcreader-mcp, or python -m sdcreader.mcp_server
uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's public catalog

ツール	内容
find_models	テキストで公開カタログを検索するか、公開プロジェクトのモデルを名前で一覧表示します
describe_model	1 つのモデルについて、タイトル、プロジェクト、ルートレコード、タイプ別のリーフ数とコンポーネント数、SDCStudio の既定値が null の場合のダブリンコア、SHA-256 に固定されたスキーマ URL を表示します
list_leaves	ドキュメント順にリーフを、パス、タイプ、制約、コード数、ID リンクとともにページ分けして表示します
list_codes	1 つのコンポーネントの列挙値を、IRI、定義、コード体系とともに表示します
check_package	パッケージディレクトリに対してリーダーの整合性チェックを実行します

各ツールには、サーバーの起動時に接続したホストから取得する ct_id、またはディスク上のパッケージ directory を指定します。 どのツールも URL は受け取りません。ホストは起動時に固定されるため、呼び出し元がサーバーの接続先を変更することはできません。すべてのツールがライブラリと同じ関数を呼び出すため、2 つのインターフェースで同じモデルが同じように記述されます。

テスト

pip install -e ".[dev]"
python -m pytest tests -q                    # includes one fetch against production
python -m pytest tests -q -m "not network"   # offline, as CI runs it

フィクスチャは FAIR Data Demo の NHANES Participant パッケージです。すべてのプロジェクションの検証に使われるレコードです。

バージョニング

先頭の 4 は SDC4 リファレンスモデルを示します。これはすべての Semantic Data Charter パッケージと同じです。リーダーが公開する内容の追加はマイナーバージョン、修正はパッチバージョンです。メジャーバージョンが変わるのは、リファレンスモデルが変更されたときだけです。

ライセンス

Apache-2.0（LICENSE、NOTICE を参照）。