io.github.SemanticDataCharter/sdcgovernance

sdcgovernance

W3C standards-based governance advisory engine for Semantic Data Charter instances.

A Python library that validates governance content in XML data instances against governance components defined in the SDC data model. If the model defines governance (workflow, attestation, party/role, provenance, audit), the instance must carry that content - and this library validates it.

Returns decisions using OASIS XACML semantics: PERMIT, DENY, or INDETERMINATE.

No framework dependency. No middleware. A function call.

How It Works

SDC data models (XSD) can optionally include governance components: Workflow state machines, Attestation authority requirements, Party/Role constraints, Provenance requirements, and Audit definitions. These are part of the data model, not a separate governance layer.

When governance components are defined, every XML data instance must carry the corresponding governance content. This library validates that content against the model:

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

If the model does not define governance components, the result is PERMIT - no governance to enforce.

Two Independent Libraries

sdcvalidator and sdcgovernance are separate, independent libraries. There is no hook, no chaining, no automatic invocation of one from the other.

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.

Both libraries read the schema from the instance. Agents call each one independently, at different points in a workflow, in whatever order the operational logic requires. A single workflow may involve multiple calls to both libraries.

What Gets Validated

Governance components are discovered by their position in the DMType root (fixed RM slots: workflow, attestation, party/role, audit, and related), not by CUID2 identity. Once a slot is found, its content is validated by vocabulary binding against the relevant standard (PROV-O, SCXML, VC, DPV). Any component occupying the right slot and bound to the right vocabulary is recognized - whether it comes from the Default project or was custom-built.

Enforcement Decisions (OASIS XACML)

Every decision produces a W3C PROV record and a SHA-256 hash-chained receipt.

What happens after the decision is the agent's responsibility. sdcgovernance issues the decision and the receipt. The operational response - routing, escalation, notification, halting - is customer business logic that varies per implementation.

Two Interfaces, One Engine

Python API - for direct integration:

from sdcgovernance import validate_governance

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

MCP Server - for any agent framework:

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

A client configuration needs only "command": "uvx", "args": ["sdcgovernance"].

The MCP server exposes governance as tools that agents call. The agent runs the loop. sdcgovernance advises.

Standards

• OASIS XACML - decision semantics (PERMIT/DENY/INDETERMINATE)
• SDC native structure + W3C SCXML concepts - workflow sequencing via XdOrdinal components in sub-cluster paths, borrowing the concepts of state and transition from automata theory as specified in W3C SCXML
• W3C PROV (PROV-O, PROV-DM) - provenance/audit records (one governance dimension)
• W3C Data Privacy Vocabulary (DPV) - provenance retention policy (same vocabulary used for SDC access control)
• W3C Activity Streams 2.0 - activity/event type vocabulary
• W3C Verifiable Credentials Data Model 2.0 - attestation authority pattern
• W3C SHACL - cross-entity constraint validation
• OMG DMN - decision tables for complex governance rules
• SHA-256 - tamper-evident hash chains for decision receipts

Architecture

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

Pure Python. No Django. No middleware. No web framework dependency.

Installation

pip install sdcgovernance

Integration with SDC Ecosystem

• sdcvalidator - independent structural validation library. Agents call it separately from sdcgovernance, at different points in a workflow.
• SDCStudio - models governance components visually. The XSD output includes governance definitions that sdcgovernance validates against.
• AppGen - generated applications can call validate_governance() at data entry boundaries.
• SDC Agents - reference implementations showing how to wire governance MCP tools into agentic workflows using Default project governance models. Customer agents connect to the same MCP server and use the tools however they want.

Status

Production-ready. Available on PyPI under Apache 2.0.

Dependencies

• rdflib - RDF/PROV record generation
• pyshacl - SHACL constraint validation

License

Apache 2.0