> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Schema Reference

> Complete reference for policy.json

## 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

| Field           | Type   | Required | Description                                                         |
| --------------- | ------ | -------- | ------------------------------------------------------------------- |
| `policyId`      | string | ✅        | Unique policy identifier. Must match parent directory name.         |
| `policyVersion` | semver | ✅        | Policy version. Must match version directory name. Format: `1.0.0`. |
| `schemaVersion` | string | ✅        | Currently only `"1.0.0"` is supported.                              |
| `signalsSchema` | object | ✅        | Declares the signals this policy accepts.                           |
| `rules`         | array  | ✅        | Ordered list of rules. First match wins.                            |

## signalsSchema

Each key declares a signal with its type:

```json theme={null}
"signalsSchema": {
  "amount":   { "type": "integer" },
  "tier":     { "type": "string" },
  "approved": { "type": "boolean" },
  "score":    { "type": "integer" },
  "status":   { "type": "enum", "values": ["active", "inactive", "pending"] }
}
```

See [Signal Types](/reference/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:

```json theme={null}
{
  "id":        "unique-rule-id",
  "condition": { ... },
  "outcome":   { ... }
}
```

Rule `id` values must be unique within the policy (`POL-020`).

### condition

| Operator       | Description                         | Example                                                                                  |
| -------------- | ----------------------------------- | ---------------------------------------------------------------------------------------- |
| `greater_than` | Signal value greater than threshold | `{ "signal": "amount", "greater_than": 1000 }`                                           |
| `less_than`    | Signal value less than threshold    | `{ "signal": "amount", "less_than": 500 }`                                               |
| `equals`       | Signal value equals given value     | `{ "signal": "tier", "equals": "premium" }`                                              |
| `all`          | All sub-conditions must match       | `{ "all": [{ "signal": "a", "equals": true }, { "signal": "b", "greater_than": 100 }] }` |
| `any`          | Any 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

| Field               | Type    | Required | Description                                                                                 |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `action`            | string  | ✅        | The decision outcome                                                                        |
| `requires_override` | boolean | ✅        | Whether human override is required before execution                                         |
| `reason`            | string  | —        | Human-readable explanation included in the attestation. Optional, but strongly recommended. |

### Valid actions

| Action              | Description                  |
| ------------------- | ---------------------------- |
| `approve`           | Decision approved            |
| `reject`            | Decision rejected            |
| `escalate`          | Escalate to higher authority |
| `manual_review`     | Requires human review        |
| `auto_approve`      | Automatic approval           |
| `document_required` | More documentation needed    |
| `fraud_review`      | Route to fraud team          |
| `pending_override`  | Override required            |

## Complete example

```json theme={null}
{
  "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:

| Phase | Check                                    |
| ----- | ---------------------------------------- |
| 1     | File exists at the given path            |
| 2     | Valid JSON syntax                        |
| 3     | Required top-level fields present        |
| 4     | `policyId` matches parent directory name |
| 5     | `schemaVersion` is supported             |
| 6     | `signalsSchema` is valid                 |
| 7     | All rules are valid                      |
| 8     | Catch-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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

* [Signal Types](/reference/signal-types) - validation rules per type
* [Error Codes](/reference/error-codes) - `POL-*` compilation errors
* [Policies](/concepts/policies) - conceptual overview