Policies

Define deterministic governance rules in JSON

What is a policy?

A policy is a JSON document that defines:

1. A schema — which signals are required and what types they must be
2. Rules — ordered list of conditions and outcomes; first match wins
3. Identity — policyId + policyVersion that are embedded in every attestation

Policies are versioned, immutable artifacts. Changing a policy means creating a new version — the old version remains valid and independently verifiable.

---

Full policy example

This is the claims-approval/v1 policy included in the repository:

{
  "policyId": "claims-approval",
  "policyVersion": "v1",
  "schemaVersion": "1.0.0",

  "signalsSchema": {
    "insurance_active": { "type": "boolean" },
    "risk_score":       { "type": "integer" },
    "vip_customer":     { "type": "boolean" },
    "claim_amount":     { "type": "integer" }
  },

  "rules": [
    {
      "id": "high-risk-reject",
      "condition": {
        "signal": "risk_score",
        "greater_than": 80
      },
      "outcome": {
        "action": "reject",
        "requires_override": false,
        "reason": "risk_score_exceeded_threshold"
      }
    },
    {
      "id": "vip-fast-track",
      "condition": {
        "signal": "vip_customer",
        "equals": true
      },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "vip_customer_approved"
      }
    },
    {
      "id": "standard-approval",
      "condition": {
        "all": [
          { "signal": "insurance_active", "equals": true },
          { "signal": "risk_score",       "less_than": 70 }
        ]
      },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "standard_approval"
      }
    },
    {
      "id": "catch-all-reject",
      "condition": { "all": [] },
      "outcome": {
        "action": "reject",
        "requires_override": true,
        "reason": "policy_requirements_not_satisfied"
      }
    }
  ]
}

---

Schema reference

Top-level fields

Field	Type	Required	Description
policyId	string	✓	Stable policy identifier, embedded in every attestation
policyVersion	string	✓	Version string (e.g. "v1", "1.0.0")
schemaVersion	string	✓	Schema format version
signalsSchema	object	✓	Map of signal names to type declarations
rules	array	✓	Ordered list of rules; first match wins

Signal types

Type string	JavaScript equivalent
"boolean"	true / false
"integer"	number (must satisfy Number.isInteger)
"string"	string

Rule fields

Field	Type	Required	Description
id	string	✓	Unique rule identifier; embedded in the DecisionResult
condition	object	✓	The match condition (see below)
outcome	object	✓	The decision if this rule matches

Condition operators

Operator	Applies to	Example
equals	any type	{ "signal": "vip_customer", "equals": true }
greater_than	integer	{ "signal": "risk_score", "greater_than": 80 }
less_than	integer	{ "signal": "risk_score", "less_than": 70 }
all	compound	{ "all": [ ...conditions ] }

An empty all: [] matches every input — use it as the final catch-all rule.

Outcome fields

Field	Type	Description
action	"approve" | "reject"	The governance decision
requires_override	boolean	Whether human escalation is required
reason	string	Machine-readable reason string embedded in the attestation

---

Rule evaluation semantics

Rules are evaluated in order, top to bottom. Evaluation stops at the first match. A well-formed policy must end with a catch-all rule so that all possible signal combinations resolve to a decision.

If no rule matches, the runtime throws an invariant violation. Always include a "condition": { "all": [] } catch-all as the final rule.

---

Using the CLI to inspect policies

# Inspect policy structure
parmana policy inspect ./policies/claims-approval/v1/policy.json

# Visualize rule graph
parmana policy graph ./policies/claims-approval/v1/policy.json

# Simulate a batch of decisions without signing
parmana policy simulate ./policies/claims-approval/v1/policy.json ./test-records.json

See CLI Reference for full documentation.