sdcdcatap

sdc_dcat3_ap

一个以 DCAT-AP 3.0.1 描述的 Semantic Data Charter 模型。

sdcdcatap 读取已发布 SDC 模型的包，并生成 dcat:Catalog。DCAT-AP（面向欧洲数据门户的 DCAT 应用配置文件）要求门户交换此目录：每个模型对应一个 Dataset；模型的架构既作为其记录所遵循的标准（dct:conformsTo）引用，也作为定义其变量的文档（foaf:page）引用，并提供 URL 和 SHA-256。输出为一个 rdflib 图，序列化为 Turtle 和 JSON-LD。输出使用 SEMIC 自身在固定提交版本中的 SHACL 形状以及 Interoperability Test Bed 的 SEMIC 验证器进行检查。

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

示例 samples/nhanes-participant/catalog.ttl（以及 catalog.jsonld，两者表示同一张图）是一个包含单个 Dataset 的 Catalog：来自 FAIR Data Demo 的 NHANES Participant（dm-xy8upneajsb8vdcmnve01g6g）记录，即美国国家健康与营养调查（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]"
sdcdcatap write --package samples/nhanes-participant --out catalog.ttl --jsonld catalog.jsonld
sdcdcatap write --ct-id xy8upneajsb8vdcmnve01g6g --ct-id <another> --save-package pkg/ --out catalog.ttl   # a catalog of models, from the public catalog
sdcdcatap write --package DIR --catalog my-catalog.yaml --out catalog.ttl                                  # a publisher's own declared input

两类输入，彼此分开。 来自模型包（其 JSON-LD、架构、公开目录记录和已发布的架构版本；无需账号；没有模型包的模型将被拒绝）的信息：标题、描述、标识符、创建者、日期、许可证、架构的 URL 和 SHA-256、变量数量，以及模型创建者填写的模型自身 Dublin Core 信息（发布者、主题关键词、贡献者、覆盖范围）。来自目录发布者的信息则在 catalog.yaml 中声明，因为该配置文件的受控词汇和取值范围规则要求提供模型包无法确定的值：联系人、欧盟数据主题、访问权限、语言、发布者的 ADMS 类型、目录自身的标题、描述和主页。示例附带了一个默认文件（src/sdcdcatap/data/catalog.yaml）；发布者应提供自己的文件。

每个被引用的节点都内联声明类型和名称。 取值范围形状要求每个对象值都是其所属类的实例；必需形状要求图中所有 Agent 都有名称，所有概念都有标签。因此，发布者是带有 foaf:name 的 foaf:Agent，主题是在所属词表中带有 skos:prefLabel 的 skos:Concept，许可证是 dct:LicenseDocument，语言是 dct:LinguisticSystem，依此类推。这样，采集门户就能获得一张完整的图。

Dataset 包含：

dct:title、dct:description	模型自身的标题和描述，带英语语言标签，另加一句说明受治理数据记录是什么，并说明架构不可更改
dct:identifier、adms:identifier	dm-xy8upneajsb8vdcmnve01g6g，既作为字面值，也作为带有 skos:notation 的 adms:Identifier
dct:conformsTo	一个 dct:Standard：位于固定 URL（?sha256=）的架构，SHA-256 作为 dct:identifier
foaf:page	一个 foaf:Document：位于稳定 URL 的架构，描述为数据字典（153 个变量）；其 dct:format 是来自 File Type NAL 的 XML；该文档本身遵循 SDC4 参考模型
dct:publisher、dct:creator	带有名称的 foaf:Agent；发布者还带有其 ADMS 类型和主页
dcat:contactPoint	一个带有 vcard:fn 和 vcard:hasEmail 的 vcard:Kind，取自声明的输入
dcat:theme、dct:language、dct:accessRights	取自声明的输入：欧盟数据主题词汇中的 HEAL、Languages NAL 中的 ENG、Access Rights NAL 中的 PUBLIC
dct:license	模型的许可证 URL，类型为 dct:LicenseDocument
dcat:keyword、dcat:landingPage、dct:issued、dct:modified	来自模型包
dct:provenance、dcat:version	一个 dct:ProvenanceStatement：已发布的模型永不更改；修订版是一个新模型，并指明所修订的模型；SHA-256 作为版本

