{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stellaops.io/schemas/vuln-explorer.v1.json",
  "title": "VulnExplorer",
  "description": "Vuln Explorer domain models for vulnerability management (GRAP0101)",
  "type": "object",
  "$defs": {
    "VulnSummary": {
      "type": "object",
      "description": "Summary view of a vulnerability finding",
      "required": ["id", "severity", "score", "exploitability", "cveIds", "purls", "policyVersion"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique finding identifier"
        },
        "severity": {
          "$ref": "#/$defs/Severity"
        },
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 10,
          "description": "CVSS or risk score"
        },
        "kev": {
          "type": "boolean",
          "description": "Is in CISA Known Exploited Vulnerabilities catalog"
        },
        "exploitability": {
          "$ref": "#/$defs/Exploitability"
        },
        "fixAvailable": {
          "type": "boolean",
          "description": "Whether a fix/patch is available"
        },
        "cveIds": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Associated CVE identifiers"
        },
        "purls": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Affected package URLs"
        },
        "policyVersion": {
          "type": "string",
          "description": "Policy version used for determination"
        },
        "rationaleId": {
          "type": "string",
          "description": "Reference to policy rationale"
        }
      }
    },
    "VulnDetail": {
      "type": "object",
      "description": "Detailed view of a vulnerability finding",
      "required": ["id", "severity", "score", "exploitability", "cveIds", "purls", "summary", "policyVersion", "firstSeen", "lastSeen"],
      "properties": {
        "id": {"type": "string"},
        "severity": {"$ref": "#/$defs/Severity"},
        "score": {"type": "number", "minimum": 0, "maximum": 10},
        "kev": {"type": "boolean"},
        "exploitability": {"$ref": "#/$defs/Exploitability"},
        "fixAvailable": {"type": "boolean"},
        "cveIds": {
          "type": "array",
          "items": {"type": "string"}
        },
        "purls": {
          "type": "array",
          "items": {"type": "string"}
        },
        "summary": {
          "type": "string",
          "description": "Human-readable vulnerability description"
        },
        "affectedPackages": {
          "type": "array",
          "items": {"$ref": "#/$defs/PackageAffect"}
        },
        "advisoryRefs": {
          "type": "array",
          "items": {"$ref": "#/$defs/AdvisoryRef"}
        },
        "rationale": {
          "$ref": "#/$defs/PolicyRationale"
        },
        "paths": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Dependency paths to vulnerable component"
        },
        "evidence": {
          "type": "array",
          "items": {"$ref": "#/$defs/EvidenceRef"}
        },
        "firstSeen": {
          "type": "string",
          "format": "date-time"
        },
        "lastSeen": {
          "type": "string",
          "format": "date-time"
        },
        "policyVersion": {"type": "string"},
        "rationaleId": {"type": "string"},
        "provenance": {"$ref": "#/$defs/EvidenceProvenance"}
      }
    },
    "Severity": {
      "type": "string",
      "enum": ["critical", "high", "medium", "low", "informational", "unknown"]
    },
    "Exploitability": {
      "type": "string",
      "description": "Exploitability assessment",
      "enum": ["active", "poc", "theoretical", "unlikely", "none", "unknown"]
    },
    "PackageAffect": {
      "type": "object",
      "required": ["purl"],
      "properties": {
        "purl": {
          "type": "string",
          "description": "Package URL"
        },
        "versions": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Affected version ranges"
        }
      }
    },
    "AdvisoryRef": {
      "type": "object",
      "required": ["url", "title"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        }
      }
    },
    "PolicyRationale": {
      "type": "object",
      "required": ["id", "summary"],
      "properties": {
        "id": {"type": "string"},
        "summary": {"type": "string"}
      }
    },
    "EvidenceRef": {
      "type": "object",
      "required": ["kind", "reference"],
      "properties": {
        "kind": {
          "type": "string",
          "description": "Type of evidence",
          "examples": ["sbom", "vex", "scan", "reachability"]
        },
        "reference": {
          "type": "string",
          "description": "URI or identifier to evidence"
        },
        "title": {
          "type": "string"
        }
      }
    },
    "EvidenceProvenance": {
      "type": "object",
      "required": ["ledgerEntryId", "evidenceBundleId"],
      "properties": {
        "ledgerEntryId": {
          "type": "string",
          "description": "Findings ledger entry ID"
        },
        "evidenceBundleId": {
          "type": "string",
          "description": "Evidence bundle reference"
        }
      }
    },
    "VulnListResponse": {
      "type": "object",
      "required": ["items"],
      "properties": {
        "items": {
          "type": "array",
          "items": {"$ref": "#/$defs/VulnSummary"}
        },
        "nextPageToken": {
          "type": "string",
          "description": "Token for next page of results"
        }
      }
    },
    "VulnFilter": {
      "type": "object",
      "description": "Query filters for vulnerability listing",
      "properties": {
        "policyVersion": {"type": "string"},
        "pageSize": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        },
        "pageToken": {"type": "string"},
        "cve": {
          "type": "string",
          "description": "Filter by CVE ID"
        },
        "purl": {
          "type": "string",
          "description": "Filter by package URL"
        },
        "severity": {"$ref": "#/$defs/Severity"},
        "exploitability": {"$ref": "#/$defs/Exploitability"},
        "fixAvailable": {"type": "boolean"}
      }
    },
    "FindingProjection": {
      "type": "object",
      "description": "Findings ledger projection model",
      "required": ["tenantId", "findingId", "policyVersion", "status", "updatedAt"],
      "properties": {
        "tenantId": {"type": "string"},
        "findingId": {"type": "string"},
        "policyVersion": {"type": "string"},
        "status": {
          "type": "string",
          "enum": ["open", "resolved", "suppressed", "false_positive"]
        },
        "severity": {
          "type": "number",
          "minimum": 0,
          "maximum": 10
        },
        "riskScore": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "riskSeverity": {"$ref": "#/$defs/Severity"},
        "riskProfileVersion": {"type": "string"},
        "riskExplanationId": {
          "type": "string",
          "format": "uuid"
        },
        "labels": {
          "type": "object",
          "additionalProperties": {"type": "string"}
        },
        "currentEventId": {
          "type": "string",
          "format": "uuid"
        },
        "explainRef": {"type": "string"},
        "policyRationale": {
          "type": "array",
          "items": {"type": "object"}
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "cycleHash": {"type": "string"}
      }
    },
    "FindingHistoryEntry": {
      "type": "object",
      "required": ["tenantId", "findingId", "policyVersion", "eventId", "status", "actorId", "occurredAt"],
      "properties": {
        "tenantId": {"type": "string"},
        "findingId": {"type": "string"},
        "policyVersion": {"type": "string"},
        "eventId": {
          "type": "string",
          "format": "uuid"
        },
        "status": {"type": "string"},
        "severity": {"type": "number"},
        "actorId": {"type": "string"},
        "comment": {"type": "string"},
        "occurredAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  },
  "examples": [
    {
      "id": "finding-001",
      "severity": "high",
      "score": 7.5,
      "kev": true,
      "exploitability": "active",
      "fixAvailable": true,
      "cveIds": ["CVE-2024-1234"],
      "purls": ["pkg:npm/lodash@4.17.20"],
      "policyVersion": "2025.12.1",
      "rationaleId": "rat-001"
    }
  ]
}