Policy rule model

A Policy can be edited in the Builder or as JSON in Policy as Code. Both edit the same draft. This page describes the JSON form.

Document

{
  "schemaVersion": "aethis.policy/v1",
  "metadata": {
    "name": "Payments Policy",
    "scope": "Workspace · Production",
    "summary": "Approval controls for production financial operations."
  },
  "defaultDecision": "No match",
  "rules": [
    {
      "name": "Finance write approval",
      "plane": "mcp_gateway",
      "subject": "Billing Agent",
      "connection": "Finance MCP",
      "capability": { "type": "Tool", "id": "refund.create" },
      "resource": "stripe.production",
      "condition": "amount > 1000 SGD",
      "decision": "require_approval",
      "obligations": [],
      "priority": 100
    }
  ]
}

Field	Meaning
schemaVersion	Always aethis.policy/v1.
metadata.name	The Policy name.
metadata.scope	Where the book lives, for example Workspace · Production or Organization · All.
metadata.summary	A short description of the book.
defaultDecision	What this book returns when no rule matches: No match, or one of the decisions.
rules	The rules. See below.

Rule fields

Field	Values	Meaning
name	text	A readable name. Shown as the Matched rule in Action Records.
plane	mcp_gateway, model_gateway	Whether the rule governs MCP tool calls or model requests (OpenAI routes).
subject	text	Who the rule applies to, such as an Agent.
connection	a Connection or Model Route in scope	Which upstream destination the rule covers.
capability	{ "type": "Tool", "id": "…" }	The discovered capability, such as a tool, the rule covers.
resource	text	The target the action acts on.
condition	text, optional	An extra condition, such as an amount threshold.
decision	allow, require_approval, block	Shown in the dashboard as Allow, Require Approval, Block.
obligations	list	Additional requirements recorded with the decision.
priority	number	Numeric metadata shown and validated by the editor. Do not use it to make overlapping same-scope rules safe. See Rule precedence.

Every reference must resolve. A rule that points at a Connection or capability that no longer exists puts the book in Conflict until you publish a fixed version.

Rule precedence

When more than one rule matches an action, Aethis decides between them in two stages.

1. Scope precedence. A more specific scope wins over a less specific one. From most to least specific:

1. Workspace + Operation + a specific Agent
2. Workspace + Operation + any Agent
3. Workspace + Semantic Profile (a rule that matches a tool by its reviewed meaning, such as its effect, rather than by the operation)
4. Default deny

2. Disjoint conditions within one scope. Keep rules at the same scope from overlapping. A numeric priority is present in the document and shown in the compiled preview, but it is not a safe way to resolve conflicting decisions.

Conflicts remain unresolved. If same-scope rules can both apply and disagree, narrow the subject, capability, resource or condition before publishing. Do not change only priority and assume the conflict is resolved.

How rules read in the dashboard

The Builder reads each rule back as a sentence:

• MCP: Require Approval Billing Agent to use tool refund.create from Finance MCP on stripe.production when amount > 1000 SGD.
• Model: Allow Support Agent to send model requests through Production OpenAI Route to the route’s model.

Versions

Publishing creates an immutable version with a version label and a hash. Action Records name the version and the matched rule that produced each decision. Use Compare Policy Versions to see the difference between two versions.

Validation

Use Validate draft in the Builder or Validate Policy in Policy as Code. Aethis reports each problem with its path in the document. Compiled policy shows what Aethis will evaluate after publishing.