{
  "markdown": "# sdcgovernance\n\n<!-- mcp-name: io.github.SemanticDataCharter/sdcgovernance -->\n\nW3C standards-based governance advisory engine for Semantic Data Charter instances.\n\nA 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.\n\nReturns decisions using OASIS XACML semantics: PERMIT, DENY, or INDETERMINATE.\n\nNo framework dependency. No middleware. A function call.\n\n## How It Works\n\nSDC 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.\n\nWhen governance components are defined, every XML data instance must carry the corresponding governance content. This library validates that content against the model:\n\n```python\nfrom sdcgovernance import validate_governance\n\nresult = validate_governance(\"model.xsd\", \"instance.xml\")\n\nprint(result.decision)      # PERMIT, DENY, or INDETERMINATE\nprint(result.has_governance) # True if model defines governance components\nprint(result.errors)         # list of governance validation errors\nprint(result.receipt)        # tamper-evident decision receipt\n```\n\nIf the model does not define governance components, the result is `PERMIT` - no governance to enforce.\n\n## Two Independent Libraries\n\nsdcvalidator and sdcgovernance are separate, independent libraries. There is no hook, no chaining, no automatic invocation of one from the other.\n\n```\nsdcvalidator (structural validation)\n    Does the instance conform to the XSD schema?\n    Single-pass. Instance in, pass/fail out.\n\nsdcgovernance (governance advisory)\n    Does the model define governance components?\n    If yes: does the instance carry valid governance content?\n    Conversational. Agents query multiple times during a workflow.\n```\n\nBoth 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.\n\n## What Gets Validated\n\n| Component | What the model defines | What the instance must carry |\n|---|---|---|\n| **Workflow** | Cluster tree of valid paths (sub-clusters with XdOrdinal states) | Current XdOrdinal state, proposed transition validated against ordinal adjacency in valid paths |\n| **Attestation** | Authority requirements per action | Attestation with correct role, party reference, timestamp |\n| **Party/Role** | Role constraints for governed actions | Acting party identification with required role |\n| **Provenance/Audit** | Provenance requirements (PROV-O) + retention policy (DPV) | PROV-formatted record(s) per retention policy: most recent + hash, last N, or full chain |\n\nGovernance 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.\n\n## Enforcement Decisions (OASIS XACML)\n\n| Decision | Meaning |\n|---|---|\n| **PERMIT** | All governance checks pass - action is authorized |\n| **DENY** | One or more governance checks fail - action is refused |\n| **INDETERMINATE** | Governance checks partially pass - requires review (configurable) |\n\nEvery decision produces a W3C PROV record and a SHA-256 hash-chained receipt.\n\nWhat 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.\n\n## Two Interfaces, One Engine\n\n**Python API** - for direct integration:\n\n```python\nfrom sdcgovernance import validate_governance\n\nresult = validate_governance(\"model.xsd\", \"instance.xml\")\n```\n\n**MCP Server** - for any agent framework:\n\n```bash\nsdcgovernance serve --mcp\n```\n\nThe MCP server exposes governance as tools that agents call. The agent runs the loop. sdcgovernance advises.\n\n## Standards\n\n- **OASIS XACML** - decision semantics (PERMIT/DENY/INDETERMINATE)\n- **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\n- **W3C PROV** (PROV-O, PROV-DM) - provenance/audit records (one governance dimension)\n- **W3C Data Privacy Vocabulary (DPV)** - provenance retention policy (same vocabulary used for SDC access control)\n- **W3C Activity Streams 2.0** - activity/event type vocabulary\n- **W3C Verifiable Credentials Data Model 2.0** - attestation authority pattern\n- **W3C SHACL** - cross-entity constraint validation\n- **OMG DMN** - decision tables for complex governance rules\n- **SHA-256** - tamper-evident hash chains for decision receipts\n\n## Architecture\n\n```\nsrc/sdcgovernance/\n├── __init__.py          # Public API: validate_governance()\n├── engine.py            # GovernanceEngine - the decision engine agents query\n├── model_inspector.py   # Inspect SDC model for governance components\n├── workflow.py          # Validate workflow transitions in instance\n├── attestation.py       # Validate attestation content in instance\n├── party_role.py        # Validate party/role constraints in instance\n├── provenance.py        # Validate provenance/audit records + PROV generation + DPV retention policy\n├── decision.py          # DMN decision table evaluation\n├── receipts.py          # Decision receipt chain (hash-chained)\n├── shacl_runtime.py     # SHACL cross-entity constraint validation\n└── mcp_server.py        # MCP server exposing governance tools to any agent\n```\n\nPure Python. No Django. No middleware. No web framework dependency.\n\n## Installation\n\n```bash\npip install sdcgovernance\n```\n\n## Integration with SDC Ecosystem\n\n- **sdcvalidator** - independent structural validation library. Agents call it separately from sdcgovernance, at different points in a workflow.\n- **SDCStudio** - models governance components visually. The XSD output includes governance definitions that sdcgovernance validates against.\n- **AppGen** - generated applications can call `validate_governance()` at data entry boundaries.\n- **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.\n\n## Status\n\nProduction-ready. Available on [PyPI](https://pypi.org/project/sdcgovernance/) under Apache 2.0.\n\n## Dependencies\n\n- `rdflib` - RDF/PROV record generation\n- `pyshacl` - SHACL constraint validation\n\n## License\n\nApache 2.0\n",
  "bytes": 7133,
  "sha": "28546ba7e1e65407a90110c4b9d87212bec0da1bf11d0f47853edb567271137c",
  "repo_slug": "semanticdatacharter/sdcgovernance",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_semanticdatacharter_sdcgoverna_891b4816/readme"
}