Catalog 包含其标题、描述、发布者、主页、语言、日期、作为 dcat:themeTaxonomy 的 Data Theme 词汇，以及该 Dataset。

2. 如何验证

测试使用 pySHACL 对 data/dcat-ap-3.0.1-4470b8e/ 中的 SEMIC 形状运行验证。该目录是在固定提交上复制的 （build/snapshot_dcat_ap.py 会先验证固定提交）：

pip install -e ".[dev]"
python -m pytest tests -q                   # the Interoperability Test Bed test runs too, over the network
python -m pytest tests -q -m "not network"  # offline, as CI runs it

离线验证：必需属性形状（dcat-ap-SHACL.ttl）和范围形状（ranges.ttl）均符合要求， 适用于 Turtle 和 JSON-LD。已提交的样例经断言，与全新运行生成的结果同构。

第二个验证方是 Interoperability Test Bed 的 SEMIC SHACL 验证器（https://www.itb.ec.europa.eu/shacl/dcat-ap/， 2026 年 10 月 9 日的 v1.14.0-SNAPSHOT，通过其 REST API），针对样例的验证结果如下：

验证类型	结果
dcatap.3_0_1_base0（必需项，不含背景知识）	符合要求
dcatap.3_0_1_range0（范围，不含背景知识）	符合要求
dcatap.3_0_1_codelists（受控词汇）	符合要求，有 3 条警告：发布者不在 EU Corporate Bodies NAL 中（它是一家公司，而非欧盟机构）
dcatap.3_0_1_rec（建议项）	符合要求，有 19 条警告，见第 4 部分
dcatap.3_0_1_full（全部检查，含背景知识）	有 11 项违规，但文档中并不存在这些问题：见第 4 部分

网络测试会断言前四项。

3. 投影无法表达的内容

这些内容被省略，而不是凭空补全：

• 没有记录的 dcat:distribution。 FAIR Data Demo 的记录未发布，发布的是模型。该配置文件建议提供分发项，但并未要求；只有发布者声明了访问 URL 时，写入器才会生成分发项。
• 没有时间覆盖范围、几何信息、频率、数据集系列或数据服务。 软件包不包含这些信息。空间覆盖范围、主题关键词、贡献者以及模型自身的发布者信息，取自模型编写者填写的模型 Dublin Core；SDCStudio 的字段默认值（覆盖范围为 “Universal”、关系为 “None”、其余为空白）被视为未设置，因此 NHANES 目录中不包含这些信息。
• 没有任何需要发布者自行决定的内容。 数据主题、访问权、语言、发布者类型和联系点都作为输入明确声明，并在此处说明；只有样例使用了默认值。

反过来，记录中包含但目录条目没有位置存放的内容也在此列出，让读者知道该去哪里查找，而非将其视为任何一方的缺陷：

• 每条记录都包含治理封套数据。 每条 Governed Data Record 都包含自己的审计事件、PROV 活动和 PROV Agent，并经过验证。DCAT-AP 的 dct:provenance 和 prov:wasGeneratedBy 描述的是数据集；每条记录各自的事实则保存在记录中，其定义见目录所指向的架构。
• 每条记录都绑定了架构。 每条记录都会标明用于验证它的架构；目录通过 dct:conformsTo 和 SHA-256 一次性说明该架构。
• 记录中会对缺失值的原因进行类型标注。 叶节点可使用十六种特殊值之一代替其值；这些值由架构定义，适用哪一种以及适用位置则记录在记录中。
• 没有数据字典字段。 DCAT-US 3.0 提供了 describedBy，用于列出“所有变量的名称和定义”；DCAT-AP 提供了 dct:conformsTo 和 foaf:page，此处用它们来指向架构。

4. 关于 DCAT-AP 3.0.1 及其验证器的经验

基于 SEMICeu/DCAT-AP 的提交 4470b8e 和 2026 年 10 月 9 日的互操作性测试平台进行构建时的实现者笔记。这些笔记说明了各项产物的行为，让下一位实现者能把时间花在自己的目录上，而不是这些问题上。

