sdcgovernance

sdcgovernance

基于 W3C 标准的治理咨询引擎，适用于 Semantic Data Charter 实例。

一个 Python 库，用于根据 SDC 数据模型中定义的治理组件，验证 XML 数据实例中的治理内容。如果模型定义了治理内容（工作流、证明、参与方/角色、来源、审计），实例就必须携带这些内容，而此库会对其进行验证。

根据 OASIS XACML 语义返回决策：PERMIT、DENY 或 INDETERMINATE。

无框架依赖。无中间件。只需调用函数。

工作原理

SDC 数据模型（XSD）可以选择包含治理组件：工作流状态机、证明授权要求、参与方/角色约束、来源要求和审计定义。这些都是数据模型的一部分，而不是独立的治理层。

定义了治理组件后，每个 XML 数据实例都必须携带相应的治理内容。此库会根据模型验证这些内容：

from sdcgovernance import validate_governance

result = validate_governance("model.xsd", "instance.xml")

print(result.decision)      # PERMIT, DENY, or INDETERMINATE
print(result.has_governance) # True if model defines governance components
print(result.errors)         # list of governance validation errors
print(result.receipt)        # tamper-evident decision receipt

如果模型未定义治理组件，结果为 PERMIT——无需执行治理。

两个独立的库

sdcvalidator 和 sdcgovernance 是两个独立的库。它们之间没有钩子、没有串联，也不会自动相互调用。

sdcvalidator (structural validation)
    Does the instance conform to the XSD schema?
    Single-pass. Instance in, pass/fail out.

sdcgovernance (governance advisory)
    Does the model define governance components?
    If yes: does the instance carry valid governance content?
    Conversational. Agents query multiple times during a workflow.

两个库都会从实例中读取架构。Agent 会在工作流的不同环节独立调用各个库，顺序由操作逻辑决定。一个工作流可能会多次调用这两个库。

验证内容

组件	模型定义的内容	实例必须携带的内容
工作流	有效路径的集群树（包含 XdOrdinal 状态的子集群）	当前 XdOrdinal 状态；根据有效路径中的序数邻接关系验证拟议的状态转换
证明	每项操作的授权要求	角色正确、参与方引用正确且带有时间戳的证明
参与方/角色	受治理操作的角色约束	执行方身份标识及所需角色
来源/审计	来源要求（PROV-O）+ 保留策略（DPV）	按保留策略生成的 PROV 格式记录：最新记录 + 哈希、最近 N 条记录，或完整链

治理组件根据其在 DMType 根节点中的位置（固定的 RM 槽位：工作流、证明、参与方/角色、审计等）发现，而不是根据 CUID2 身份发现。找到槽位后，会通过与相关标准（PROV-O、SCXML、VC、DPV）的词汇表绑定来验证其内容。任何占据正确槽位且绑定到正确词汇表的组件都会被识别，无论它来自 Default 项目还是自定义构建。

执行决策（OASIS XACML）

决策	含义
PERMIT	所有治理检查均通过——操作已获授权
DENY	一项或多项治理检查未通过——拒绝操作
INDETERMINATE	部分治理检查通过——需要审核（可配置）

每项决策都会生成一条 W3C PROV 记录和一份通过 SHA-256 哈希链保护的收据。

决策之后的处理由 Agent 负责。sdcgovernance 会给出决策和收据。后续操作——路由、升级、通知、停止——属于客户业务逻辑，因实现方式而异。

两种接口，一个引擎

Python API——用于直接集成：

from sdcgovernance import validate_governance

result = validate_governance("model.xsd", "instance.xml")

MCP Server——适用于任何 Agent 框架：

sdcgovernance            # what an MCP registry client runs (uvx sdcgovernance)
sdcgovernance mcp        # the same, spelled like the other Semantic Data Charter servers
sdcgovernance serve --mcp   # still works for existing client configurations

客户端配置只需 "command": "uvx", "args": ["sdcgovernance"]。

MCP Server 将治理功能作为工具提供，供 Agent 调用。循环由 Agent 执行。sdcgovernance 提供建议。

标准

• OASIS XACML - 决策语义（PERMIT/DENY/INDETERMINATE）
• SDC 原生结构 + W3C SCXML 概念 - 通过子集群路径中的 XdOrdinal 组件对工作流进行排序，借鉴自动机理论中的状态和转换概念，这些概念由 W3C SCXML 规范定义
• W3C PROV（PROV-O、PROV-DM）- 来源记录/审计记录（一个治理维度）
• W3C Data Privacy Vocabulary (DPV) - 来源保留策略（与 SDC 访问控制使用相同的词汇表）
• W3C Activity Streams 2.0 - 活动/事件类型词汇表
• W3C Verifiable Credentials Data Model 2.0 - 证明权威模式
• W3C SHACL - 跨实体约束验证
• OMG DMN - 复杂治理规则的决策表
• SHA-256 - 防篡改的决策收据哈希链

架构

src/sdcgovernance/
├── __init__.py          # Public API: validate_governance()
├── engine.py            # GovernanceEngine - the decision engine agents query
├── model_inspector.py   # Inspect SDC model for governance components
├── workflow.py          # Validate workflow transitions in instance
├── attestation.py       # Validate attestation content in instance
├── party_role.py        # Validate party/role constraints in instance
├── provenance.py        # Validate provenance/audit records + PROV generation + DPV retention policy
├── decision.py          # DMN decision table evaluation + content hash
├── tables.py            # Decision table registry: id, version, hash; files on disk
├── receipts.py          # Decision receipt chain (hash-chained)
├── shacl_runtime.py     # SHACL cross-entity constraint validation
└── mcp_server.py        # MCP server exposing governance tools to any agent

纯 Python。无 Django。无中间件。无 Web 框架依赖。

安装

pip install sdcgovernance

与 SDC 生态系统的集成

• sdcvalidator - 独立的结构验证库。Agent 在工作流的不同阶段单独调用它，而不是通过 sdcgovernance 调用。
• SDCStudio - 以可视化方式建模治理组件。XSD 输出包含 sdcgovernance 会验证的治理定义。
• AppGen - 生成的应用可以在数据录入边界调用 validate_governance()。
• SDC Agents - 展示如何使用 Default 项目治理模型，将治理 MCP 工具接入 Agent 工作流的参考实现。客户的 Agent 连接到同一个 MCP 服务，并可按需使用这些工具。

状态

已可用于生产环境。在 PyPI 上以 Apache 2.0 许可发布。

依赖项

• rdflib - RDF/PROV 记录生成
• pyshacl - SHACL 约束验证

许可证

Apache 2.0