Skip to main content

Schema DSL Specification

The schema section is the foundational contract layer of Actra DSL. It defines the shape and primitive types of all runtime data that policies are allowed to reference.

Purpose​

The schema serves three critical roles:

  1. Defines allowed action payloads
  2. Defines actor context fields
  3. Defines snapshot/state fields

Everything referenced inside policy expressions must originate from this schema.

This makes the DSL:

  • statically analyzable
  • type-safe
  • compiler validated
  • governance friendly
  • SDK portable

Root Structure​

version: 1

actions:
  create_invoice:
    fields:
      amount: number
      currency: string
      approved: boolean

actor:
  fields:
    role: string
    region: string
    risk_score: number

snapshot:
  fields:
    tenant_plan: string
    monthly_usage: number
    is_suspended: boolean

Top-Level Fields​

version​

version: 1

Type: Numeric scalar Required: Yes

Used for forward compatibility of the DSL.

Current supported value:

  • 1

Future compiler versions may introduce migration or compatibility rules based on this field.

actions​

actions:
  action_name:
    fields:
      field_name: string

Type: Mapping of action names to action definitions Required: Yes

Defines every allowed runtime action type that may be evaluated by Actra.

Each key is the action name, and each action contains a fields mapping.

Action Schema Structure​

actions:
  deploy_service:
    fields:
      service: string
      replicas: number
      emergency: boolean

actor​

actor:
  fields:
    role: string

Type: Object containing actor field definitions Required: Yes

Defines identity and caller metadata.

These fields represent who is performing the action.

Typical examples:

  • role
  • tenant
  • department
  • permissions
  • region
  • auth_method
  • account_age_days

Example​

actor:
  fields:
    role: string
    department: string
    is_admin: boolean
    login_count: number

snapshot​

snapshot:
  fields:
    current_usage: number

Type: Object containing snapshot field definitions Required: Yes

Defines environment, resource, or domain state available during evaluation.

This is the read-only state context used by policies.

Typical examples:

  • account balance
  • deployment status
  • workflow stage
  • usage limits
  • fraud flags
  • resource ownership

Example​

snapshot:
  fields:
    balance: number
    tier: string
    is_locked: boolean

Field Definitions​

Every fields block is a mapping:

fields:
  key: type

Type: Mapping of field names to primitive field types

Supported Primitive Types​

The schema currently supports exactly three primitive types.

string​

email: string

Used for:

  • names
  • identifiers
  • roles
  • regions
  • enums represented as strings
  • freeform metadata

number​

amount: number

Used for:

  • counts
  • balances
  • scores
  • quotas
  • timestamps
  • versions
  • numeric risk signals

boolean​

approved: boolean

Used for binary state.

Examples:

  • flags
  • feature toggles
  • risk gates
  • account states
  • verification results

Compilation Model​

The YAML schema first loads as a raw document model and is then normalized into the compiler’s internal representation.

Compilation Flow​

YAML
  -> raw schema document
  -> normalized schema model
  -> policy compilation

This transformation performs:

  • primitive type normalization
  • field mapping conversion
  • compiler representation generation

It does not yet validate policy field references. That semantic validation happens later during compilation.

Compiler Guarantees​

After normalization, the compiler guarantees:

  • all schema primitive types are known
  • actor fields are strongly typed
  • snapshot fields are strongly typed
  • every action field is strongly typed
  • runtime SDKs can safely serialize values
  • governance rules can restrict field access

This strongly typed contract is what enables efficient policy compilation.

Detailed Spec Rules​

1) Required Sections​

All three sections are mandatory:

  • actions
  • actor
  • snapshot

A valid schema must define them even if minimally.

actor:
  fields:

is valid.

2) Action Names Must Be Unique​

Each action name inside actions must be unique.

3) Field Names Must Be Unique Within Scope​

Within each fields block, names must be unique.

Valid:

fields:
  amount: number
  currency: string

Invalid:

fields:
  amount: number
  amount: string

4) Primitive Types Are Closed​

Only these values are valid:

  • string
  • number
  • boolean

Anything else is invalid in v1.

Invalid example:

tags: array

Governance Implications​

Schema is also the governance boundary.

Because policies can only access declared fields, the schema controls:

  • what application data enters policy evaluation
  • what sensitive fields remain inaccessible
  • what SDKs may send to runtime
  • what can be audited safely

This is why schema should be treated as a security contract, not only a typing layer.

Best Practices​

Prefer stable field names​

Good:

risk_score: number

Avoid:

score_v2_latest: number

Keep actor identity minimal​

Only expose fields required for policy decisions.

Snapshot should be business state​

Use snapshot for:

  • balances
  • workflow stage
  • ownership
  • lifecycle status

Avoid transient request metadata unless truly required.