{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stellaops.io/schemas/advisory-key.v1.json",
  "title": "AdvisoryKey",
  "description": "Canonical advisory key for vulnerability correlation across VEX observations, policy findings, and risk assessments",
  "type": "object",
  "required": ["advisoryKey", "scope", "links"],
  "additionalProperties": false,
  "properties": {
    "advisoryKey": {
      "type": "string",
      "description": "The canonical advisory key used for correlation and storage. CVE identifiers remain unchanged; non-CVE identifiers are prefixed with scope indicator (ECO:, VND:, DST:, UNK:)",
      "examples": ["CVE-2024-1234", "ECO:GHSA-XXXX-XXXX-XXXX", "VND:RHSA-2024:1234"]
    },
    "scope": {
      "$ref": "#/$defs/AdvisoryScope"
    },
    "links": {
      "type": "array",
      "description": "Original and alias identifiers preserved for traceability",
      "items": {
        "$ref": "#/$defs/AdvisoryLink"
      },
      "minItems": 1
    }
  },
  "$defs": {
    "AdvisoryScope": {
      "type": "string",
      "description": "The scope/authority level of the advisory",
      "enum": ["global", "ecosystem", "vendor", "distribution", "unknown"],
      "x-enum-descriptions": {
        "global": "Global identifiers (CVE)",
        "ecosystem": "Ecosystem-specific identifiers (GHSA)",
        "vendor": "Vendor-specific identifiers (RHSA, MSRC, ADV)",
        "distribution": "Distribution-specific identifiers (DSA, USN)",
        "unknown": "Unclassified or custom identifiers"
      }
    },
    "AdvisoryLink": {
      "type": "object",
      "description": "A link to an original or alias advisory identifier",
      "required": ["identifier", "type", "isOriginal"],
      "additionalProperties": false,
      "properties": {
        "identifier": {
          "type": "string",
          "description": "The advisory identifier value",
          "examples": ["CVE-2024-1234", "GHSA-xxxx-xxxx-xxxx", "RHSA-2024:1234"]
        },
        "type": {
          "$ref": "#/$defs/AdvisoryType"
        },
        "isOriginal": {
          "type": "boolean",
          "description": "True if this is the original identifier provided at ingest time"
        }
      }
    },
    "AdvisoryType": {
      "type": "string",
      "description": "The type of advisory identifier",
      "enum": ["cve", "ghsa", "rhsa", "dsa", "usn", "msrc", "other"],
      "x-enum-descriptions": {
        "cve": "Common Vulnerabilities and Exposures (CVE-YYYY-NNNNN)",
        "ghsa": "GitHub Security Advisory (GHSA-xxxx-xxxx-xxxx)",
        "rhsa": "Red Hat Security Advisory (RHSA-YYYY:NNNN)",
        "dsa": "Debian Security Advisory (DSA-NNNN-N)",
        "usn": "Ubuntu Security Notice (USN-NNNN-N)",
        "msrc": "Microsoft Security Response Center (ADV-YYYY-NNNN)",
        "other": "Custom or unrecognized identifier format"
      }
    },
    "AdvisoryIdentifierPattern": {
      "type": "object",
      "description": "Patterns for recognizing advisory identifier formats",
      "properties": {
        "cve": {
          "type": "string",
          "const": "^CVE-\\d{4}-\\d{4,}$"
        },
        "ghsa": {
          "type": "string",
          "const": "^GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$"
        },
        "rhsa": {
          "type": "string",
          "const": "^RH[A-Z]{2}-\\d{4}:\\d+$"
        },
        "dsa": {
          "type": "string",
          "const": "^DSA-\\d+(-\\d+)?$"
        },
        "usn": {
          "type": "string",
          "const": "^USN-\\d+(-\\d+)?$"
        },
        "msrc": {
          "type": "string",
          "const": "^(ADV|CVE)-\\d{4}-\\d+$"
        }
      }
    }
  },
  "examples": [
    {
      "advisoryKey": "CVE-2024-1234",
      "scope": "global",
      "links": [
        {
          "identifier": "CVE-2024-1234",
          "type": "cve",
          "isOriginal": true
        },
        {
          "identifier": "GHSA-xxxx-xxxx-xxxx",
          "type": "ghsa",
          "isOriginal": false
        }
      ]
    },
    {
      "advisoryKey": "ECO:GHSA-XXXX-XXXX-XXXX",
      "scope": "ecosystem",
      "links": [
        {
          "identifier": "GHSA-xxxx-xxxx-xxxx",
          "type": "ghsa",
          "isOriginal": true
        }
      ]
    }
  ]
}