Skip to content
Press / to search

Control-plane Config Schema Examples

Reference schema examples for Trust-plane config and adjacent Decision-plane catalogs — policy bundles, intent / task catalog, decision catalog, evaluation gates, model routing config.

Reference DesignLast reviewed: Edit on GitHub
At a glance

Reference Architecture

This page collects compact schema examples for control-plane artifacts. Treat them as documentation references, not complete generated schemas. Versioned schema files under /schemas, implementation tests, and the dedicated implementation docs are the source of truth where they exist.

Trust-plane config owns policy bundles, approval gates, evaluation gates, the model profile registry, and signed model-routing policy. Intent/task and decision catalogs are Decision-plane catalogs governed through the control-plane lifecycle; the Trust plane validates and enforces policy bindings but does not own the business decision catalog. (URL retained as control-plane-config for backward compatibility.)

Policy bundle (JSON Schema)

Approval gate naming is intentionally separate from rule naming. For the returns examples, R_HIGH_VALUE_REQUIRES_APPROVAL is the rule that fires, and GATE_FINANCE_APPROVAL is the approval_gates[].gate_id referenced by then.requires_approval_gate.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "ApprovalMode": { "enum": ["read_only", "local_write", "network", "delegated", "destructive"] },
    "Rule": {
      "type": "object",
      "properties": {
        "rule_id": { "type": "string" },
        "applies_to": {
          "type": "object",
          "properties": {
            "intent": { "type": "string" },
            "task": { "type": "string" }
          }
        },
        "if": {},
        "then": {
          "type": "object",
          "properties": {
            "allow": { "type": "boolean" },
            "approval_mode": { "$ref": "#/$defs/ApprovalMode" },
            "requires": { "type": "array", "items": { "type": "string" } },
            "prohibits": { "type": "array", "items": { "type": "string" } },
            "requires_approval_gate": { "type": ["string", "null"] },
            "arg_constraints": { "type": "object" }
          },
          "required": ["allow"]
        },
        "else": { "type": "object" },
        "decision_binding": { "type": "string" },
        "rationale": { "type": "string" },
        "citations": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["rule_id", "if", "then"]
    },
    "ApprovalGate": {
      "type": "object",
      "properties": {
        "gate_id": { "type": "string" },
        "when": {},
        "required_approver_role": { "type": "string" },
        "ttl_seconds": { "type": "integer", "minimum": 60 }
      },
      "required": ["gate_id", "when", "required_approver_role"]
    }
  },
  "type": "object",
  "properties": {
    "bundle_id": { "type": "string" },
    "priority": { "type": "integer", "minimum": 0 },
    "effective_from": { "type": "string", "format": "date-time" },
    "policy_dsl": {
      "type": "object",
      "properties": {
        "language": { "const": "jsonlogic" },
        "rules": { "type": "array", "items": { "$ref": "#/$defs/Rule" } }
      },
      "required": ["language", "rules"]
    },
    "guardrails": {
      "type": "object",
      "properties": {
        "must_refuse": { "type": "array", "items": { "type": "string" } },
        "must_escalate": { "type": "array", "items": { "type": "string" } },
        "redaction_rules": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["must_refuse", "must_escalate", "redaction_rules"]
    },
    "approval_gates": { "type": "array", "items": { "$ref": "#/$defs/ApprovalGate" } },
    "prohibited_claims": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["bundle_id", "priority", "policy_dsl", "guardrails", "approval_gates"]
}

Intent / Task Catalog (JSON Schema)

This catalog is a Decision-plane catalog. The control plane versions and signs it, while runtime components consume it to resolve allowed intents, task templates, and decision bindings.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "Intent": {
      "type": "object",
      "properties": {
        "intent_id": { "type": "string" },
        "version": { "type": "string" },
        "owner_role": { "type": "string" },
        "description": { "type": "string" },
        "risk_class": { "enum": ["read_only", "local_write", "network", "delegated", "destructive"] },
        "accepted_channels": { "type": "array", "items": { "type": "string" } },
        "locale_support": { "type": "array", "items": { "type": "string" } },
        "eligible_task_templates": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["intent_id", "version", "risk_class", "eligible_task_templates"]
    },
    "TaskTemplate": {
      "type": "object",
      "properties": {
        "task_template_id": { "type": "string" },
        "version": { "type": "string" },
        "intent_id": { "type": "string" },
        "owner_role": { "type": "string" },
        "decision_bindings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "decision_key": { "type": "string" },
              "checkpoint_after_step": { "type": "string" }
            },
            "required": ["decision_key"]
          }
        },
        "default_plan": { "type": "object" },
        "eligibility_rules": {}
      },
      "required": ["task_template_id", "version", "intent_id", "decision_bindings", "default_plan"]
    }
  },
  "properties": {
    "catalog_version": { "type": "string" },
    "intents": { "type": "array", "items": { "$ref": "#/$defs/Intent" } },
    "task_templates": { "type": "array", "items": { "$ref": "#/$defs/TaskTemplate" } }
  },
  "required": ["catalog_version", "intents", "task_templates"]
}

