sdcreader

sdcreader

读取已发布的 Semantic Data Charter 模型包，以便投影到其他标准。

投影使用另一种标准的术语来描述模型所治理的数据记录：CDIF、DCAT-US 3.0、DCAT-AP 3.0.1、HealthDCAT-AP，以及未来出现的标准。每种投影描述的都是相同的证据——模型包，并将其读取为相同的结构。sdcreader 将这份证据读取为这种结构，只实现一次，不包含任何投影相关内容。在此包发布之前，四个投影编写器（sdc_cdif、sdc_dcat3_us、sdc_dcat3_ap、sdc_healthdcat_ap）都各自保留着相同的副本。

pip install sdcreader            # the reader, with HTTP for fetching from the public catalog (since 4.1.0 no extra is needed)

from sdcreader import fetch_package, load_package, read_model

pkg = load_package("samples/nhanes-participant")          # a package on disk
pkg = fetch_package("xy8upneajsb8vdcmnve01g6g", save_to="pkg/")   # or from SDCStudio's public catalog, no account
model = read_model(pkg)

pkg.schema_url_pinned        # https://sdcstudio.axius-sdc.com/dmlib/dm-xy8u...xsd?sha256=0df4...   the exact bytes the records are validated against
model.title, model.leaves    # 'NHANES Participant', 153 leaves in document order, each with its path of clusters
model.codes[ct_id]           # the enumerated values of a component with the IRI, definition and code the schema annotates them with
model.dc("publisher")        # what the modeler wrote, None where SDCStudio's default sits

什么是模型包

SDCStudio 会为每个已发布模型生成一个模型包，并向公共项目中的模型公开提供：

GET /api/v1/catalog/dm/<ct>/	目录记录：标题、描述、项目、构件列表（catalog.json）
GET /api/v1/catalog/dm/<ct>/<artifact>/	存储指针，{"download_url": ..., "filename": ..., "storage": "gcs"}，适用于 jsonld、xsd 等；读取器会跟随此指针
dm-<ct>.jsonld	模型及其组件：类型、标签、描述、基数、约束（枚举、单位、范围、模式）、语义链接（dcterms:identifier 库槽位、dcterms:source、dcterms:publisher、skos:exactMatch、rdfs:seeAlso、prov:wasRevisionOf）、contains
GET /dmlib/dm-<ct>.xsd	Schema 字节：模型的 Dublin Core 头信息，以及每个枚举值的定义和定义该值的代码（dm-<ct>.xsd）
GET /dmlib/dm-<ct>.versions.json	Schema 按 SHA-256 标识的所有已发布版本，以及当前版本（versions.json）

模型包目录包含这四个文件。若目录中缺少 JSON-LD 或 Schema、JSON-LD 的标识符与目录中的模型不符，或 Schema 字节不是当前已发布版本，读取器就会拒绝该目录：投影会通过 URL 和 SHA-256 引用 Schema，因此字节必须与该 URL 提供的内容一致。

SDCStudio 的问题跟踪器中记录了模型包的两个缺陷：JSON-LD 元数据缺少 Schema 头信息中包含的字段（#748），且头信息省略了 dc:source（#749）。读取器从头信息中获取模型的 Dublin Core 元数据，该处信息完整。

读取器提供的内容

• ModelPackage：四个文件、SHA-256、Schema URL 及其固定版本形式（?sha256=）、公共目录 URL，以及 check()。
• Model：title、description、root（受治理记录的簇）、按标识符索引的 components、按文档顺序排列的 leaves（每项都是一个 Leaf，包含其 component、簇路径 path 和该路径的 slug，在记录中唯一）、codes（每个组件的枚举值，表示为 Code：值、IRI、定义、定义该值的代码）、metadata（JSON-LD 元数据）和 header（Schema 的 Dublin Core 元数据）。
• Model.dc(name)：模型作者填写的内容，优先取自头信息，其次取自 JSON-LD；SDCStudio 的字段默认值视为未设置："Universal" 表示 coverage，"None" 表示 relation，"SDC Data Model (DM)" 表示 type，以及空白值。投影绝不会将默认值作为事实发布。contributors、subjects（分号分隔的列表）、rights_url 和 rights_statement 均由此得出。
• Component：sdc_type、label、description、data_type、constraints、按谓词索引的 links（link(p) 返回第一个）、contains、iri。
• 常量：叶子、数值和量化类型；谓词 IRI IDENTIFIER、SOURCE、PUBLISHER、EXACT、CLOSE、SEE_ALSO、HAS_UNIT；DC_DEFAULTS。

MCP 服务

sdcreader 也是一个 MCP 服务，注册为 io.github.SemanticDataCharter/sdcreader，因此助手可以读取已发布的模型，就像 sdcvalidator、sdcgovernance 和 sdcreceipt 让它验证、治理和结算记录一样。 stdio、无 SDK、无账户、只读。

uvx sdcreader                    # or: sdcreader-mcp, or python -m sdcreader.mcp_server
uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's public catalog

工具	功能
find_models	按文本搜索公共目录，或按名称列出公共项目的模型
describe_model	单个模型：标题、项目、根记录、按类型统计的叶节点和组件数量、Dublin Core（将 SDCStudio 的默认值设为 null）、固定到其 SHA-256 的架构 URL
list_leaves	按文档顺序列出叶节点，包括路径、类型、约束、代码数量和身份链接，支持分页
list_codes	列出单个组件的枚举值，包括 IRI、定义和代码系统
check_package	检查包目录的完整性

每个工具都接受 ct_id（从启动服务时指定的主机获取）或磁盘上的包 directory。 没有工具接受 URL：主机在启动时固定，因此调用方无法将服务指向其他位置。每个工具都调用与库相同的函数；两种接口描述同一个模型的方式一致。

测试

pip install -e ".[dev]"
python -m pytest tests -q                    # includes one fetch against production
python -m pytest tests -q -m "not network"   # offline, as CI runs it

此测试夹具是 FAIR Data Demo 的 NHANES Participant 包，也是每种投影都经过验证的记录。

版本控制

开头的 4 表示 SDC4 参考模型，与每个 Semantic Data Charter 包的情况相同。读取器公开内容的新增功能会提升次版本号，修复会提升补丁版本号；只有参考模型发生变化时才会更改主版本号。

许可证

Apache-2.0（参见 LICENSE、NOTICE）。