{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stellaops.dev/schemas/excititor/vex_overlay.schema.json",
  "title": "Excititor VEX Overlay",
  "description": "Graph-ready overlay built from Link-Not-Merge observations and linksets. Immutable and append-only; ordered for deterministic pagination and caching.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schemaVersion",
    "generatedAt",
    "tenant",
    "purl",
    "advisoryId",
    "source",
    "status",
    "observations",
    "provenance"
  ],
  "properties": {
    "schemaVersion": {
      "type": "string",
      "enum": ["1.0.0"]
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "tenant": {
      "type": "string",
      "description": "Tenant identifier used for storage partitioning."
    },
    "purl": {
      "type": "string",
      "description": "Normalized package URL for the component."
    },
    "advisoryId": {
      "type": "string",
      "description": "Upstream advisory identifier (e.g., GHSA, RHSA, CVE)."
    },
    "source": {
      "type": "string",
      "description": "Linkset source identifier (matches Concelier linkset source)."
    },
    "status": {
      "type": "string",
      "enum": [
        "affected",
        "not_affected",
        "under_investigation",
        "fixed",
        "unknown"
      ]
    },
    "justifications": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["kind", "reason"],
        "properties": {
          "kind": {
            "type": "string",
            "description": "Reason code aligned to VEX statement taxonomy."
          },
          "reason": {
            "type": "string",
            "description": "Human-readable justification text."
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Observation or linkset id contributing to this justification."
            }
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Optional confidence weight."
          }
        }
      }
    },
    "conflicts": {
      "type": "array",
      "description": "Conflicts detected in linkset normalization.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["field", "reason"],
        "properties": {
          "field": { "type": "string" },
          "reason": { "type": "string" },
          "values": {
            "type": "array",
            "items": { "type": "string" }
          },
          "sourceIds": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    },
    "observations": {
      "type": "array",
      "description": "Ordered list of Link-Not-Merge observation references feeding this overlay.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "contentHash", "fetchedAt"],
        "properties": {
          "id": { "type": "string" },
          "contentHash": { "type": "string", "pattern": "^sha256:[A-Fa-f0-9]{64}$" },
          "fetchedAt": { "type": "string", "format": "date-time" }
        }
      },
      "minItems": 1
    },
    "provenance": {
      "type": "object",
      "additionalProperties": false,
      "required": ["linksetId", "linksetHash", "observationHashes"],
      "properties": {
        "linksetId": { "type": "string" },
        "linksetHash": { "type": "string", "pattern": "^sha256:[A-Fa-f0-9]{64}$" },
        "observationHashes": {
          "type": "array",
          "items": { "type": "string", "pattern": "^sha256:[A-Fa-f0-9]{64}$" },
          "minItems": 1
        },
        "policyHash": { "type": "string" },
        "sbomContextHash": { "type": "string" },
        "planCacheKey": { "type": "string" },
        "generatedBy": { "type": "string" }
      }
    },
    "cache": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "cached": { "type": "boolean" },
        "cachedAt": { "type": "string", "format": "date-time" },
        "ttlSeconds": { "type": "integer", "minimum": 0 }
      }
    }
  }
}