{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://securitycontrols.ai/agentic-controls.schema.json",
  "title": "Agentic Security Control Matrix dataset",
  "description": "Canonical source of truth. Enforcement gate: scripts/validate.mjs (this schema documents the shape).",
  "type": "object",
  "required": ["meta", "planes", "layers", "gaps", "references", "asi_coverage", "controls"],
  "additionalProperties": true,
  "definitions": {
    "mapping": {
      "type": "object",
      "required": ["value", "status"],
      "properties": {
        "value": { "type": "string" },
        "status": { "enum": ["verified", "indicative", "forthcoming"] },
        "fit": {
          "enum": ["direct", "partial", "adjacent", "supporting"],
          "description": "How strongly the cited source matches the control, separate from `status` (which is evidence strength). direct = the source materially requires/matches the control; partial = related but not the whole requirement; adjacent = broad or contextual; supporting = a dependency the control relies on or enables, not a thing it implements (e.g. an ATLAS mitigation that only supplies telemetry)."
        },
        "evidence": {
          "type": "object",
          "required": ["ref", "rationale"],
          "description": "Per-cell evidence: the source (references[] id), the section/clause, a one-line rationale, and the verification date.",
          "properties": {
            "ref": { "type": "string" },
            "section": { "type": "string" },
            "rationale": { "type": "string" },
            "verified_on": { "type": "string" }
          }
        }
      }
    },
    "check": {
      "type": "object",
      "required": ["text"],
      "description": "Cite-or-flag: must have a resolvable ref OR unverified:true.",
      "properties": {
        "text": { "type": "string", "minLength": 1 },
        "ref": { "type": "string" },
        "unverified": { "type": "boolean" }
      },
      "anyOf": [{ "required": ["ref"] }, { "required": ["unverified"] }]
    }
  },
  "properties": {
    "patterns": {
      "type": "array",
      "description": "Cross-layer implementation patterns (e.g. the runtime enforcement plane). Not controls and not a layer; each maps to a set of existing control ids.",
      "items": {
        "type": "object",
        "required": ["id", "title", "controls"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "type": { "type": "string" },
          "plain": { "type": "string" },
          "desc": { "type": "string" },
          "invariant": { "type": "string" },
          "enforcementPoints": { "type": "array", "items": { "type": "string" } },
          "controls": { "type": "array", "minItems": 1, "items": { "type": "string" } }
        }
      }
    },
    "references": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "title", "type"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "url": { "type": "string" },
          "type": { "type": "string" },
          "date": { "type": "string" },
          "claim": { "type": "boolean" },
          "flagship": { "type": "boolean" }
        }
      }
    },
    "controls": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "id", "layer", "plane", "name", "plain", "threat", "standard",
          "mappings", "implementers", "frameworks", "sources",
          "implementation", "validation", "lenses", "maturity", "coverage_note"
        ],
        "properties": {
          "id": { "type": "string" },
          "cross_domain": {
            "type": "object",
            "description": "RESERVED extension point (optional, not yet populated): links from this security control to controls in adjacent domains (see meta.adjacent_domains: privacy, financial, model-eval, reliability) for a future multi-domain crosswalk. Keyed by domain key; additive, so adding it later is not a breaking change.",
            "additionalProperties": true
          },
          "layer": { "enum": ["identity", "containment", "protocol", "governance", "runtime", "assurance"] },
          "plane": { "enum": ["control", "data", "both", "lifecycle"] },
          "name": { "type": "string", "minLength": 1 },
          "plain": { "type": "string", "minLength": 1 },
          "threat": {
            "type": "object",
            "required": ["tags", "desc"],
            "properties": {
              "tags": { "type": "array", "items": { "type": "string" } },
              "desc": { "type": "string", "minLength": 1 }
            }
          },
          "standard": { "type": "array", "items": { "type": "string" } },
          "mappings": {
            "type": "object",
            "properties": {
              "aicm": { "$ref": "#/definitions/mapping" },
              "aismm": { "$ref": "#/definitions/mapping" },
              "nist": { "$ref": "#/definitions/mapping" },
              "iso": { "$ref": "#/definitions/mapping" },
              "owasp": { "$ref": "#/definitions/mapping" },
              "aisvs": { "$ref": "#/definitions/mapping" },
              "mitre": { "$ref": "#/definitions/mapping" },
              "mgf": { "$ref": "#/definitions/mapping" }
            }
          },
          "implementers": { "type": "array", "items": { "type": "string" } },
          "frameworks": { "type": "array", "items": { "type": "string" } },
          "sources": { "type": "array", "minItems": 1, "items": { "type": "string" } },
          "implementation": {
            "type": "object",
            "required": ["pattern", "steps", "anti_patterns"],
            "properties": {
              "pattern": { "type": "string", "minLength": 1 },
              "steps": { "type": "array", "minItems": 1, "items": { "type": "string" } },
              "anti_patterns": { "type": "array", "minItems": 1, "items": { "type": "string" } }
            }
          },
          "validation": {
            "type": "object",
            "required": ["design_check", "runtime_test", "evidence"],
            "properties": {
              "design_check": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/check" } },
              "runtime_test": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/check" } },
              "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/check" } }
            }
          },
          "lenses": {
            "type": "object",
            "required": ["engineering", "detection", "red_team", "grc", "secops"],
            "properties": {
              "engineering": { "type": "string", "minLength": 1 },
              "detection": { "type": "string", "minLength": 1 },
              "red_team": { "type": "string", "minLength": 1 },
              "grc": { "type": "string", "minLength": 1 },
              "secops": { "type": "string", "minLength": 1 }
            }
          },
          "maturity": {
            "type": "object",
            "required": ["current", "target"],
            "properties": {
              "current": { "type": ["string", "null"], "enum": ["none", "manual", "automated", "enforced", null] },
              "target": { "enum": ["none", "manual", "automated", "enforced"] }
            }
          },
          "coverage_note": { "type": "string" },
          "matrix_thesis": { "type": "boolean" },
          "thesis_type": {
            "description": "Only on matrix_thesis controls. Clarifies that 'this matrix's own position' is not 'a novel invention': compensating (mitigates an unresolved gap), elevated (an established mechanism raised to a standalone agentic control), or frontier (an original, research-stage position).",
            "enum": ["compensating", "elevated", "frontier"]
          },
          "readiness": {
            "description": "Deployment readiness. Absent = deployable. emerging = buildable but efficacy varies / partly research-dependent. research = frontier, not shelf-ready.",
            "enum": ["deployable", "emerging", "research"]
          },
          "enforcement_point": {
            "description": "Where the control is actually enforced (the architectural integration point) — bridges the prose to a builder's wiring.",
            "type": "string"
          },
          "tiers": {
            "description": "Risk drivers that make this control matter, for tiering an agent up from the baseline floor.",
            "type": "array",
            "items": { "enum": ["autonomy", "external-reach", "irreversibility", "data-sensitivity"] }
          },
          "response": {
            "description": "The operational lever when the control fires (revoke, halt, block, pause/kill/isolate, abort, fail-build, etc.). Only on controls that carry one.",
            "type": "object",
            "required": ["lever", "detail"],
            "properties": { "lever": { "type": "string" }, "detail": { "type": "string" } }
          },
          "detection_schema": {
            "description": "Minimum telemetry, baseline, and alert condition that make a detection-bearing control writable as a real signature. Only on detection-relevant controls.",
            "type": "object",
            "required": ["telemetry", "baseline", "alert"],
            "properties": {
              "telemetry": { "type": "array", "minItems": 1, "items": { "type": "string" } },
              "baseline": { "type": "string" },
              "alert": { "type": "string" }
            }
          },
          "star_ai": { "type": "boolean" }
        }
      }
    }
  }
}