sdccdif

sdc_cdif

一种用 CDIF 描述的 Semantic Data Charter 模型。

sdccdif 读取已发布 SDC 模型的包，并写入描述符合该模型的 Governed Data Records 集合的 CDIF JSON-LD：数据集的 Core 和 Discovery、记录每个叶节点的 Data Description、每个枚举叶节点对应的 Codelist，以及一个包含参考模型 16 个特殊值的哨兵值域。输出会使用 CDIF 自带的框架、JSON Schemas、SHACL 和一致性验证器进行检查；这些工具来自固定提交版本的 validation 仓库。

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

示例文档 samples/nhanes-participant/cdif-dm-xy8upneajsb8vdcmnve01g6g.jsonld 描述了一个已发布模型的记录：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

写入器会读取模型包（模型的 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 中填写了这些信息，还包括发布者名称、主题关键词、贡献者和覆盖范围（schema:spatialCoverage，表示为具名 Place）
schema:publishingPrinciples	永久性页面：已发布模型不可变更；变更时须创建一个新模型，并注明其修订的模型
dcterms:conformsTo	通过已发布 URL（附带 ?sha256=）指定架构，并提供字节的 spdx:Checksum
schema:variableMeasured	153 个 cdi:InstanceVariable，按文档顺序对应记录的每个叶节点，包含路径、库槽位（作为 schema:propertyID）、skos:exactMatch 概念（作为 cdif:uses）、XSD 数据类型、单位、范围、实质性值域和共享哨兵值域
cdif:role	受访者序列号是 UnitIdentifier；治理叶节点（审计事件、PROV 活动和代理）是用于限定它的 Attribute；其他所有项都是 Measure
cdif:hasPrimaryKey	单元标识符
67 个 skos:ConceptScheme	每个枚举组件对应一个，每个值均作为 skos:notation，并带有其定义和所依据的代码；重复组合三次的组件只对应一个代码表，但会被引用三次
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 文档不包含这些内容：其建模者保留了默认值。软件包中没有、而是另行声明的一项建议内容，我们在此明确说明：发布者的联系点（样例中为 [email protected]，位于 src/sdccdif/data/declared.json；--contact-name 和 --contact-email 可覆盖此值，地址为空时则不包含该项）。

反过来说，记录中包含而描述没有位置可容纳的内容，也在此说明，让读者知道该去哪里查阅，而非将其视为任一方的缺陷：

• 治理信息封套是每条记录中的数据。 每条治理数据记录都将自己的审计事件、PROV 活动和 PROV Agent 作为叶节点，并与其余内容一同验证。CDIF 的来源信息是数据集的属性。编写器会将这些叶节点列为 Attribute 角色的变量，让读者看到它们的存在；每条记录的具体值则保存在记录中。
• 架构与每条记录绑定，而非仅与集合绑定。 每条记录都会注明用于验证它的架构，且架构在发布后不会更改。描述只需在数据集层面说明一次，这正是 dcterms:conformsTo 与 SHA-256 值以及 schema:publishingPrinciples 的作用。
• 记录会对缺失值的原因进行类型标注。 叶节点可以用 16 种例外值之一代替其值，因此拒绝回答、未询问某项内容以及因隐私原因屏蔽某个值，是不同的事实。CDIF 的哨兵值域描述了这些值的集合；具体适用哪种原因以及适用位置，则记录在记录中。

4. 我们对 CDIF 配置文件的了解

根据上述固定版本的构件进行构建时的实现者笔记。这些笔记描述了构件的行为，让下一位实现者可以把时间花在自己的文档上，而不是研究这些构件。

• 框架会嵌入所有被引用的节点。 CDIF-frame-2026.jsonld 全程使用 @embed: @always，因此，在多个位置被引用的节点（此处是一个被 153 个变量引用的哨兵域）会在框架化树中的每个引用处重复出现。这不会影响验证；框架化文档的大小是源文档的许多倍。不是 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 检查；构建块自身的 Schema 和规则会直接检查它。
• cdif:physicalDataType 可接受字符串或引用，CDIF 自带的示例两种形式都有（"xsd:integer" 和完整的 XML Schema URL）。这里使用字符串形式。
• 形如 IRI 的值必须是 IRI 引用。 将 schema:propertyID 和 schema:additionalType 写成看起来像 IRI 或 CURIE 的字符串会违反 SHACL；可接受的形式是 {"@id": ...}。普通标签仍然使用字符串。
• 框架的上下文中没有 SKOS 前缀，因此在验证器的压缩步骤添加该前缀之前，框架化输出会显示完整的 SKOS IRI。这是预期行为；特此说明，以免有人对中间输出感到担忧。

MCP 服务

sdccdif 也是 MCP 服务，注册名为 io.github.SemanticDataCharter/sdccdif，因此，能够使用 sdcreader 读取已发布模型的助手可以请求其 CDIF 描述。它提供一个工具 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）：记录树、叶节点、带代码的枚举值，以及模型的 Dublin Core 元数据（SDCStudio 的默认值视为未设置）。包格式仅在此处说明一次。
• src/sdccdif/：cdif.py（JSON-LD）、cli.py、data/sdc4-exceptional-values.json（从 SDC4 参考模型 Schema 中提取的 16 个例外值）。
• data/cdif-129085c/：CDIF 的上下文、框架、JSON Schema、SHACL、一致性映射和验证器。 data/mbb-61f24aa/：cdifCodelist 构建块，以及检测器据此判断的三条逐类规则。
• samples/nhanes-participant/：获取的模型包及据此生成的文档。
• build/snapshot_cdif.py：从固定提交版本的 CDIF 仓库只读克隆重新生成 data/。

许可证

Apache-2.0（参见 LICENSE、NOTICE）。data/ 中的 CDIF 产物保留各自的许可证：validation 仓库采用 CC0；构建模块采用 CC BY 4.0、CODATA 和跨领域互操作框架的许可证。