sdcgovernance

sdcgovernance

Semantic Data Charter インスタンス向けの、W3C 標準に準拠したガバナンス助言エンジンです。

SDC データモデルで定義されたガバナンスコンポーネントに照らして、XML データインスタンスのガバナンス内容を検証する Python ライブラリです。モデルでガバナンス（ワークフロー、証明、当事者／役割、来歴、監査）が定義されている場合、インスタンスにはその内容が含まれている必要があり、このライブラリがそれを検証します。

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 になります。適用すべきガバナンスがないためです。

独立した 2 つのライブラリ

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.

両方のライブラリは、インスタンスからスキーマを読み取ります。エージェントはワークフロー内の異なる時点で、それぞれを個別に、運用ロジックに必要な順序で呼び出します。1 つのワークフローで両方のライブラリを複数回呼び出すこともあります。

検証対象

コンポーネント	モデルで定義される内容	インスタンスに必要な内容
ワークフロー	有効なパスのクラスターツリー（XdOrdinal 状態を持つサブクラスター）	現在の XdOrdinal 状態。有効なパスにおける序数の隣接関係に照らして検証された、提案される遷移
証明	アクションごとの機関要件	正しい役割、当事者参照、タイムスタンプを含む証明
当事者／役割	ガバナンス対象のアクションに対する役割の制約	必要な役割を持つ、実行当事者の識別情報
来歴／監査	来歴要件（PROV-O）＋保持ポリシー（DPV）	保持ポリシーに従った PROV 形式の記録：最新の記録＋ハッシュ、直近 N 件、または完全なチェーン

ガバナンスコンポーネントは、CUID2 の識別情報ではなく、DMType ルート内の位置（固定 RM スロット：ワークフロー、証明、当事者／役割、監査など）によって検出されます。スロットが見つかると、その内容は関連する標準（PROV-O、SCXML、VC、DPV）に対する語彙のバインディングによって検証されます。適切なスロットにあり、適切な語彙にバインドされたコンポーネントであれば、Default プロジェクト由来か、独自に構築されたものかを問わず認識されます。

適用判定（OASIS XACML）

判定	意味
PERMIT	すべてのガバナンスチェックに合格しています。アクションは許可されています
DENY	1 つ以上のガバナンスチェックに失敗しています。アクションは拒否されます
INDETERMINATE	ガバナンスチェックに一部だけ合格しています。レビューが必要です（設定可能）

すべての判定について、W3C PROV レコードと SHA-256 ハッシュチェーン付きのレシートが生成されます。

判定後の対応は、エージェントの責任です。sdcgovernance は判定とレシートを発行します。ルーティング、エスカレーション、通知、停止などの運用上の対応は、実装ごとに異なる顧客側のビジネスロジックです。

2 つのインターフェース、1 つのエンジン

Python API — 直接統合する場合：

from sdcgovernance import validate_governance

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

MCP サーバー — 任意のエージェントフレームワークで利用する場合：

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 サーバーは、エージェントが呼び出すツールとしてガバナンス機能を公開します。ループを実行するのはエージェントです。sdcgovernance は助言を行います。

標準

• OASIS XACML - 判定の意味論（PERMIT/DENY/INDETERMINATE）
• SDC ネイティブ構造 + W3C SCXML の概念 - サブクラスターパス内の XdOrdinal コンポーネントによるワークフローの順序付け。W3C SCXML で規定されているオートマトン理論の状態と遷移の概念を採用しています。
• W3C PROV（PROV-O、PROV-DM）- 来歴／監査記録（ガバナンスの 1 つの側面）
• 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 - 独立した構造検証ライブラリです。エージェントはワークフローの異なる段階で、sdcgovernance とは別にこれを呼び出します。
• SDCStudio - ガバナンスコンポーネントを視覚的にモデル化します。XSD 出力には、sdcgovernance が検証するガバナンス定義が含まれます。
• AppGen - 生成されたアプリケーションは、データ入力の境界で validate_governance() を呼び出せます。
• SDC Agents - Default プロジェクトのガバナンスモデルを使用して、ガバナンス MCP ツールをエージェント型ワークフローに組み込む方法を示すリファレンス実装です。顧客のエージェントは同じ MCP サーバーに接続し、任意の方法でツールを使用します。

ステータス

本番環境で使用できる状態です。PyPI で Apache 2.0 ライセンスのもと公開されています。

依存関係

• rdflib - RDF／PROV レコードの生成
• pyshacl - SHACL 制約の検証

ライセンス

Apache 2.0