YAML policy schema design for AI agents

The YAML policy schema is the interface between humans and the policy engine. Its design determines how easy policies are to write, review, and maintain. This article explains the design principles behind Authensor's policy schema.

Design goals

1. Readable by non-engineers: Security teams, compliance officers, and managers should be able to read and understand policies without programming knowledge.

2. Machine-evaluatable: The schema must be unambiguous. Every valid policy must produce a deterministic evaluation result.

3. Composable: Multiple policies can be merged. Base policies and override policies combine predictably.

4. Safe by default: A minimal or empty policy should deny everything, not allow everything.

Schema structure

version: "1"
metadata:
  name: "Production policy"
  description: "Safety rules for the production agent"
  owner: "security-team"
  updated: "2026-02-15"

rules:
  - tool: "search.web"
    action: allow

  - tool: "file.write"
    action: escalate
    when:
      args.path:
        not:
          startsWith: "/tmp/"
    reason: "Writes outside /tmp/ need approval"

  - tool: "*"
    action: block
    reason: "Deny by default"

Rule anatomy

Each rule has:

• tool: A tool name or pattern (supports * wildcards)
• action: What to do (allow, block, escalate)
• when: Optional conditions on arguments and context
• reason: Human-readable explanation (required for block and escalate)
• metadata: Optional data for approval routing, SLA, etc.

Condition matchers

The when block uses nested matchers that read like natural language:

when:
  args.amount:
    gt: 100          # Amount greater than 100
  args.to:
    not:
      endsWith: "@company.com"  # Not an internal email
  context.role:
    equals: "engineer"          # User role is engineer

Available matchers: equals, not, startsWith, endsWith, contains, matches (regex), gt, lt, gte, lte.

Why YAML

YAML was chosen over JSON, TOML, or a custom DSL for several reasons:

• Readable: YAML reads like a structured outline. Non-engineers can parse it visually.
• Comments: YAML supports comments. Policies can include rationale inline.
• Established: Most engineers already know YAML from CI/CD configurations.
• Tools: Editors, linters, and diff tools support YAML out of the box.

Schema validation

The policy schema is defined as a JSON Schema. This enables:

• Editor autocompletion and inline validation
• CI validation in the pipeline
• Documentation generation from the schema
• Cross-language compatibility (both TypeScript and Python can validate against the same schema)

Versioning

The version field enables schema evolution. When the schema changes (new matchers, new fields), the version increments. The policy engine can evaluate policies of any supported version, maintaining backward compatibility.

Common patterns

Allowlist: List allowed tools explicitly, block everything else with a catch-all * rule at the bottom.

Blocklist: Allow everything by default, block specific patterns. Less safe but simpler for low-risk environments.

Escalation ladder: Multiple rules for the same tool with different conditions, escalating from allow to escalate to block based on argument values.