sdcdcatus

sdc_dcat3_us

DCAT-US 3.0 で記述された、1 つの Semantic Data Charter モデルです。

sdcdcatus は、公開済みの SDC モデルのパッケージを読み込み、米国連邦データカタログの標準である DCAT-US 3.0 が各機関に公開を求める data.json カタログを書き込みます。モデルごとに 1 つの Dataset を登録し、モデルのスキーマをデータディクショナリ（describedBy）として、またレコードが準拠する標準（conformsTo）として、URL と SHA-256 で示します。出力は、固定コミットの GSA/dcat-us に含まれる GSA 独自の JSON Schema と検証スクリプト、および Data.gov のオンライン検証ツールでチェックされます。

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

サンプルの samples/nhanes-participant/data.json は、Fair Data Demo の NHANES Participant（dm-xy8upneajsb8vdcmnve01g6g）の記録を含む、1 つの Dataset を持つカタログです。これは、米国国民健康栄養調査（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

pip install -e ".[fetch]"
sdcdcatus write --package samples/nhanes-participant --out data.json
sdcdcatus write --ct-id xy8upneajsb8vdcmnve01g6g --ct-id <another> --save-package pkg/ --out data.json   # a catalog of models, from the public catalog
sdcdcatus write --package DIR --catalog my-catalog.yaml --contact-email [email protected] --out data.json  # a publisher's own declared input

7 つのモデルのカタログ。 samples/fair-data-demo/data.json は、公開カタログから取得した 7 つの Fair Data Demo モデル（NHANES Participant および Medication、BRFSS Respondent、CMS Beneficiary、Inpatient Claim、Outpatient Claim、Prescription Drug Event）に対して同じ書き込み処理を実行したもので、各パッケージも隣に保存されています。すなわち、1 つの data.json に、ガバナンス対象のモデルごとに 1 つの Dataset があり、それぞれにスキーマをデータディクショナリとして含みます。包括的なデータインベントリにおける、モデルごとのエントリはこのようになります。

2 種類の入力を分けて保持します。 モデルのパッケージ（JSON-LD、スキーマ、公開カタログレコード、公開済みのスキーマバージョン。アカウントは不要で、パッケージのないモデルは拒否されます）から取得するのは、タイトル、説明、識別子、発行者、日付、言語、ライセンス、スキーマの URL と SHA-256、変数の数です。スキーマや法令が求めていても、パッケージからは把握できない情報は、catalog.yaml で宣言するカタログ発行者から取得します。これには、連絡先、カタログ自体のタイトル、説明、ホームページ、アクセスに関して発行者が表明する内容が含まれます。パッケージにはサンプル用の既定ファイル（src/sdcdcatus/data/catalog.yaml）が含まれており、各機関は独自のファイルを用意します。

describedBy を使う理由。 OMB Memorandum M-25-05 は、各機関の包括的なデータインベントリに「データ資産のすべての変数の名称と定義」を含めることを求めています。また、GSA のクロスウォークでは、この要件を describedBy、つまり機械可読なデータディクショナリを指す Distribution に対応付けています。公開済みの SDC スキーマは、まさにそれに当たります。各変数には、ラベル、定義、データ型、単位、コード付きの許容値、値が欠損している場合の 16 種類の型付き理由が含まれます。スキーマは公開後に変更されず、ここでは URL と SHA-256 で参照します。

Dataset に含まれる情報：

title、description	モデルのタイトルと説明に、ガバナンス対象のデータレコードとは何か、スキーマがデータディクショナリであることを述べる一文を加えます
identifier	Identifier：notation は dm-xy8upneajsb8vdcmnve01g6g、schemaAgency は発行者です
contactPoint	宣言された入力から取得した、fn と hasEmail を含む Kind です
publisher、creator、landingPage、keyword、license、language en	パッケージから取得します。モデル作成者がモデルに dc:publisher を記述している場合はその値を、そうでない場合は宣言された発行者を使います
subject、contributor、spatial、relation、rights	モデル作成者がモデルの Dublin Core に記述している場合、その情報を使います。具体的には、主題キーワード、寄稿者、名前付きの Location としての対象地域、関連 URL、ライセンス URL に付随する権利表明です
describedBy	Distribution：スキーマの固定 URL を downloadURL として指定し、application/xml、XSD、SHA-256 の Checksum、SDC4 参照モデルへの conformsTo を含みます
conformsTo	同じ固定 URL を参照する Standard です
issued、modified	モデルの公開日です。inventoried はカタログの作成日です
accessRights	発行者がモデルについて宣言する public です
versionNotes	公開済みモデルは変更されません。改訂版は、改訂元のモデルを示す新しいモデルです。SHA-256 と永続性ページも含まれます

