Cognitive_Agent/contracts/schemas/intent-ir.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cognitive-agent.local/schemas/intent-ir.schema.json",
  "title": "IntentIR",
  "type": "object",
  "additionalProperties": false,
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": {"const": "cognitive-agent/v1alpha1"},
    "kind": {"const": "IntentIR"},
    "metadata": {"$ref": "common.schema.json#/$defs/metadata"},
    "spec": {
      "type": "object",
      "additionalProperties": false,
      "required": ["utterance", "language", "mode", "detected_domains", "requests", "actions", "constraints", "ambiguities", "unresolved_spans", "coverage", "confidence", "requires_confirmation", "execution_eligible"],
      "properties": {
        "utterance": {"type": "string", "minLength": 1, "maxLength": 4000},
        "language": {"type": "string", "pattern": "^[a-z]{2}(?:-[A-Z]{2})?$"},
        "mode": {"type": "string", "enum": ["single_domain", "cross_domain"]},
        "detected_domains": {
          "type": "array",
          "minItems": 0,
          "uniqueItems": true,
          "items": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"}
        },
        "requests": {
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["domain", "goal"],
            "properties": {
              "domain": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
              "goal": {"type": "string", "minLength": 1, "maxLength": 500},
              "target": {"$ref": "common.schema.json#/$defs/target"},
              "parameters": {"type": "object"},
              "source_span": {"type": "string", "maxLength": 500}
            }
          }
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "domain", "capability", "target", "operation", "parameters", "source_span", "confidence", "provenance", "risk_level", "confirmation_policy"],
            "properties": {
              "id": {"type": "string", "pattern": "^[a-z][a-z0-9_-]*$"},
              "domain": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
              "capability": {"type": "string", "minLength": 1},
              "target": {"$ref": "common.schema.json#/$defs/target"},
              "operation": {"type": "string", "minLength": 1},
              "parameters": {"type": "object"},
              "source_span": {"$ref": "#/$defs/sourceSpan"},
              "confidence": {"type": "object", "additionalProperties": {"type": "number", "minimum": 0, "maximum": 1}},
              "provenance": {"type": "object", "required": ["parser", "rule_ids"], "properties": {"parser": {"type": "string"}, "rule_ids": {"type": "array", "items": {"type": "string"}}}, "additionalProperties": true},
              "risk_level": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
              "confirmation_policy": {"type": "string", "enum": ["never", "on_ambiguity", "always"]},
              "resolution": {"type": "object"}
            }
          }
        },
        "constraints": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "required": ["id", "type", "source_span"],
            "properties": {
              "id": {"type": "string"},
              "type": {"type": "string"},
              "domain": {"type": "string"},
              "capability": {"type": "string"},
              "target": {"$ref": "common.schema.json#/$defs/target"},
              "parameters": {"type": "object"},
              "source_span": {"$ref": "#/$defs/sourceSpan"}
            }
          }
        },
        "ambiguities": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["field", "question"],
            "properties": {
              "field": {"type": "string", "minLength": 1},
              "question": {"type": "string", "minLength": 1},
              "options": {"type": "array", "items": {"type": ["string", "number", "boolean"]}},
              "reason": {"type": "string"},
              "risk_level": {"type": "string"}
            }
          },
          "default": []
        },
        "unresolved_spans": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["text", "start", "end", "reason"],
            "properties": {
              "text": {"type": "string"},
              "start": {"type": "integer", "minimum": 0},
              "end": {"type": "integer", "minimum": 0},
              "reason": {"type": "string"}
            }
          }
        },
        "coverage": {
          "type": "object",
          "additionalProperties": false,
          "required": ["complete", "covered_spans"],
          "properties": {
            "complete": {"type": "boolean"},
            "covered_spans": {"type": "array", "items": {"$ref": "#/$defs/sourceSpan"}}
          }
        },
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        "requires_confirmation": {"type": "boolean"},
        "execution_eligible": {"type": "boolean"}
      }
    }
  },
  "$defs": {
    "sourceSpan": {
      "type": "object",
      "additionalProperties": false,
      "required": ["text", "start", "end"],
      "properties": {
        "text": {"type": "string"},
        "start": {"type": "integer", "minimum": 0},
        "end": {"type": "integer", "minimum": 0}
      }
    }
  }
}