Skip to main content

Governance DSL Specification

The Governance DSL defines organizational constraints that validate policy documents before compilation.

Unlike policy rules, governance rules do not make runtime decisions. They enforce higher-order authoring constraints on policy structure, rule patterns, field usage, and mandatory controls.

This enables organizations to codify:

  • required safety controls
  • forbidden policy shapes
  • field access restrictions
  • minimum governance coverage
  • policy size limits
  • compliance guardrails

This page is the complete governance authoring reference for v1.

Validation Stage​

Governance validation runs in the compiler pipeline as:

YAML Policy
  -> Policy AST
  -> Governance Validation
  -> Validated IR
  -> Runtime Engine

A policy may be structurally valid yet still be rejected by governance.

Root Structure​

version: 1

governance:
  rules:
    - id: require_prod_approval
      applies_to:
        actions:
          - deploy_service
      select:
        where:
          effect: require_approval
      must:
        exists: true
      error: "Production deploys must require approval"

Top-Level Fields​

version​

Type: Numeric scalar Required: Yes

Current supported value:

  • 1

governance​

Type: Object containing governance rules Required: Yes

Contains the governance rule set.

governance.rules​

Type: Sequence of governance rules Required: Yes

Rules are evaluated sequentially and violations are aggregated.

Governance Rule Specification

Each governance rule contains five major sections.

- id: restrict_sensitive_fields
  select:
    where:
      when:
        subject:
          domain: snapshot
  must:
    allowed_fields:
      - snapshot.tier
      - snapshot.balance
  error: "Only approved snapshot fields may be used"

Rule Fields​

id​

Type: String scalar Required: Yes

Unique governance rule identifier.

applies_to​

Optional applicability narrowing.

applies_to:
  actions:
    - delete_user
    - deploy_service

If omitted, the governance rule applies to the entire policy document.

A governance rule applies if at least one policy rule targets one of the listed actions.

select​

Defines how policy rules are selected.

select:
  where:
    effect: block

The selector always uses a where clause.

must​

Defines the governance constraint.

Supported constraints:

  • exists
  • min_count
  • max_count
  • forbid
  • allowed_fields

error​

Type: String scalar Required: Yes

Custom error message returned when the constraint fails.

This message should be written for human governance reviews.

Selector DSL

Selectors match a subset of policy rules.

Matching is conjunctive: all specified filter clauses must match.

Selector Root​

select:
  where:
    id: require_prod_approval

Supported where Filters​

Filter by Rule ID​

where:
  id: require_prod_approval

Filter by Effect​

where:
  effect: require_approval

Supported values:

  • allow
  • block
  • require_approval

Filter by Scope​

Global Rules​

where:
  scope:
    global: true

Action Scope​

where:
  scope:
    action: deploy_service

Filter by Condition Subject​

where:
  when:
    subject:
      domain: snapshot
      field: balance

This matches if the rule condition references the selected subject.

Supported across:

  • atomic conditions
  • all
  • any

Constraint DSL

The must block uses a closed constraint vocabulary.

exists​

Requires at least one matching rule.

must:
  exists: true

Inverse​

must:
  exists: false

Requires no matching rules.

min_count​

Requires at least N matching rules.

must:
  min_count: 2

Useful for mandatory layered controls.

max_count​

Limits the number of matching rules.

must:
  max_count: 5

Useful for preventing rule explosion.

forbid​

Forbids selected rules.

must:
  forbid: true

This is ideal for banning dangerous rule patterns.

allowed_fields​

Restricts referenced condition fields.

must:
  allowed_fields:
    - actor.role
    - snapshot.tier

Fields must use:

<domain>.<field>

format.

This validates all referenced subjects inside:

  • atomic
  • all
  • any

conditions.

Violation Model

Governance failures are returned as an aggregated violation batch.

Each violation contains:

  • governance rule_id
  • custom error message

This design is excellent for:

  • CI validation
  • PR comments
  • policy review bots
  • IDE diagnostics
  • compliance exports

Validation Semantics

Governance validation executes in three deterministic stages.

1) Applicability Check​

If applies_to is defined, first determine whether the rule is relevant.

2) Rule Selection​

Select all matching policy rules using the selector.

3) Constraint Evaluation​

Evaluate the selected set against the declared constraint.

Violations are accumulated instead of fail-fast.

Governance Patterns

Mandatory Approval Gate​

- id: require_prod_approval
  applies_to:
    actions: [deploy_service]
  select:
    where:
      effect: require_approval
  must:
    exists: true
  error: "Deployments must require approval"

Forbid Global Block Rules​

- id: forbid_global_blocks
  select:
    where:
      scope:
        global: true
      effect: block
  must:
    forbid: true
  error: "Global block rules are not allowed"

Restrict Sensitive Fields​

- id: approved_subject_fields_only
  select:
    where:
      when:
        subject:
          domain: snapshot
  must:
    allowed_fields:
      - snapshot.tier
      - snapshot.balance
  error: "Unapproved snapshot field used"

Governance Best Practices

Prefer explicit human-readable errors​

Good:

error: "Production deploys must require approval"

Avoid vague messages.

Use allowed_fields for privacy boundaries​

This is extremely strong for:

  • PII isolation
  • tenant separation
  • financial field controls
  • export restrictions

Use forbid for dangerous anti-patterns​

Examples:

  • global deny rules
  • unrestricted approvals
  • broad admin allows

Strategic Value

This governance layer is one of Actra’s strongest differentiators.

It enables policy-on-policy enforcement, allowing platform teams to govern how teams write governance itself.

This creates a true:

  • compiler
  • governance engine
  • compliance layer
  • policy platform

rather than just a rules DSL.