2. 検証方法

テストでは、data/dcat-us-4996591/ から GSA 独自のバリデーターを実行します。このディレクトリには、26 個のクラス定義、サンプルコーパス、test_json_schema.py が固定コミット時点でコピーされています（build/snapshot_dcat_us.py が最初にコミットの固定を検証します）。

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

テストスイートは、まずスナップショットに対して GSA のスクリプトを実行します（固定時点で、良好なデータと不正なデータからなるコーパスは 510 件が合格、0 件が失敗）。次に、サンプルの Catalog、その Dataset、および describedBy Distribution を、GSA のメソッドと、すべての定義を $id で登録した referencing レジストリ、さらにフォーマットチェッカーを使用する Draft202012Validator で検証します。エラーは 0 件です。

2 つ目の検証手段は、Data.gov のオンラインバリデーター（https://harvest.data.gov/validate/）です。スキーマに「dcatus3.0 catalog」を選択し、サンプルを貼り付けるかアップロードします。2026 年 10 月 9 日時点で、1 モデルのカタログと 7 モデルのカタログのどちらも 「検証エラーは見つかりませんでした」 という結果でした。7 モデルのカタログはテストでも検証されており、コミット済みのファイルが、保存済みパッケージを使った最新の実行結果と一致することも確認されています。

3. この投影では表現できなかったこと

補完するのではなく、次の情報は含めていません。

• レコードの distribution はありません。 FAIR Data Demo のレコードは公開されていません。公開されているのはモデルです。スキーマでは、Dataset に Distribution がなくても構いません。作成ツールは、公開者がアクセス URL またはダウンロード URL を宣言した場合にそれらを出力します。
• 政府機関が判断すべき事項は含まれていません。 M-25-05 に基づくオープンデータの判断、FOIA、Federal Data Catalog、オープン形式およびライセンスに関する判断、Title 44 の記述、アクセス、使用、CUI の制限、局およびプログラムのコードは、すべて政府機関が表明する事項です。作成ツールは、これらを宣言された入力としてのみ受け取り、いずれもデフォルト値を設定しません。政府機関ではなく企業が公開したサンプルには、accessRights: public が含まれ、判断事項は含まれていません。
• 時間的範囲、テーマ、品質測定値はありません。 パッケージにはこれらの情報が含まれていません。空間的範囲、主題、寄稿者、関連、権利に関する記述は、モデラーが記入している場合に限り、モデル自体の Dublin Core から取得されます。SDCStudio のフィールドのデフォルト値（範囲の「Universal」、関連の「None」、空欄）は未設定として扱われます。そのため、NHANES カタログにはこれらの情報が含まれていません。モデラーがデフォルト値のままにしているためです。

パッケージから読み取るのではなく、宣言された情報であることをここに明記します。連絡先（サンプルでは [email protected]）、カタログのタイトル、説明、ホームページ、公開者の名前と識別子、accessRights です。

逆に、レコードには含まれていてもカタログ項目には記載する場所がない情報についても、いずれかの側の欠点ではなく、読者が確認先を把握できるように明記します。

• ガバナンスの情報は、すべてのレコードに含まれています。 各 Governed Data Record には、検証済みのリーフとして、それぞれの監査イベント、PROV アクティビティ、PROV エージェントが含まれています。DCAT-US の provenance、wasGeneratedBy、qualifiedAttribution はデータセットを記述するものです。レコード単位の情報はレコードに含まれ、データ辞書で定義されています。
• スキーマは各レコードに紐付けられています。 すべてのレコードに、検証に使用したスキーマが記されています。カタログではその情報を一度だけ記載でき、SHA-256 を含む conformsTo がその役割を果たします。
• 値が欠落している理由は、レコード内で型付きで示されます。 リーフでは値の代わりに、16 種類の例外値のいずれかを指定できます。これらはデータ辞書で定義されており、どの例外値がどこに適用されるかはレコードに記されています。

