sdcdcatus

sdc_dcat3_us

以 DCAT-US 3.0 描述的 Semantic Data Charter 模型。

sdcdcatus 读取已发布的 SDC 模型包，并生成 data.json Catalog。美国联邦数据目录标准 DCAT-US 3.0 要求机构发布此目录：每个模型对应一个 Dataset，模型的架构既作为数据字典（describedBy），也作为记录所遵循的标准（conformsTo），并提供 URL 和 SHA-256。输出会使用 GSA 自行提供的 JSON Schema 和固定提交版本的 GSA/dcat-us 验证脚本进行检查，并通过 Data.gov 的在线验证器验证。

1. 这是什么，以及它的来源

示例 samples/nhanes-participant/data.json 是一个包含一个数据集的目录：FAIR Data Demo 中 NHANES Participant（dm-xy8upneajsb8vdcmnve01g6g）的记录，这是一份来自 National Health and Nutrition Examination Survey（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

包含七个模型的目录。 samples/fair-data-demo/data.json 是对从公共目录获取的七个 FAIR Data Demo 模型（NHANES Participant 和 Medication、BRFSS Respondent、CMS Beneficiary、Inpatient Claim、Outpatient Claim 和 Prescription Drug Event）运行同一编写器的结果；每个模型包都保存在其旁边：一个 data.json，每个受治理模型对应一个数据集，每个数据集都以其架构作为数据字典。这就是每个模型对应一条全面数据清单条目的样子。

将两类输入分开处理。 模型包（其 JSON-LD、架构、公共目录记录和已发布的架构版本；无需账户；没有模型包的模型将被拒绝）提供：标题、描述、标识符、发布者、日期、语言、许可证、架构的 URL 和 SHA-256、变量数量。目录的发布者由 catalog.yaml 声明，因为架构或法规要求提供这些信息，而模型包无法获知：联系点、目录自身的标题、描述和主页，以及发布者对访问权限的声明。该包为示例附带一个默认文件（src/sdcdcatus/data/catalog.yaml）；各机构应提供自己的文件。

为什么使用 describedBy。 OMB Memorandum M-25-05 要求每个机构的全面数据清单都包含“数据资产中所有变量的名称和定义”，GSA 的对应表将此要求映射到 describedBy：一个指向机器可读数据字典的分发项。已发布的 SDC 架构正是这样的字典：每个变量都包含其标签、定义、数据类型、单位、允许值及其代码，以及十六种带类型的缺失值原因；架构发布后不可更改，并在此处通过 URL 和 SHA-256 引用。

数据集包含的内容：

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，并通过 conformsTo 指向 SDC4 参考模型
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

测试套件会先在快照上运行他们的脚本（他们的正确和错误语料库：在固定提交中通过 510 项，失败 0 项），随后使用他们的方法、一个按 $id 注册了所有定义的 referencing 注册表，以及带格式检查器的 Draft202012Validator 验证示例 Catalog、其中的 Dataset 和 describedBy Distribution：错误数为 0。

第二项佐证来自 Data.gov 的在线验证器：https://harvest.data.gov/validate/（schema“dcatus3.0 catalog”，粘贴或上传示例）：2026 年 10 月 9 日，单模型 Catalog 和七模型 Catalog 均显示 “No validation errors found”。测试也会检查七模型 Catalog，并断言提交的文件与基于已保存软件包重新运行所得的结果相同。

3. 投影无法说明的内容

宁可留空，也不擅自补全：

• 没有记录的 distribution。 FAIR Data Demo 的记录并未发布；发布的是模型。该 schema 允许 Dataset 不包含 distributions；当发布者声明了访问或下载 URL 时，写入器才会生成这些字段。
• 没有任何需要由政府机构认定的内容。 M-25-05 开放数据、FOIA、Federal Data Catalog、开放格式和许可相关认定，Title 44 声明，访问、使用和 CUI 限制，以及局和项目代码：这些都属于政府机构的声明。写入器只接受这些声明作为输入，不会为任何一项设置默认值。示例由一家公司而非政府机构发布，因此包含 accessRights: public，且没有任何认定。
• 没有时间覆盖范围、主题或质量测量值。 软件包不包含这些内容。空间覆盖范围、主题、贡献者、关系和权利声明只有在模型编写者填写时，才会取自模型自身的 Dublin Core；SDCStudio 的字段默认值（覆盖范围为“Universal”、关系为“None”、其余为空）视为未设置，因此 NHANES Catalog 不包含这些内容：其模型编写者保留了默认值。

