sdchealthdcatap

sdc_healthdcat_ap

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

sdchealthdcatap 读取已发布 SDC 模型的程序包，并编写 dcat:Dataset 描述。HealthDCAT-AP 是 DCAT-AP 的健康领域扩展，面向欧洲健康数据空间中的健康数据二次使用，它要求数据持有方将该描述发布到 HealthData@EU 目录中：每个模型对应一个 Dataset，并注明访问级别；模型的变量作为 CSVW 表组，从记录的叶节点构建；模型绑定的编码系统；以及根据明确声明的输入提供的数据持有方信息。输出为一个 rdflib 图，序列化为 Turtle 和 JSON-LD。随后使用 HealthData@EU 验证器针对该级别的自有形状集进行检查，所用版本固定于规范仓库的指定提交。

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

示例 samples/nhanes-participant/catalog.ttl（以及 catalog.jsonld，即相同的图）是一个访问级别为 NON_PUBLIC 的 Dataset，不带目录包装，正如该版本自身的示例所示（第 4 部分解释了原因）：数据来自 FAIR Data Demo 中 NHANES Participant（dm-xy8upneajsb8vdcmnve01g6g）的记录。这是美国国家健康与营养调查（CDC）的人口统计、检查和实验室记录，共有 9,254 条记录，每位参与者一条。该模型是公开的：

• 目录记录：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]"
sdchealthdcatap write --package samples/nhanes-participant --out catalog.ttl --jsonld catalog.jsonld
sdchealthdcatap write --ct-id xy8upneajsb8vdcmnve01g6g --save-package pkg/ --out catalog.ttl     # any published model, from the public catalog
sdchealthdcatap write --package DIR --catalog my-catalog.yaml --out catalog.ttl                  # a data holder's own declared input

两类输入，彼此分开。 模型程序包提供的内容（其 JSON-LD、架构、公开目录记录和已发布的架构版本；无需账户；没有程序包的模型将被拒绝）：标题、描述、标识符、创建者、日期、许可证、架构 URL 和 SHA-256、记录的每个叶节点（用于变量）、模型绑定的每个概念系统（用于编码系统），以及模型设计者填写的模型自身 Dublin Core 信息。数据持有方提供的内容在 catalog.yaml 中声明，因为该配置文件要求提供只有持有方才掌握的信息，以及来自 DG SANTE 和 EU 词汇表的值：访问级别、健康数据访问机构、适用法规、健康类别和主题、数据集类型、作为访问途径的分发项、记录数和个人数、典型年龄、人口覆盖范围、个人数据类别、法律依据、目的、发布者类型和联系点。程序包附带示例文件（src/sdchealthdcatap/data/catalog.yaml）；持有方需提供自己的文件。

数据字典在此处作为一个插槽。 healthdcatap:hasVariables 接收一个 csvw:TableGroup；编写器会为记录的每个叶节点构建一个表格列，对 NHANES Participant 共构建 153 列：csvw:name 是该叶节点在记录中的路径，csvw:title 是其标签，csvw:datatype 是其 XSD 类型，dct:description 是其定义，csvw:propertyUrl 是其库插槽（用于标识变量含义，并在重复使用时保持一致），dct:identifier 是其元素名称。healthdcatap:hasStructuredData 的值为 true。healthdcatap:hasCodingSystem 包含来自 Coding System NAL 的 SNOMED CT、LOINC 和 NCIT，这些信息根据 IRI 前缀，从模型的 skos:exactMatch 绑定中推导得出。

Dataset 还包含以下内容：

dct:title、dct:description、dct:identifier、adms:identifier、dcat:keyword、dcat:landingPage、dct:issued、dct:modified、dct:language、dct:license、dct:provenance、dcat:version	与 DCAT-AP 编写器一致，取自软件包
dct:accessRights	来自 Access Rights NAL 的 NON_PUBLIC（已声明；它决定验证器的形状集）
dcatap:applicableLegislation	EHDS Regulation 的 ELI：http://data.europa.eu/eli/reg/2025/327/oj，用于 Catalog、Dataset 和 Distribution（已声明）
healthdcatap:hdab、geodcatap:custodian	发布者，一个带有 cv:ContactPoint 且类型取自 Health Publisher Types NAL 的 foaf:Agent（已声明；见第 3 部分）
healthdcatap:healthCategory、healthdcatap:healthTheme、dct:type、dcat:theme	RQSH（研究队列、问卷和调查）、非传染性疾病、STATISTICAL、HEAL（已声明）
dcat:distribution	访问路径：标题、描述、dcat:accessURL、可用性、法规、许可，以及作为 dct:Standard、通过固定 URL 指定的 dct:conformsTo 模式
foaf:page	位于稳定 URL 的模式，描述为数据字典
healthdcatap:numberOfRecords、numberOfUniqueIndividuals、minTypicalAge、maxTypicalAge、populationCoverage	9,254；9,254；0；80；NHANES 人群（已声明）
dpv:hasPersonalData、dpv:hasLegalBasis、dpv:hasPurpose	来自 DPV 个人数据分类体系的年龄、性别和健康记录；依据和目的以文本表示（已声明）
dqv:hasQualityAnnotation	一个 dqv:QualityCertificate，其主体为模式：每条记录在创建前都会根据该模式进行验证

