DOCS
Schemas you can integrate without bespoke parsers.
Governance events as structured records — built for replay, diffing, and long-horizon audit.
GovernanceEvent v1.0 Specification
Status: Draft
Version: 1.0.0
Last Updated: 2026-02-09
Authors: ZAK Platform
---
Abstract
This specification defines a standard format for governance events emitted by institutional systems (version control, issue tracking, identity providers, cloud platforms, incident management, etc.) to enable constitutional evaluation and audit by governance infrastructure.
GovernanceEvent is a normative, platform-agnostic schema for representing state changes, authority changes, artifact changes, and signals that may require governance response.
---
1. Introduction
1.1 Purpose
Organizations rely on multiple authority systems:
Each system emits events. Few systems can evaluate those events constitutionally.
GovernanceEvent provides a universal schema that:
1.2 Design Principles
1.3 Non-Goals
This specification does not:
---
2. Event Schema
2.1 Core Structure
`` {
"spec_version": "1.0.0",
"event_id": "uuid-or-platform-id",
"event_type": "state_change | authority_change | artifact_change | signal",
"authority_source": "github | gitlab | jira | aws | okta | ...",
"occurred_at": "2026-02-09T12:34:56.789Z",
"subject": {
"kind": "repo | branch | ticket | workflow | identity | environment | ...",
"id": "platform-specific-id",
"name": "human-readable-name",
"metadata": { /* optional, platform-specific */ }
},
"event": {
"name": "repository.created | push | role.granted | ...",
"severity": "low | med | high | critical",
"description": "Human-readable summary"
},
"provenance": {
"issuer": "platform-or-system-name",
"signature": "optional-cryptographic-signature",
"issued_at": "2026-02-09T12:34:56.789Z"
},
"payload": {
/* Opaque, platform-specific data */
/* ZAK stores but does not interpret */
/* Constitutions may reference fields */
}
}
json
`
2.2 Field Definitions
spec_version (required)
)event_id (required)
event_type (required)
- state_change - - - — Something moved from A → B
authority_change — Who is allowed/trusted changed
artifact_change — A versioned thing changed
signal — The system is telling you something important
authority_source (required)
, gitlab, jira, servicenow, aws, okta, pagerdutyoccurred_at (required)
subject (required)
- kind - - - (required) — Type of subject (e.g., repo, branch, ticket, identity)
id (required) — Platform-specific identifier
name (optional) — Human-readable name
metadata (optional) — Additional platform-specific context
event (required)
- name - - (required) — Event name (e.g., repository.created, push, role.granted)
severity (optional) — low, med, high, critical
description (optional) — Human-readable summary
provenance (required)
- issuer - - (required) — Who/what emitted this event
signature (optional) — Cryptographic signature (format TBD)
issued_at (required) — When the event was issued (may differ from occurred_at)
payload (optional)
---
3. Event Types
3.1 State Change
Definition: Something moved from state A → state B.
Examples:
Characteristics:
Example:
` {
"event_type": "state_change",
"authority_source": "github",
"subject": {
"kind": "repo",
"id": "12345",
"name": "acme-corp/api-gateway"
},
"event": {
"name": "repository.created",
"severity": "low",
"description": "New repository created"
}
}
json
`
---
3.2 Authority Change
Definition: Who is allowed or trusted changed.
Examples:
Characteristics:
Example:
` {
"event_type": "authority_change",
"authority_source": "okta",
"subject": {
"kind": "identity",
"id": "user-789",
"name": "alice@acme.com"
},
"event": {
"name": "role.granted",
"severity": "med",
"description": "Admin role granted to user"
}
}
json
`
---
3.3 Artifact Change
Definition: A versioned thing changed.
Examples:
Characteristics:
Example:
` {
"event_type": "artifact_change",
"authority_source": "github",
"subject": {
"kind": "branch",
"id": "refs/heads/main",
"name": "main"
},
"event": {
"name": "push",
"severity": "med",
"description": "Push to protected branch"
}
}
json
`
---
3.4 Signal
Definition: The system is telling you something important.
Examples:
Characteristics:
Example:
` {
"event_type": "signal",
"authority_source": "pagerduty",
"subject": {
"kind": "incident",
"id": "INC-001",
"name": "API Gateway Down"
},
"event": {
"name": "incident.triggered",
"severity": "critical",
"description": "SEV-1 incident triggered"
}
}
json
`
---
4. Severity Levels
| Level | Meaning | Examples |
|-------|---------|----------|
| low | | | | Routine, informational | Repo created, ticket opened |
med | Operationally relevant | Production push, role granted |
high | Risk signal | Security workflow disabled, secret exposed |
critical | Immediate attention | SEV-1 incident, data breach |
Note: Severity is advisory. Constitutional evaluation determines actual response.
---
5. Immutability and Replay
5.1 Immutability Requirements
GovernanceEvents must be:
and issued_at preserved for verification5.2 Replay Semantics
A governance system consuming GovernanceEvents must:
), authority_source, occurred_at---
6. Platform-Specific Mappings
6.1 GitHub
| GitHub Event | GovernanceEvent Type | Subject Kind | Event Name |
|--------------|---------------------|--------------|------------|
| repository | | | | | state_change | repo | repository.created |
push | artifact_change | branch | push |
pull_request.opened | artifact_change | pr | pull_request.opened |
workflow_run.disabled | authority_change | workflow | workflow_run.disabled |
release.published | artifact_change | deployment | release.published |
6.2 Jira
| Jira Event | GovernanceEvent Type | Subject Kind | Event Name |
|------------|---------------------|--------------|------------|
| jira:issue_created | | | state_change | ticket | issue.created |
jira:issue_updated | state_change | ticket | issue.updated |
jira:project_deleted | state_change | project | project.deleted |
6.3 AWS
| AWS Event | GovernanceEvent Type | Subject Kind | Event Name |
|-----------|---------------------|--------------|------------|
| CreateBucket | | | state_change | environment | bucket.created |
PutBucketPolicy | authority_change | environment | policy.updated |
AssumeRole | authority_change | identity | role.assumed |
---
7. Constitutional Evaluation (Non-Normative)
This section is informative (not part of the spec).
7.1 How Governance Systems Use GovernanceEvents
7.2 Example: GitHub Push to Main
Incoming GovernanceEvent:
` {
"event_type": "artifact_change",
"authority_source": "github",
"subject": { "kind": "branch", "name": "main" },
"event": { "name": "push", "severity": "med" }
}
json
`
Constitutional Rule (example):
` when:
event_type: artifact_change
authority_source: github
subject.kind: branch
subject.name: ["main", "production"]
then:
action: tighten_constraints
reason: "Production branch modified"
requires_approval: true
yaml
`
Result:
---
8. Security Considerations
8.1 Authentication
Platforms emitting GovernanceEvents should:
8.2 Authorization
Governance systems must:
is authorized8.3 Privacy
GovernanceEvents may contain sensitive data in payload.
Platforms should:
---
9. Versioning
This specification uses semantic versioning:
Current version: 1.0.0
---
10. Conformance
A platform conforms to GovernanceEvent v1.0 if:
is one of the four defined types and issued_at are valid ISO 8601 timestamps is unique within authority_source---
11. References
---
12. Appendix: Full Example
` {
"spec_version": "1.0.0",
"event_id": "550e8400-e29b-41d4-a716-446655440000",
"event_type": "authority_change",
"authority_source": "github",
"occurred_at": "2026-02-09T14:23:45.123Z",
"subject": {
"kind": "workflow",
"id": "12345",
"name": "security-scan",
"metadata": {
"repo": "acme-corp/api-gateway",
"branch": "main"
}
},
"event": {
"name": "workflow_run.disabled",
"severity": "high",
"description": "Security workflow disabled on main branch"
},
"provenance": {
"issuer": "github-app-12345",
"signature": "sha256:abcdef...",
"issued_at": "2026-02-09T14:23:46.000Z"
},
"payload": {
"workflow_run": {
"id": 12345,
"name": "security-scan",
"conclusion": "cancelled",
"actor": "alice@acme.com"
},
"repository": {
"full_name": "acme-corp/api-gateway",
"private": true
}
}
}
json
``
---
13. License
This specification is released under CC0 1.0 Universal (Public Domain).
Anyone may implement, extend, or reference this specification without restriction.
---
14. Contact
For questions, clarifications, or proposed changes:
---
End of Specification