schemas/routing-decision.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:tokenx:schema:routing-decision:v2",
  "title": "TokenX routing decision",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schemaVersion",
    "decisionId",
    "sessionId",
    "observedTurnId",
    "provider",
    "route",
    "execution",
    "agentCount",
    "model",
    "reasoningEffort",
    "method",
    "reasonCodes",
    "explicit",
    "createdAtMs",
    "expiresAtMs",
    "delegationPlan",
    "delegationMode"
  ],
  "properties": {
    "schemaVersion": {
      "const": 2
    },
    "decisionId": {
      "type": "string",
      "pattern": "^tx_[a-f0-9]{24}$"
    },
    "sessionId": {
      "type": "string",
      "minLength": 1
    },
    "observedTurnId": {
      "type": [
        "string",
        "null"
      ]
    },
    "provider": {
      "const": "codex"
    },
    "route": {
      "enum": [
        "passthrough",
        "parent",
        "economy",
        "standard",
        "deep"
      ]
    },
    "execution": {
      "enum": [
        "none",
        "parent",
        "agent"
      ]
    },
    "agentCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4
    },
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "reasoningEffort": {
      "enum": [
        null,
        "low",
        "medium",
        "high",
        "xhigh",
        "max",
        "ultra"
      ]
    },
    "method": {
      "type": "string",
      "minLength": 1
    },
    "reasonCodes": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "explicit": {
      "type": "boolean"
    },
    "createdAtMs": {
      "type": "integer",
      "minimum": 0
    },
    "expiresAtMs": {
      "type": "integer",
      "minimum": 1
    },
    "delegationPlan": {
      "anyOf": [
        { "type": "null" },
        { "$ref": "urn:tokenx:schema:delegation-plan:v2" }
      ]
    },
    "delegationMode": { "enum": ["none", "classifier_proposed"] }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "execution": {
            "const": "agent"
          }
        }
      },
      "then": {
        "properties": {
          "agentCount": {
            "minimum": 1
          },
          "model": {
            "type": "string",
            "minLength": 1
          },
          "reasoningEffort": {
            "enum": [
              "low",
              "medium",
              "high",
              "xhigh",
              "max",
              "ultra"
            ]
          }
        }
      },
      "else": {
        "properties": {
          "agentCount": {
            "const": 0
          },
          "model": {
            "const": null
          },
          "reasoningEffort": {
            "const": null
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "delegationMode": { "const": "none" }
        }
      },
      "then": {
        "properties": {
          "delegationPlan": { "const": null }
        }
      },
      "else": {
        "properties": {
          "delegationPlan": { "$ref": "urn:tokenx:schema:delegation-plan:v2" }
        }
      }
    }
  ]
}