Skip to main content
Glama
sdcgovernance

sdcgovernance

Official

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.

Related MCP server: ceco proof gate

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

Component

What the model defines

What the instance must carry

Workflow

Cluster tree of valid paths (sub-clusters with XdOrdinal states)

Current XdOrdinal state, proposed transition validated against ordinal adjacency in valid paths

Attestation

Authority requirements per action

Attestation with correct role, party reference, timestamp

Party/Role

Role constraints for governed actions

Acting party identification with required role

Provenance/Audit

Provenance requirements (PROV-O) + retention policy (DPV)

PROV-formatted record(s) per retention policy: most recent + hash, last N, or full chain

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)

Decision

Meaning

PERMIT

All governance checks pass - action is authorized

DENY

One or more governance checks fail - action is refused

INDETERMINATE

Governance checks partially pass - requires review (configurable)

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.

Also listed on mcprush.

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

Available Tools

9 tools
evaluate_decisionA

Evaluate a DMN decision table against instance context. Name the table by table_id (and table_version; the highest registered version when omitted) for a governed evaluation, or pass it inline as table_json for an ad-hoc one. Returns decision, matched_rules, reasoning, errors, the table's identity and content hash, and a tamper-evident Receipt whose receipt_hash covers table_id, table_version and table_hash as well as context_hash. instance_path is optional: when omitted, the decision is evaluated against extra_context alone, which is the path external context-only consumers (e.g. MTCP Evidence Packs) should use. Pass previous_hash to chain receipts; the caller is responsible for chain persistence.

Inputs: table_id, table_json, instance_id, context_hash, +5 more.

evaluate_transitionB

Evaluate whether a specific workflow transition is permitted. Returns PERMIT/DENY/INDETERMINATE with receipt.

Inputs: schema_path (required), target_state (required), instance_path (required), actor.

get_allowed_transitionsA

Get valid next states from the current workflow state. Returns list of valid transitions with target state info and path(s).

Inputs: schema_path (required), instance_path (required).

get_governance_statusB

Report which governance dimensions the model defines. Returns model_id, model_label, has_governance, and active dimensions.

Inputs: schema_path (required).

list_decision_tablesA

List the registered decision tables: table_id, version, table_hash, domain, policy and registered_at for each version, lowest version first. Filter by table_id or domain. With table_id the full table JSON of each version is included, which is how a receipt's table_id and table_version are resolved back to the rules that applied.

Inputs: domain, table_id.

record_provenanceC

Record a provenance event as a W3C PROV-O record. Returns the PROV record content.

Inputs: agent_name (required), activity_type (required), agent_ref, entity_id, +4 more.

register_decision_tableA

Register a decision table under a stable table_id and an immutable version, so evaluate_decision can name it and every Receipt it produces records which policy version applied. Returns table_id, version, table_hash (SHA-256 of the table's RFC 8785 canonical JSON), domain and policy. Registering the same content again under the same id and version is a no-op; different content under an existing id and version is refused: register it as a new version. Persists to the server's tables directory when one is configured.

Inputs: version (required), table_id (required), table_json (required), domain, +1 more.

validate_governanceB

Full governance validation of an instance against its model. Returns decision, has_governance, errors, dimensions_validated.

Inputs: schema_path (required), instance_path.

verify_evidence_packA

Verify the integrity of an MTCP Evidence Pack by recomputing its evidence_pack_hash. Returns valid (bool), computed_hash, and expected_hash. Canonicalization follows RFC 8785: keys sorted, no whitespace, comma-colon separators, UTF-8.

Inputs: evidence_pack (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool targets a distinct resource and action, but there are two close pairs: get_allowed_transitions vs evaluate_transition (enumerate vs decide) and get_governance_status vs validate_governance (report dimensions vs validate an instance). Descriptions do make the boundaries explicit, so misselection risk is low but non-zero.

    Naming Consistency5/5

    All nine tools follow a strict verb_noun snake_case pattern (evaluate_*, get_*, validate_*, record_*, register_*, list_*, verify_*). The repeated verbs are used semantically consistently, with no camelCase or bare-noun outliers.

    Tool Count5/5

    Nine tools is squarely in the well-scoped range and each maps to a concrete governance step: policy registration, policy lookup, decision evaluation, governance validation, transition discovery/authorization, provenance, and evidence verification. No filler or duplicate tools.

    Completeness4/5

    Core lifecycle is covered: register/list/evaluate decision tables, validate governance, inspect and evaluate transitions, verify evidence packs. Gaps remain around provenance (record only, no read/query tool), no evidence pack construction (verify only), and no deprecation/removal for registered tables, but these are workaroundable rather than blocking.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers