Skip to main content

​
Overview

Every policy is a JSON file at policies/{policyId}/{policyVersion}/policy.json. The policyId must match its parent directory name. The policyVersion must match the version directory name and must be semver format.

​
Top-level fields

FieldTypeRequiredDescription
policyIdstring✅Unique policy identifier. Must match parent directory name.
policyVersionsemver✅Policy version. Must match version directory name. Format: 1.0.0.
schemaVersionstring✅Currently only "1.0.0" is supported.
signalsSchemaobject✅Declares the signals this policy accepts.
rulesarray✅Ordered list of rules. First match wins.

​
signalsSchema

Each key declares a signal with its type: 
"signalsSchema": {
  "amount":   { "type": "integer" },
  "tier":     { "type": "string" },
  "approved": { "type": "boolean" },
  "score":    { "type": "integer" },
  "status":   { "type": "enum", "values": ["active", "inactive", "pending"] }
}
See Signal Types for full validation rules per type. Signals not declared here are rejected with VAL-003 at execution time.

​
rules

Each rule has three required fields: 
{
  "id":        "unique-rule-id",
  "condition": { ... },
  "outcome":   { ... }
}
Rule id values must be unique within the policy (POL-020).

​
condition

OperatorDescriptionExample
greater_thanSignal value greater than threshold{ "signal": "amount", "greater_than": 1000 }
less_thanSignal value less than threshold{ "signal": "amount", "less_than": 500 }
equalsSignal value equals given value{ "signal": "tier", "equals": "premium" }
allAll sub-conditions must match{ "all": [{ "signal": "a", "equals": true }, { "signal": "b", "greater_than": 100 }] }
anyAny sub-condition must match{ "any": [{ "signal": "a", "equals": true }, { "signal": "b", "equals": false }] }
all: []Always matches (catch-all){ "all": [] }
Conditions may reference only signals declared in signalsSchema. Unknown signals are rejected with POL-019.

​
outcome

FieldTypeRequiredDescription
actionstring✅The decision outcome
requires_overrideboolean✅Whether human override is required before execution
reasonstring—Human-readable explanation included in the attestation. Optional, but strongly recommended.

​
Valid actions

ActionDescription
approveDecision approved
rejectDecision rejected
escalateEscalate to higher authority
manual_reviewRequires human review
auto_approveAutomatic approval
document_requiredMore documentation needed
fraud_reviewRoute to fraud team
pending_overrideOverride required

​
Complete example

{
  "policyId":      "loan-approval",
  "policyVersion": "1.0.0",
  "schemaVersion": "1.0.0",
  "signalsSchema": {
    "credit_score": { "type": "integer" },
    "loan_amount":  { "type": "integer" },
    "employed":     { "type": "boolean" }
  },
  "rules": [
    {
      "id": "reject-low-score",
      "condition": { "signal": "credit_score", "less_than": 500 },
      "outcome": {
        "action": "reject",
        "requires_override": false,
        "reason": "Credit score below minimum threshold."
      }
    },
    {
      "id": "require-employment-for-large-loans",
      "condition": {
        "all": [
          { "signal": "loan_amount", "greater_than": 50000 },
          { "signal": "employed",    "equals": false }
        ]
      },
      "outcome": {
        "action": "reject",
        "requires_override": false,
        "reason": "Employment required for loans over $50,000."
      }
    },
    {
      "id": "approve-standard",
      "condition": { "signal": "credit_score", "greater_than": 700 },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "Credit score meets standard threshold."
      }
    },
    {
      "id": "catch-all",
      "condition": { "all": [] },
      "outcome": {
        "action": "manual_review",
        "requires_override": true,
        "reason": "Credit score requires manual review."
      }
    }
  ]
}

​
Compilation phases

The policy compiler validates policies in 8 phases. All phases must pass before a bundle can be signed:
PhaseCheck
1File exists at the given path
2Valid JSON syntax
3Required top-level fields present
4policyId matches parent directory name
5schemaVersion is supported
6signalsSchema is valid
7All rules are valid
8Catch-all rule present

​
Use Cases

​
Personal loan underwriting policy

A complete policy for evaluating personal loan applications from salaried employees in India. Rules evaluate from top to bottom; the first matching rule wins: 
{
  "policyId":      "personal-loan",
  "policyVersion": "1.0.0",
  "schemaVersion": "1.0.0",
  "signalsSchema": {
    "monthly_income":    { "type": "integer" },
    "loan_amount":       { "type": "integer" },
    "credit_score":      { "type": "integer" },
    "emi_obligations":   { "type": "integer" },
    "employed":          { "type": "boolean" },
    "employment_type":   { "type": "enum", "values": ["salaried", "self_employed", "government"] },
    "blacklisted":       { "type": "boolean" }
  },
  "rules": [
    {
      "id": "reject-blacklisted",
      "condition": { "signal": "blacklisted", "equals": true },
      "outcome": {
        "action": "reject",
        "requires_override": false,
        "reason": "applicant_blacklisted"
      }
    },
    {
      "id": "reject-low-credit",
      "condition": { "signal": "credit_score", "less_than": 600 },
      "outcome": {
        "action": "reject",
        "requires_override": false,
        "reason": "credit_score_below_minimum"
      }
    },
    {
      "id": "reject-unemployed",
      "condition": { "signal": "employed", "equals": false },
      "outcome": {
        "action": "reject",
        "requires_override": false,
        "reason": "employment_required"
      }
    },
    {
      "id": "auto-approve-prime",
      "condition": {
        "all": [
          { "signal": "credit_score",    "greater_than": 750 },
          { "signal": "monthly_income",  "greater_than": 80000 }
        ]
      },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "prime_borrower_auto_approved"
      }
    },
    {
      "id": "manual-review-standard",
      "condition": { "all": [] },
      "outcome": {
        "action": "manual_review",
        "requires_override": true,
        "reason": "standard_underwriting_required"
      }
    }
  ]
}

​
UPI fraud detection policy

A policy that routes high-risk transactions for fraud review: 
{
  "policyId":      "upi-fraud-gate",
  "policyVersion": "1.0.0",
  "schemaVersion": "1.0.0",
  "signalsSchema": {
    "transaction_amount": { "type": "integer" },
    "risk_score":         { "type": "integer" },
    "is_foreign":         { "type": "boolean" }
  },
  "rules": [
    {
      "id": "block-high-risk",
      "condition": { "signal": "risk_score", "greater_than": 75 },
      "outcome": {
        "action": "fraud_review",
        "requires_override": true,
        "reason": "risk_score_exceeds_threshold"
      }
    },
    {
      "id": "escalate-large-foreign",
      "condition": {
        "all": [
          { "signal": "transaction_amount", "greater_than": 200000 },
          { "signal": "is_foreign",         "equals": true }
        ]
      },
      "outcome": {
        "action": "escalate",
        "requires_override": true,
        "reason": "large_foreign_transaction_requires_review"
      }
    },
    {
      "id": "approve-standard",
      "condition": { "all": [] },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "transaction_cleared"
      }
    }
  ]
}

​
See also