4. DCAT-US 3.0 についてわかったこと

GSA/dcat-us のコミット 4996591 に対して実装した際のメモです。成果物の動作を説明しているので、次の実装者がこの点の確認に費やす時間を、自分のカタログに使えるようにまとめています。

• 検証対象の形式は、JSON Schema 2020-12 に対する JSON です。 以前のドラフトにあった JSON-LD コンテキストと SHACL シェイプ（内務省のリポジトリにあるもの）は DEPRECATED/ の下にあります。スクリプトとオンラインバリデーターが検証するのは data.json です。RDF に対する SHACL を使用する DCAT-AP から移行する実装者は、シェイプを探す必要はありません。
• 形式の検証には追加パッケージが必要です。 定義では format: date、date-time、iri を使用しています。通常の jsonschema ではこれらは検証されず、GSA 独自の「不正な」例のうち 6 件が合格します。GSA の CI でインストールされている jsonschema[format] を使えば、コーパスの 510 件すべてがラベルどおりに動作します。ここでのテストには追加パッケージが必要です。
• 未知のプロパティも合格します。 クラスに additionalProperties が設定されていないため、スペルミスのあるプロパティや古いプロパティもメッセージなしで受け入れられます。バリデーターが知らせるのは、欠落または不正な内容であり、認識されなかった内容ではありません。
• null は「指定されていない」という意味です。 推奨プロパティはすべて、明示的に null を受け入れます（「必須でない場合は Null を許可」）。プロパティを省略することも同様に有効です。
• language は 2 文字です（ISO 639-1）。これは v1.1 の BCP 47 からの変更点として文書化されており、互換性を破る変更です。en-US は失敗します。
• 日付には 4 つの形式があります。 date-time、date、YYYY、YYYY-MM です。
• identifier は文字列または Identifier オブジェクト（notation、schemaAgency、version）です。contactPoint は Kind 1 つ、またはそのリストです。hasEmail は mailto: パターンに一致する必要があります。license は文字列です（クロスウォークでは URL とされています）。
• describedBy は Document ではなく Distribution です。そのため、データディクショナリには downloadURL、mediaType、checksum、独自の conformsTo が必要です。これはスキーマに適した形式です。
• conformsTo は、Catalog では単一の Standard、Dataset ではそのリストです。 どちらも identifier に文字列または Identifier オブジェクトを指定できます。
• Distribution に必須プロパティはありません。 Dataset には title、description、contactPoint、identifier の 4 つがあります。法令で求められるその他の項目はすべて推奨項目です。
• レジストリ方式。 各定義の $id は https://resources.data.gov/dcat-us/3.0.0/definitions/<class> で、参照先は /dcat-us/3.0.0/definitions/<class> というパスです。このディレクトリを基に referencing レジストリを構築すると、test_json_schema.py のように参照を解決できます。サンプルでは、オンラインバリデーターとスクリプトの結果も一致しました。

MCP サーバー

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

uvx sdcdcatus mcp            # or: sdcdcatus-mcp, or sdcdcatus mcp

構成

• モデルのパッケージは sdcreader（load_package、fetch_package、read_model）で読み取ります。パッケージには、レコードツリー、そのリーフ、コード付きの列挙値、未設定として扱われる SDCStudio の既定値を含むモデルの Dublin Core が含まれています。パッケージ形式については、そちらで一度だけ説明しています。
• src/sdcdcatus/：dcatus.py（Catalog）、cli.py、data/catalog.yaml（サンプルの宣言済み入力）。
• data/dcat-us-4996591/：ピン留めしたコミット時点の GSA の定義、サンプル、バリデーター、README。
• samples/nhanes-participant/：取得したモデルのパッケージと、そこから書き出した data.json。
• build/snapshot_dcat_us.py：ピン留めしたコミットの GSA/dcat-us を読み取り専用でクローンし、data/ を再作成します。

ライセンス

Apache-2.0（LICENSE、NOTICEを参照）。data/内のDCAT-US成果物は米国政府の著作物（17 USC § 105）であり、CC0 1.0のもとで公開され、このプロジェクトでもその状態が維持されています。