Decision Catalog (JSON Schema)

This catalog is Decision-plane owned. Trust-plane policy may bind to decision_key values and require approvals, but it should not become the owner of allowed outcomes, evidence semantics, or business decision rights.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "DecisionSpec": {
      "type": "object",
      "properties": {
        "decision_key": { "type": "string" },
        "version": { "type": "string" },
        "owner_role": { "type": "string" },
        "required_evidence": { "type": "array", "items": { "type": "string" } },
        "allowed_outcomes": { "type": "array", "items": { "type": "string" } },
        "approval_mode": { "enum": ["read_only", "local_write", "network", "delegated", "destructive"] },
        "inputs_schema_ref": { "type": "string" },
        "outputs_schema_ref": { "type": "string" },
        "eligibility_rules": {},
        "decision_right": { "enum": ["propose", "recommend", "execute", "escalate"] },
        "challenge_required": { "type": "boolean" }
      },
      "required": ["decision_key", "version", "required_evidence", "allowed_outcomes", "approval_mode"]
    }
  },
  "properties": {
    "catalog_version": { "type": "string" },
    "decision_specs": { "type": "array", "items": { "$ref": "#/$defs/DecisionSpec" } }
  },
  "required": ["catalog_version", "decision_specs"]
}

AI Gateway routing config (schema pointers)

Model profiles and routing policy are Trust-plane config artifacts consumed by the AI Gateway and LLM Router. They are separate from RoutingDecision runtime audit records, which the gateway writes during model calls.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "ModelProfile": {
      "type": "object",
      "properties": {
        "model_profile_id": { "type": "string" },
        "provider_adapter": { "type": "string" },
        "deployment_ref": { "type": "string" },
        "capabilities": { "type": "object" },
        "limits": { "type": "object" },
        "policy": { "type": "object" },
        "status": { "enum": ["healthy", "degraded", "disabled"] }
      },
      "required": ["model_profile_id", "provider_adapter", "deployment_ref", "capabilities", "policy", "status"]
    },
    "RoutingPolicy": {
      "type": "object",
      "properties": {
        "policy_id": { "type": "string" },
        "owner_role": { "type": "string" },
        "default_profile": { "type": "string" },
        "rules": { "type": "array", "items": { "type": "object" } }
      },
      "required": ["policy_id", "owner_role", "default_profile", "rules"]
    }
  },
  "properties": {
    "model_profiles": { "type": "array", "items": { "$ref": "#/$defs/ModelProfile" } },
    "routing_policies": { "type": "array", "items": { "$ref": "#/$defs/RoutingPolicy" } }
  },
  "required": ["model_profiles", "routing_policies"]
}

Evaluation gates (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "EvalTarget": {
      "type": "object",
      "properties": {
        "intent": { "type": "string" },
        "policy": { "type": "number", "minimum": 0, "maximum": 1 },
        "utility": { "type": "number", "minimum": 0, "maximum": 1 },
        "latency_p99_ms": { "type": "integer", "minimum": 0 },
        "safety": { "type": "number", "minimum": 0, "maximum": 1 },
        "economics_cents_per_decision": { "type": "number", "minimum": 0 }
      },
      "required": ["intent", "policy", "utility", "safety"]
    },
    "ReleaseGate": {
      "type": "object",
      "properties": {
        "metric": { "type": "string" },
        "max_delta": { "type": "number" },
        "verdict_on_breach": { "enum": ["block", "warn"] }
      },
      "required": ["metric", "max_delta", "verdict_on_breach"]
    }
  },
  "properties": {
    "eval_version": { "type": "string" },
    "eval_targets": { "type": "array", "items": { "$ref": "#/$defs/EvalTarget" } },
    "release_gates": { "type": "array", "items": { "$ref": "#/$defs/ReleaseGate" } }
  },
  "required": ["eval_version", "eval_targets", "release_gates"]
}