{
  "$id": "https://stella.ops/schema/vex-normalization.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "VexNormalization",
  "description": "Normalized VEX representation supporting OpenVEX, CSAF VEX, and CycloneDX VEX formats with unified semantics",
  "type": "object",
  "required": [
    "schemaVersion",
    "documentId",
    "sourceFormat",
    "statements"
  ],
  "properties": {
    "schemaVersion": {
      "type": "integer",
      "const": 1,
      "description": "Schema version for forward compatibility"
    },
    "documentId": {
      "type": "string",
      "description": "Unique document identifier derived from source VEX",
      "examples": ["openvex:ghsa-2022-0001", "csaf:rhsa-2023-1234"]
    },
    "sourceFormat": {
      "type": "string",
      "enum": ["OPENVEX", "CSAF_VEX", "CYCLONEDX_VEX", "SPDX_VEX", "STELLAOPS"],
      "description": "Original VEX document format before normalization"
    },
    "sourceDigest": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$",
      "description": "SHA-256 digest of original source document"
    },
    "sourceUri": {
      "type": "string",
      "format": "uri",
      "description": "URI where source document was obtained"
    },
    "issuer": {
      "$ref": "#/$defs/VexIssuer",
      "description": "Issuing authority for this VEX document"
    },
    "issuedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp when VEX was originally issued"
    },
    "lastUpdatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp when VEX was last modified"
    },
    "statements": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/NormalizedStatement"
      },
      "minItems": 1,
      "description": "Normalized VEX statements extracted from source"
    },
    "provenance": {
      "$ref": "#/$defs/NormalizationProvenance",
      "description": "Metadata about the normalization process"
    }
  },
  "$defs": {
    "VexIssuer": {
      "type": "object",
      "required": ["id", "name"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique issuer identifier (e.g., PURL, domain)",
          "examples": ["pkg:github/anchore", "redhat.com", "github.com/github"]
        },
        "name": {
          "type": "string",
          "description": "Human-readable issuer name"
        },
        "category": {
          "type": "string",
          "enum": ["VENDOR", "DISTRIBUTOR", "COMMUNITY", "INTERNAL", "AGGREGATOR"],
          "description": "Issuer category for trust weighting"
        },
        "trustTier": {
          "type": "string",
          "enum": ["AUTHORITATIVE", "TRUSTED", "UNTRUSTED", "UNKNOWN"],
          "description": "Trust tier for policy evaluation"
        },
        "keyFingerprints": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Known signing key fingerprints for this issuer"
        }
      }
    },
    "NormalizedStatement": {
      "type": "object",
      "required": ["statementId", "vulnerabilityId", "product", "status"],
      "properties": {
        "statementId": {
          "type": "string",
          "description": "Unique statement identifier within this document"
        },
        "vulnerabilityId": {
          "type": "string",
          "description": "CVE, GHSA, or other vulnerability identifier",
          "examples": ["CVE-2023-12345", "GHSA-xxxx-yyyy-zzzz"]
        },
        "vulnerabilityAliases": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Known aliases for this vulnerability"
        },
        "product": {
          "$ref": "#/$defs/NormalizedProduct"
        },
        "status": {
          "type": "string",
          "enum": ["not_affected", "affected", "fixed", "under_investigation"],
          "description": "Normalized VEX status using OpenVEX terminology"
        },
        "statusNotes": {
          "type": "string",
          "description": "Additional notes about the status determination"
        },
        "justification": {
          "type": "string",
          "enum": [
            "component_not_present",
            "vulnerable_code_not_present",
            "vulnerable_code_not_in_execute_path",
            "vulnerable_code_cannot_be_controlled_by_adversary",
            "inline_mitigations_already_exist"
          ],
          "description": "Normalized justification when status is not_affected"
        },
        "impactStatement": {
          "type": "string",
          "description": "Impact description when status is affected"
        },
        "actionStatement": {
          "type": "string",
          "description": "Recommended action to remediate"
        },
        "actionStatementTimestamp": {
          "type": "string",
          "format": "date-time"
        },
        "versions": {
          "$ref": "#/$defs/VersionRange",
          "description": "Version constraints for this statement"
        },
        "subcomponents": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/NormalizedProduct"
          },
          "description": "Specific subcomponents affected within the product"
        },
        "firstSeen": {
          "type": "string",
          "format": "date-time",
          "description": "When this statement was first observed"
        },
        "lastSeen": {
          "type": "string",
          "format": "date-time",
          "description": "When this statement was last confirmed"
        }
      }
    },
    "NormalizedProduct": {
      "type": "object",
      "required": ["key"],
      "properties": {
        "key": {
          "type": "string",
          "description": "Canonical product key (preferably PURL)"
        },
        "name": {
          "type": "string",
          "description": "Human-readable product name"
        },
        "version": {
          "type": "string",
          "description": "Specific version if applicable"
        },
        "purl": {
          "type": "string",
          "pattern": "^pkg:",
          "description": "Package URL if available"
        },
        "cpe": {
          "type": "string",
          "pattern": "^cpe:",
          "description": "CPE identifier if available"
        },
        "hashes": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Content hashes (algorithm -> value)"
        }
      }
    },
    "VersionRange": {
      "type": "object",
      "properties": {
        "affected": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Version expressions for affected versions"
        },
        "fixed": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Version expressions for fixed versions"
        },
        "unaffected": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Version expressions for unaffected versions"
        }
      }
    },
    "NormalizationProvenance": {
      "type": "object",
      "required": ["normalizedAt", "normalizer"],
      "properties": {
        "normalizedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When normalization was performed"
        },
        "normalizer": {
          "type": "string",
          "description": "Service/version that performed normalization",
          "examples": ["stellaops-excititor/1.0.0"]
        },
        "sourceRevision": {
          "type": "string",
          "description": "Source document revision if tracked"
        },
        "transformationRules": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Transformation rules applied during normalization"
        }
      }
    }
  },
  "examples": [
    {
      "schemaVersion": 1,
      "documentId": "openvex:ghsa-2023-0001",
      "sourceFormat": "OPENVEX",
      "sourceDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
      "sourceUri": "https://github.com/anchore/vex-data/example.json",
      "issuer": {
        "id": "pkg:github/anchore",
        "name": "Anchore",
        "category": "VENDOR",
        "trustTier": "TRUSTED"
      },
      "issuedAt": "2025-11-21T10:00:00Z",
      "statements": [
        {
          "statementId": "stmt-001",
          "vulnerabilityId": "CVE-2023-12345",
          "product": {
            "key": "pkg:npm/example@1.0.0",
            "name": "example",
            "version": "1.0.0",
            "purl": "pkg:npm/example@1.0.0"
          },
          "status": "not_affected",
          "justification": "vulnerable_code_not_in_execute_path",
          "statusNotes": "The vulnerable function is not used in the package's runtime code path.",
          "firstSeen": "2025-11-21T10:00:00Z",
          "lastSeen": "2025-11-21T10:00:00Z"
        }
      ],
      "provenance": {
        "normalizedAt": "2025-11-21T10:15:00Z",
        "normalizer": "stellaops-excititor/1.0.0"
      }
    }
  ]
}