图中使用的每个 NAL 概念都声明了其方案（skos:inScheme），每个方案都有类型和标题，因为验证器的代码列表形状会以这种方式检查成员关系。每个 Agent 都有类型、名称和联系点。

2. 如何验证

测试会运行 HealthData@EU 验证器自己的配置，配置位于 data/healthdcat-ap-r8-cd7841f/validator/ （build/snapshot_healthdcat_ap.py 会先验证固定版本）：config.properties 按访问级别指定形状文件，测试会针对声明的级别准确加载这些文件，并加载该版本发布时附带的 SEMIC DCAT-AP 3.0.1 形状，以及代码列表形状所列的 13 个词汇表；验证器会将它们预加载为背景数据：

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

在固定版本的 NON_PUBLIC 级别下，以 Turtle 和 JSON-LD 格式运行的结果为：0 个违规，10 条警告。这些警告针对软件包未包含的建议属性（分析、保留期限、频率、Dataset 上的 dct:conformsTo、引用、关系、来源、时间覆盖范围和分辨率、样本）。已提交的样本经断言与全新运行结果同构。以相同方式在 PUBLIC 级别运行该版本自带的 ARCA 示例，除我们携带的背景数据不足之处外，均通过验证（见第 4 部分）。

第二个验证依据是 Interoperability Test Bed，规范的验证章节将其列为可“加载”形状文件和导入文件的地方：其通用 SHACL 验证器（https://www.itb.ec.europa.eu/shacl/any/upload，REST API /shacl/any/api/validate）将该版本的非公开形状文件作为外部规则；在 2026 年 10 月 9 日的验证结果中，文档的任何节点都没有违规，另有 14 条警告（上述 10 条，以及 distribution 上的 dct:format、dct:spatial，还有 creator agent 和许可文件上的 dct:type）。它另外报告的 22 个违规均出现在 Test Bed 自身提供的节点上：6 个没有标题的 ADMS 概念方案和 5 个没有名称的空白 Agent，各重复两次；空 catalog 在其 DCAT-AP 域中也会收到同样的结果。带网络标记的测试会断言第一部分；CI 会跳过该测试。无法访问 HealthData@EU 平台自己的验证器页面：生产平台和验收平台在验证器路径上都返回 404，且平台的公开页面没有链接到该页面。

3. 投影无法表达的内容

这些信息是声明的，而非从包中读取的，因此在此说明：

• 健康数据访问主体是发布方。 该字段在每个层级都是必填项，且没有任何欧盟机构持有此数据集。示例将 Axius SDC, Inc. 及其联系点列为授予访问权限的主体；这适用于 FAIR Data Demo。对于 EHDS 内的数据集，则应替换为实际主体。
• 适用法规是 EHDS Regulation，正如配置文件的使用说明所建议的那样；该法规并不管辖此数据集。这是配置文件规定的、用于表述“按照 EHDS 框架描述”的方式。
• 数量、年龄、人口、个人数据类别、法律依据和用途，是持有方对 FAIR Data Demo 生成过程和 NHANES 来源的陈述，并非此包所包含的事实。
• 分发项是获取途径，而非文件。 这些记录并未发布；访问途径是联系页面。持有方若提供下载或数据服务，则应以此替换。

未纳入的内容：保留期限、分析分发项、样本分发项、频率、时间覆盖范围、关联关系。此包未包含这些信息，而配置文件只是建议提供，并非要求提供。

反过来说，记录包含而目录条目仅指向的内容有：

• 治理封套是每条记录中的数据，包括审计事件、PROV 活动和 PROV Agent，并与其余内容一同通过验证。表格组中设有对应的列，因此读者可以看到这些内容确实存在；具体值则位于记录中。
• 架构绑定到每条记录，并在此处的分发项和页面上通过 URL 和 SHA-256 引用。
• 值缺失的原因在记录中以类型标注。 表格组的说明指出，每列都可能带有十六种特殊值之一；具体适用哪一种以及出现的位置，记录中均有注明。

4. 我们从 HealthDCAT-AP Release 8 及其验证器中学到的内容

在 2026 年 10 月 9 日基于 healthdataeu/healthdcat-ap 的 cd7841f 构建时，实施者记录的笔记。这些笔记描述了各项产物的行为，帮助下一位实施者把时间花在自己的目录上，而不是研究这些产物。

