Skip to main content

Policy DSL Specification

The Policy DSL defines how Actra expresses authorization, governance, approval, and decision logic in a fully declarative YAML format.

This document is the complete policy authoring reference for v1 and combines:

  • policy document structure
  • rule grammar
  • scope semantics
  • condition grammar
  • subject references
  • literal values
  • supported operators
  • rule effects
  • compilation guarantees
  • governance implications

Root Policy Structure​

version: 1

rules:
  - id: require_finance_approval
    scope:
      action: transfer_funds
    when:
      all:
        - subject:
            domain: action
            field: amount
          operator: greater_than
          value:
            literal: 100000
        - subject:
            domain: actor
            field: department
          operator: equals
          value:
            literal: finance
    effect: require_approval

Top-Level Fields​

version​

Type: Numeric scalar Required: Yes

Current supported value:

  • 1

rules​

Type: Sequence of rule definitions Required: Yes

The rule sequence preserves author intent and deterministic compilation order.

Rule Specification

Each rule contains four required sections.

- id: block_suspended_account
  scope:
    global: true
  when:
    subject:
      domain: snapshot
      field: is_suspended
    operator: equals
    value:
      literal: true
  effect: block

Rule Fields​

id​

Type: String scalar Required: Yes

Unique rule identifier.

Example:

id: require_manager_approval

scope​

Defines where the rule applies.

Supported forms:

Action Scope​

scope:
  action: delete_user

Actor Scope​

scope:
  actor: admin

Global Scope​

scope:
  global: true

Exactly one scope form must be used.

when​

Defines conditional evaluation logic.

Supported forms:

Atomic Condition​

when:
  subject:
    domain: actor
    field: role
  operator: equals
  value:
    literal: admin

Logical AND​

when:
  all:
    - subject:
        domain: actor
        field: role
      operator: equals
      value:
        literal: admin

Logical OR​

when:
  any:
    - subject:
        domain: actor
        field: region
      operator: equals
      value:
        literal: eu

effect​

Defines the outcome when the rule condition evaluates to true.

Supported values:

  • allow
  • block
  • require_approval

Condition Grammar

Atomic conditions follow this model:

<subject> <operator> <value>

Subject Reference​

A subject references a field from schema domains.

subject:
  domain: actor
  field: role

Supported Domains​

  • action
  • actor
  • snapshot

The referenced field must exist in the schema.

Value Forms​

Literal Value​

value:
  literal: admin

Subject Reference Value​

value:
  subject:
    domain: snapshot
    field: owner_id

This enables field-to-field comparisons.

Supported Literal Types​

String​

literal: admin

Number​

literal: 42

Boolean​

literal: true

Operator Reference

The operator vocabulary is closed in v1.

Equality​

equals​

operator: equals

not_equals​

operator: not_equals

Numeric Comparison​

greater_than​

operator: greater_than

Numeric only.

less_than​

operator: less_than

Numeric only.

Membership​

in​

operator: in

not_in​

operator: not_in

Operator Type Rules​

Equality​

Supports:

  • string
  • number
  • boolean
  • subject-to-subject matching types

Numeric​

Supports only numeric fields.

Membership​

Supports scalar membership semantics.

Effects Semantics

allow​

Explicitly permits the evaluated action.

block​

Explicitly denies the evaluated action.

require_approval​

Defers the decision to an approval workflow.

This is one of Actra’s strongest governance primitives.

Detailed Validation Rules

1) Rule IDs Must Be Unique​

Every id must be unique within the policy document.

2) Scope Shape Is Closed​

Only one of the following is valid:

  • action
  • actor
  • global

3) Condition Shape Is Closed​

Only:

atomic

  • all
  • any

are valid.

4) Operator Vocabulary Is Closed​

Only these operators are valid:

  • equals
  • not_equals
  • greater_than
  • less_than
  • in
  • not_in

5) Effect Vocabulary Is Closed​

Only:

  • allow
  • block
  • require_approval

are valid.

Compilation Model

YAML
  -> raw policy document
  -> validated IR
  -> optimized evaluation plan
  -> runtime decision engine

Compilation validates:

  • schema field existence
  • operator legality
  • type compatibility
  • rule structure correctness
  • governance restrictions

Governance Implications

The Policy DSL is designed as a human-reviewable governance language.

This enables:

  • PR reviews
  • compliance approvals
  • security signoff
  • audit exports
  • deterministic diffing
  • rule ownership workflows

This is a major strategic advantage over embedded policy code.

Best Practices

Prefer intent-rich rule IDs​

Good:

id: block_cross_region_customer_export

Avoid:

id: rule_9

Prefer narrow scopes​

Use action scopes where possible.

Use require_approval for governance gates​

This should be the preferred effect for:

  • high-value transactions
  • destructive actions
  • tenant migrations
  • permission escalation
  • production deployments

Prefer semantic operators​

Good:

operator: greater_than

Avoid symbols.

Canonical Example

version: 1

rules:
  - id: require_prod_deploy_approval
    scope:
      action: deploy_service
    when:
      all:
        - subject:
            domain: action
            field: environment
          operator: equals
          value:
            literal: production
        - subject:
            domain: actor
            field: role
          operator: not_equals
          value:
            literal: sre_admin
    effect: require_approval