approval-engine/schemas/approval_claim.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://approval-engine.netkingdom/schemas/approval_claim.schema.json",
  "title": "ApprovalClaim",
  "description": "Input claim that access-engine consumes. This is a fact about an approval object, not a decision. Yields to the Taxonomy request-claim schema (statute \u00a717) when that artifact exists and is assented; do not treat this local shape as permanent.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "kind",
    "issuer",
    "approval_id",
    "state",
    "valid_now",
    "consumed",
    "binding",
    "freshness",
    "validity",
    "reason_code"
  ],
  "properties": {
    "schema_version": {
      "const": "0.1"
    },
    "kind": {
      "const": "approval-claim"
    },
    "yields_to": {
      "type": "string",
      "description": "Taxonomy artifact this contract yields to. Informational; consumers must not branch on it."
    },
    "issuer": {
      "const": "approval-engine"
    },
    "approval_id": {
      "type": "string",
      "format": "uuid"
    },
    "state": {
      "type": "string",
      "enum": [
        "requested",
        "approved",
        "valid",
        "consumed",
        "superseded",
        "revoked",
        "expired"
      ]
    },
    "valid_now": {
      "type": "boolean",
      "description": "True only when the object is approved, inside its validity window, and not consumed, superseded, revoked, or expired. Not a permission."
    },
    "consumed": {
      "type": "boolean"
    },
    "binding": {
      "$ref": "#/$defs/binding"
    },
    "freshness": {
      "$ref": "#/$defs/freshness"
    },
    "validity": {
      "$ref": "#/$defs/validity"
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "ok",
        "requested",
        "not_yet_valid",
        "insufficient_approvers",
        "expired",
        "revoked",
        "superseded",
        "consumed",
        "human_control_unsatisfied"
      ]
    }
  },
  "not": {
    "anyOf": [
      {
        "required": [
          "effect"
        ]
      },
      {
        "required": [
          "decision"
        ]
      },
      {
        "required": [
          "allow"
        ]
      },
      {
        "required": [
          "deny"
        ]
      }
    ]
  },
  "$defs": {
    "binding": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "action",
        "target",
        "actor",
        "principal",
        "purpose",
        "digest",
        "pdp_digest",
        "pdp_path"
      ],
      "properties": {
        "action": {
          "type": "string",
          "minLength": 1
        },
        "target": {
          "type": "object"
        },
        "actor": {
          "type": "string",
          "minLength": 1
        },
        "principal": {
          "type": "string",
          "minLength": 1
        },
        "purpose": {
          "type": "string",
          "minLength": 1
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[0-9a-f]{64}$",
          "description": "SHA-256 over the canonical JSON of action, actor, principal, purpose, target (sorted keys, RFC 8259). Distinguishes approved from approved-for-this-exact-request."
        },
        "pdp_digest": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^sha256:[0-9a-f]{64}$",
          "description": "The flex-auth NewDecisionBinding request_digest recorded at issue time, or null when the approval was not issued against a PDP decision. Always present so its absence is a stated fact rather than a missing key. Recorded at issue, so it is the digest of the action request as it stands before this claim is embedded in it. At execute time on a claim-bearing request the comparison target is the PDP's claim-excluded digest -- flex-auth publishes it as binding.approval_binding_digest (FLEX-DEC-2026-007) -- and NOT binding.request_digest, which covers the carried claim and therefore can never equal a digest recorded before that claim existed. When non-null, a consumer MUST compare this to the PDP's published exclusion-scoped digest and MUST NOT re-derive the native digest as a substitute, and MUST NOT guess the exclusion rule. A PEP on a privileged lane MUST refuse a claim whose pdp_digest is null."
        },
        "pdp_path": {
          "type": "boolean",
          "description": "Whether this approval was declared at issue for the GH-DEC-2026-003 PDP consumption path. GH-DEC-2026-008 requires pdp_digest on that path, so this engine refuses to create a pdp_path approval without one; a true value therefore guarantees pdp_digest is non-null. A consumer on that path MUST require pdp_path true and MUST NOT infer path intent from a pdp_digest that merely happens to be present."
        },
        "human_control": {
          "type": "boolean",
          "description": "Declared at issue under GH-DEC-2026-016: this object discharges a human-in-the-loop or dual-control requirement. New producers always state it; absence in historical claims is undeclared, never proof of human control. True with valid_now means the required distinct approvers are verified human principals. It is separate from the five-field act digest. Consumers requiring human control must require exactly true; they must not infer it from approver identity or count."
        }
      }
    },
    "freshness": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "observed_at",
        "ttl_seconds",
        "not_after"
      ],
      "properties": {
        "observed_at": {
          "type": "string",
          "format": "date-time"
        },
        "ttl_seconds": {
          "type": "integer",
          "minimum": 1
        },
        "not_after": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "validity": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "not_before",
        "expires_at"
      ],
      "properties": {
        "not_before": {
          "type": "string",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}