• 为所有引用的内容指定类型和名称。 ranges 文件会检查每个对象属性的 sh:class，而 base 文件要求图中的每个 foaf:Agent 都有 foaf:name，每个 skos:Concept 都有 skos:prefLabel，包括你仅仅引用的词汇术语（ADMS 发布者类型、数据主题）。SEMIC 自己的最小示例将发布者设为裸 URI，通过了强制形状检查，却正是因此未通过范围检查。
• full 和 base 类型会报告文档中并不存在的违规。 将一个空的最小目录（标题、描述、具名发布者）提交给 dcatap.3_0_1_base，会返回与我们的示例相同的五条空白节点 Agent 的 foaf:name 违规；full 还会增加六条 ADMS 概念方案的 dct:title 违规（http://purl.org/adms/publishertype/1.0 及其同类项）。这些违规来自这些类型加载的背景知识，而非内容。请分别检查四个组（base0、range0、codelists、rec），它们只会报告文档中的问题；第 2 部分的表格就是如此。
• 建议类型会将 Catalog 视为 Dataset。 将 DCAT 作为背景知识加载后（dcat:Catalog 是 dcat:Dataset 的子类），Dataset 的建议也会应用于 Catalog：联系点、分发、关键词、主题、空间和时间范围、许可证。示例中的 19 条警告里有 9 条属于这些；其余警告涉及 Dataset 缺少分发、空间和时间范围、创建者 Agent 和许可证文档（ADMS 许可证类型）缺少 dct:type，以及发布者不属于 Corporate Bodies NAL。
• ranges.ttl 引用了未定义的属性形状。 有 206 个 sh:property 三元组指向自身没有三元组的节点。基于 Jena 的验证器会跳过这些节点；pySHACL 则拒绝运行（“not a well-formed SHACL PropertyShape”）。测试会在运行前删除未定义的引用；实际检查的是 91 个已定义的属性形状。
• REST API 很简单。 向 https://www.itb.ec.europa.eu/shacl/dcat-ap/api/validate 发送 POST 请求，并附上包含 contentToValidate（作为字符串的文档）、embeddingMethod: STRING、contentSyntax、validationType 和 reportSyntax 的 JSON 请求体；响应是 SHACL 验证报告。/api/info 会列出验证类型和验证器版本。JSON-LD 和 Turtle 的结果相同。
• dcat:version 是 DCAT 3 的属性，rdflib 的封闭式 DCAT 命名空间并不识别它；请手动构建 IRI。
• 语言是 NAL 概念，而不是标签。 dct:language 接受 http://publications.europa.eu/resource/authority/language/ENG，即一个 dct:LinguisticSystem；BCP 47 字符串无法通过范围检查。

MCP 服务

sdcdcatap 也是一个 MCP 服务，注册名为 io.github.SemanticDataCharter/sdcdcatap，因此，能够通过 sdcreader 读取已发布模型的助手可以请求其 DCAT-AP 3.0.1 描述。一个工具 write_catalog，使用与 CLI 相同的函数；stdio；除其返回的文档外均为只读；无需账号；没有工具会接收 URL（目录主机在启动时通过 --host 固定）。协议脚手架为 sdcreader.mcp，由每个 SDC 投影服务共享。

uvx sdcdcatap mcp            # or: sdcdcatap-mcp, or sdcdcatap mcp

目录结构

• 模型包通过 sdcreader 读取（load_package、 fetch_package、read_model）：记录树及其叶节点、带有代码的枚举值，以及模型的 Dublin Core，其中 SDCStudio 的默认值为未设置状态。包格式仅在此处记录一次。
• src/sdcdcatap/：dcatap.py（图）、cli.py、data/catalog.yaml（示例中声明的输入）。
• data/dcat-ap-3.0.1-4470b8e/：该固定版本中的 SEMIC 形状文件、上下文、示例和变更日志。
• samples/nhanes-participant/：获取的模型包，以及据此生成的目录，格式为 Turtle 和 JSON-LD。
• build/snapshot_dcat_ap.py：从固定提交的 SEMICeu/DCAT-AP 只读克隆重新生成 data/。

许可证

Apache-2.0（参见 LICENSE、NOTICE）。data/ 中的 DCAT-AP 工件版权归 © European Union 所有，采用 CC BY 4.0 许可，并在此保留该许可证。