• 文档是数据集（Dataset），而非目录（Catalogue）。 此版本中的示例仅涉及数据集，原因在验证时显现：加载 DCAT 作为背景知识后（dcat:Catalog 是 dcat:Dataset 的子类），验证器会将 dcat:Catalog 节点视为数据集，并要求其满足数据集的强制清单；仅包装节点就有十一项违规（联系点、分发、关键词、主题、访问权限、标识符、来源、类型、健康类别、访问主体、结构化数据标记）。编写器不会生成目录；HealthData@EU 目录才是目录。
• 此版本附带已配置好的验证器。 html/shacl/HealthDCAT-AP_validator/config/rdf-validator/ehds/ 中包含 config.properties，用于指定各访问级别对应的形状文件，以及验证器预加载的词汇表和本体。使用 pySHACL 加载这组文件运行，就是在运行验证器的逻辑；托管实例还会添加背景知识和 Web 界面。
• 通过 skos:inScheme 检查是否属于某个词汇表。 每项代码列表限制都会要求概念具有 skos:inScheme <the scheme>；其中几项还会要求该 scheme 是类型为 skos:ConceptScheme 的资源；随后，SEMIC 的基础形状会要求图中的每个 scheme 都有 dct:title。托管验证器会预加载词汇表，提供 inScheme；离线运行时，则需要加载词汇表或显式声明。编写器会为其使用的每个概念都显式声明，因此测试也会加载全部十三个词汇表。这就是此版本的 ARCA 示例离线验证通过的原因，语言除外（Languages NAL 大小为 14 MB，因此不会加载），许可类型也除外（预加载项中没有 ADMS scheme）。
• 数据集上的 dct:conformsTo 仅接受技术标准 NAL（FHIR、OMOP-CDM、openEHR、DICOM、CDISC SDTM 等约二十种），违规级别。不能在此处填写自定义 schema；编写器会在分发和 foaf:page 上引用它，因为这些位置没有此类限制。
• 健康数据发布者是一个 Agent，且必须恰好有一个 cv:ContactPoint（使用核心公共服务词汇表，而非 vCard），其类型须来自 Health Publisher Types NAL；数据集的联系点则是一个带电子邮件或 URL 的 vcard:Kind。同一文档中使用两种联系点词汇表，分别用于对应形状要求的位置。
• 编码系统除了是概念，还必须是 dct:Standard。 范围形状要求 healthdcatap:hasCodingSystem 的值为 dct:Standard；代码列表形状则要求其具有 skos:inScheme，且该 scheme 为 Coding System NAL。两者都必须满足。
• 三个没有路径的属性形状（vcard:Kind 的“电子邮件或 URL”、cv:ContactPoint 的“电子邮件或页面”，均以不含 sh:path 的 sh:or 编写）会导致 pySHACL 停止运行；测试会移除它们并手动断言两项规则。范围文件引用了自身未定义的属性形状，DCAT-AP 的范围文件也如此。
• pySHACL 会报告嵌套结果。 sh:node 验证失败时，会产生一个严重级别与属性一致的外层结果，并将内层结果放在 sh:detail 下，各自保留原有严重级别；基于 Jena 的验证器只报告外层结果。测试会将嵌套结果合并到其父级，因此目录发布者的警告仍为警告。
• 目录的发布者会根据两种词汇表检查两次。 DCAT-AP 的代码列表形状要求目录发布者的类型来自 ADMS publisher-type scheme（警告）；HealthDCAT-AP 则要求数据集发布者的类型来自 Health Publisher Types NAL（违规）。同一个 Agent 同时担任两种角色，可满足第二项要求，但会触发第一项警告。
• 此版本的示例和形状将 csvw:column 用作普通的重复属性，而非 CSVW 规范定义的 rdf:List；表格中的列名必须唯一，因此，一个组件（血压读数）组合三次时，会生成三个以路径命名的列。
• Release 8 的 CHANGELOG.md 和根目录下的 shacl/ 属于 DCAT-AP 3.0.1，未作更改；HealthDCAT-AP 形状仅位于验证器配置路径下。

MCP 服务

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

uvx sdchealthdcatap mcp            # or: sdchealthdcatap-mcp, or sdchealthdcatap mcp

目录结构

• 使用 sdcreader 读取模型的软件包（load_package、 fetch_package、read_model）：记录树、其叶节点、带代码的枚举值，以及模型的 Dublin Core（未设置的 SDCStudio 默认值）。软件包格式在该处有一次性文档说明。
• src/sdchealthdcatap/：dcatap.py（DCAT-AP 图构建器，复用自 sdc_dcat3_ap）、healthdcatap.py（健康层和表格组）、validate.py（使用 pySHACL 的验证器形状集）、cli.py、data/catalog.yaml （示例的指定输入）。
• data/healthdcat-ap-r8-cd7841f/：该版本的形状、上下文、验证器配置，以及形状中指定的词汇表和示例，均固定在指定提交。
• samples/nhanes-participant/：获取的模型软件包，以及由此生成的目录，格式为 Turtle 和 JSON-LD。
• build/snapshot_healthdcat_ap.py：从固定提交处的只读克隆重新生成 data/。

许可证

Apache-2.0（参见 LICENSE、NOTICE）。data/ 中的 HealthDCAT-AP 工件采用 CC BY 4.0 许可，并在此保留该许可。