API documentation

Decionis Policy Spec v1

Your policy decides whether an action may run. The people who own the risk write it in their own words; PolicyAgent encodes it; a named person accepts every version before it decides anything. This page is the contract for each of those steps.

Overview

A policy is a set of rules for one business domain: payouts, refunds, spec changes, production deploys. A request names the domain policy it needs, and the policy returns one of three outcomes.

DocumentWho works with itSchema
Your sourcesThe people who own the risk: CISO, compliance and risk, business teams. Plain English, or the documents you already have.None. Any supported format.
Authoring documentPolicyAgent writes it from your sources. Reviewers read it. AI assistants propose changes to it.https://decionis.com/schemas/policy-authoring/v1
Policy bundleThe evaluator runs it. Each published version is identified by its digest, and every decision records the version that made it.https://decionis.com/schemas/policy/v1
One owner per step

PolicyAgent is the only encoder of record. Assistants such as Claude, Copilot or Cursor can encode a candidate with their own model and propose it, but a proposal changes nothing until a person accepts it in the workspace. No assistant can publish, approve, activate or deploy a policy.

Formats

Write in plain English, or upload what you already have. Each source is kept with its digest, so every rule can cite the exact text it came from. Each source is at most 10 MB.

DirectionFormat
In: your sourcesPlain text, typed or pasted · Markdown · PDF, up to 200 pages. A scan with no text layer is held for review. · Word (.docx) · CSV · Excel (.xlsx) · A web page (HTML) · Jira issues
EncodedJSON: the authoring document, then the policy bundle the evaluator runs
ExportYAML, to review a policy or keep it in Git. YAML is never read back in.

JSON submitted to Decionis must be a single object with no duplicate or ambiguous keys. Anything else is refused rather than guessed at.

The rule card

Every rule is read back in this shape before it is encoded, and the person who owns it confirms it. It is how a rule written in plain English becomes one that can only mean one thing.

When [who] [does what] [to what],
and  [condition],
then allow / escalate to [role] / block,
because [source].
When an AI agent issues a refund over 500 USD, and the order is older than 30 days, then escalate to the Finance Controller, because Refund Policy §4.2.
PartWhat it needs
WhoA person, a team, an AI agent or a service.
Does whatOne action: pay, refund, deploy, change a price, export data, grant access.
ConditionAmounts with a currency, time windows, counts, data classes, environments. Vague words such as large, senior, sensitive or unusual are replaced by a number, a role or a list.
OutcomeAllow, escalate to a named role, or block.
BecauseThe clause, ticket or document the rule comes from.
When nothing matches

End every policy with a catch-all rule that has no conditions. Unless you decide otherwise, it blocks.

Authoring document

The JSON form of your rules, validated against https://decionis.com/schemas/policy-authoring/v1. A policy holds up to 120 rules. The example encodes the rule card above.

{
  "$schema": "https://decionis.com/schemas/policy-authoring/v1",
  "metadata": {
    "policy_id": "refunds",
    "domain": "refunds",
    "source_artifacts": [
      "Refund Policy v3"
    ],
    "version": "1.0.0"
  },
  "execution_binding": {
    "tool_identifier": "refund.issue",
    "input_schema_mapping": {
      "amount": "input.amount",
      "currency": "input.currency",
      "order_age_days": "input.order_age_days"
    }
  },
  "ruleset": [
    {
      "id": "refund-old-order-over-500",
      "decision_domain": "refunds",
      "description": "Old orders: refunds over 500 USD need the Finance Controller.",
      "conditions": {
        "all": [
          {
            "field": "input.currency",
            "operator": "EQUALS",
            "value": "USD"
          },
          {
            "field": "input.amount",
            "operator": "GREATER_THAN",
            "value": 500
          },
          {
            "field": "input.order_age_days",
            "operator": "GREATER_THAN",
            "value": 30
          }
        ]
      },
      "verdict": "ESCALATE",
      "presence_gate": {
        "mode": "ALL",
        "required_roles": [
          "FINANCE_CONTROLLER"
        ],
        "conditions": []
      }
    },
    {
      "id": "refund-default",
      "decision_domain": "refunds",
      "description": "Anything no other rule covers is blocked.",
      "conditions": null,
      "verdict": "BLOCK",
      "presence_gate": null
    }
  ]
}
FieldMeaning
metadatapolicy_id, the business domain, the source documents it came from, and a semantic version.
execution_bindingThe action this policy governs (tool_identifier) and where each fact comes from in the request (input.*).
ruleset[].conditionsA predicate, or all / any groups that nest. null means the rule always matches.
ruleset[].verdictALLOW, ESCALATE, BLOCK, or REVIEW_REQUIRED while drafting.
ruleset[].presence_gateFor ESCALATE: the roles that must approve, from the Presence role directory, and whether one or two approvers are needed.