以下内容是声明而非从软件包中读取，特此说明：联系点（示例中的 [email protected]）、Catalog 的标题、描述和主页、发布者的名称和标识符，以及 accessRights。

反过来，记录中包含、但 Catalog 条目没有相应位置的内容也列于下方，目的是让读者知道该去哪里查找，而非将其视为任何一方的缺陷：

• 治理信息封套是每条记录中的数据。 每条 Governed Data Record 都包含自己的审计事件、PROV 活动和 PROV Agent，并将它们作为经过验证的叶节点。DCAT-US 的 provenance、wasGeneratedBy 和 qualifiedAttribution 描述的是数据集；每条记录各自的信息则保存在记录中，定义见数据字典。
• 每条记录都绑定了自己的 schema。 每条记录都会注明用于验证的 schema；Catalog 只需说明一次，而 conformsTo 会通过 SHA-256 实现这一点。
• 记录会标明值缺失的原因类型。 叶节点可用 16 种例外值之一代替其值；数据字典对这些值有定义；适用的是哪一种以及所在位置，都记录在记录中。

4. 我们从 DCAT-US 3.0 中学到的内容

基于 GSA/dcat-us 的 4996591 版本构建时，实施者记录的说明。这些内容描述了各项制品的行为，帮助下一位实施者把时间花在自己的目录上，而不是花在这些问题上。

• 经过验证的表单是符合 JSON Schema 2020-12 的 JSON。 早期草案中的 JSON-LD 上下文和 SHACL 形状（来自内政部的代码库）位于 DEPRECATED/ 下；脚本和在线验证器检查的是 data.json。从 DCAT-AP（基于 RDF 的 SHACL）转来实施的人，不必去寻找形状。
• 格式断言需要额外组件。 定义使用了 format: date、date-time 和 iri。使用普通的 jsonschema 时，这些格式不会经过检查，而且 GSA 自己的 6 个“错误”示例会通过；使用其 CI 安装的 jsonschema[format] 时，语料库中的 510 个案例都会按标注结果处理。这里的测试需要这些额外组件。
• 未知属性也会通过。 类上没有设置 additionalProperties，因此拼写错误或过时的属性也会被接受，不会给出提示。验证器会告诉你缺少或格式不正确的内容，但不会告诉你它无法识别的内容。
• Null 表示“未提供”。 每个建议属性都明确允许 null（“非必需时允许 Null”）；省略该属性同样有效。
• language 是两个字母（ISO 639-1），这是相较于 v1.1 的 BCP 47 的一项有记录的重大变更；en-US 会验证失败。
• **日期有 4 种格式：**日期时间、日期、YYYY、YYYY-MM。
• identifier 可以是字符串，也可以是 Identifier 对象（notation、schemaAgency、version）；contactPoint 可以是一个 Kind，也可以是列表；hasEmail 必须匹配 mailto: 模式；license 是字符串（交叉映射表中则将其标为 URL）。
• describedBy 是 Distribution，而不是 Document，因此数据字典会有自己的 downloadURL、mediaType、checksum 和 conformsTo。这才是架构应有的形式。
• conformsTo 在 Catalog 上是单个 Standard，在 Dataset 上则是 Standard 列表。 两者的 identifier 都可以是字符串或 Identifier 对象。
• Distribution 没有必填属性，而 Dataset 有 4 个：title、description、contactPoint、identifier。法规要求的其他所有内容都是建议项。
• 注册表方法。 每个定义的 $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 也是一个 MCP 服务，注册为 io.github.SemanticDataCharter/sdcdcatus，因此能够使用 sdcreader 读取已发布模型的助手可以请求其 DCAT-US 3.0 描述。它提供一个工具 write_catalog，调用与 CLI 相同的函数；使用 stdio；除返回的文档外为只读；无需账户；没有工具会接收 URL（目录主机在启动时通过 --host 固定）。协议脚手架为 sdcreader.mcp，由每个 SDC 投影服务共享。

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

目录结构

• 模型的包通过 sdcreader 读取（load_package、fetch_package、read_model）：记录树、叶节点、带代码的枚举值，以及模型的 Dublin Core 元数据（将 SDCStudio 的默认值设为未设置）。包格式在该项目中已有一次性说明。
• 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 卷第 105 条），以 CC0 1.0 发布，并在此继续保持该状态。