Operators: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN, EXISTS, CONTAINS, MATCHES.

Outcomes

Every decision has exactly one of three outcomes: ALLOW, ESCALATE or BLOCK. They are never renamed. An approval by a person is an escalation, never an allow.

Authoring verdictPolicy bundle actionDecisionWhat happens
ALLOWAUTO_APPROVEALLOWThe action may run, with a single-use grant.
ESCALATEESCALATEESCALATEThe action waits for the approver the rule names, who confirms in Presence.
REVIEW_REQUIREDREQUIRE_REVIEW, REQUEST_INFOESCALATEThe action is held for review, with no named approver.
BLOCKAUTO_REJECTBLOCKThe action does not run.

A policy can list the facts it needs before any rule is matched. When one is missing, the decision is ESCALATE, never a guess.

Review to enforce

A policy decides nothing until it has been reviewed, tested and run in shadow mode. Each approval is an attestation to an exact, immutable revision, and a high-impact policy also needs a Risk Reviewer at every step.

StateMeaning
DRAFTBeing written. Authors and Policy Owners edit it.
REVIEW_READYSubmitted for review as an immutable revision.
APPROVED_FOR_TESTINGThe Policy Owner and a Technical Reviewer approved it for testing.
TESTEDIts test scenarios have run and the results are recorded.
APPROVED_FOR_SHADOWThe Test Approver and the Release Approver approved it for shadow mode.
SHADOW_ACTIVERecording the verdict it would give on live requests. Nothing is blocked.
APPROVED_FOR_PRODUCTIONThe Policy Owner and the Release Approver approved it for production.
PRODUCTION_ACTIVEDeciding live requests in its business domain.
SUPERSEDEDReplaced by a newer version. Kept, with every decision it made.
RETIREDNo longer used. Kept, with every decision it made.
Separation of duties

Approving, testing and deploying need someone other than the author. A workspace with a single member can have its owner review, and a registered sole proprietor holds every role and attests to each one separately; the release records which applied. Agents cannot attest.

Roles

Your workspace assigns these roles to people. Approvers named in rules come from the Presence role directory, the one place approvers are defined.

RoleDuty
SOURCE_CUSTODIANUploads and vouches for the source documents.
AUTHORWrites and edits the rules.
POLICY_OWNEROwns the policy: reviews the sources, scope and assumptions; edits and submits it.
RISK_REVIEWERReviews control effectiveness and risk. Required at every approval of a high-impact policy.
TECHNICAL_REVIEWERReviews how each rule maps to its source, the inputs, defaults, ordering and conflicts.
TEST_APPROVERReviews the test scenarios, expected outcomes and observed results.
RELEASE_APPROVERReviews the test, shadow and operational evidence for a release, rollback or retirement.
DEPLOYERPuts an approved version live.
AUDITORReads revisions, citations and the review record. Changes nothing.

DECIONIS_POLICY.md

A plain Markdown file at a repository root, reviewed with the code. It is the human statement of the rules: nothing in it is evaluated.

The GitHub Action (decionis/govern) hashes the file and records its path and SHA-256 with each decision, so a Decision Dossier shows which revision the repository held. The policy that decides is the one in your workspace. The file can also be a source: upload it as Markdown and PolicyAgent encodes it like any other document.

Published schemas

JSON Schema (draft 2020-12), public and versioned. Validate your own documents against them, or generate types from them.

SchemaURL
Authoring documenthttps://decionis.com/schemas/policy-authoring/v1
Policy bundlehttps://decionis.com/schemas/policy/v1
Starter packs, authoring formhttps://decionis.com/schemas/policy-authoring/v1/packs
Starter packs, bundle formhttps://decionis.com/schemas/policy/v1/packs

To draft a policy from your documents through the API, see Policy encoding.