model-eol 0.2.1

package/lib/validate-feed.mjs

@@ -0,0 +1,246 @@
+export const MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+export const MAX_IDENTIFIER_LENGTH = 256
+export const MAX_TEXT_LENGTH = 4096
+export const MAX_URL_LENGTH = 4096
+export const MAX_REPORT_BYTES = 8 * 1024 * 1024
+export const MIN_TIMEOUT_MS = 1000
+export const MAX_TIMEOUT_MS = 3600000
+
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+const DATE_PRECISIONS = new Set(['exact', 'earliest'])
+const DISTRIBUTION_STATUSES = new Set(['active', 'legacy', 'extended-access', 'retired'])
+
+export const assertIsoDate = (value, label = 'date') => {
+  if (typeof value !== 'string' || !DATE_PATTERN.test(value)) {
+    throw new Error(`${label} must be YYYY-MM-DD`)
+  }
+  const [year, month, day] = value.split('-').map(Number)
+  const date = new Date(Date.UTC(year, month - 1, day))
+  if (year >= 0 && year <= 99) date.setUTCFullYear(year)
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() + 1 !== month ||
+    date.getUTCDate() !== day
+  ) throw new Error(`${label} must be a real calendar date`)
+  return value
+}
+
+const isObject = value => value && typeof value === 'object' && !Array.isArray(value)
+
+const isUrl = value => {
+  try {
+    const url = new URL(value)
+    return url.protocol === 'http:' || url.protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+export const validateFeed = feed => {
+  const errors = []
+  const fail = (path, message) => errors.push({ path, message })
+  const checkString = (value, path, limit = MAX_TEXT_LENGTH) => {
+    if (typeof value !== 'string') return false
+    if (CONTROL_CHARACTER_PATTERN.test(value)) fail(path, 'must not contain control characters')
+    if (value.length > limit) fail(path, `must be at most ${limit} characters`)
+    return true
+  }
+  const checkIdentifier = (value, path, required = false) => {
+    if (value === undefined && !required) return false
+    if (!checkString(value, path, MAX_IDENTIFIER_LENGTH)) {
+      fail(path, required ? 'must be a string' : 'must be a string')
+      return false
+    }
+    if (!value || !MODEL_ID_PATTERN.test(value)) fail(path, 'must be a grammar-valid model ID')
+    return Boolean(value && MODEL_ID_PATTERN.test(value))
+  }
+  const checkUrl = (value, path) => {
+    if (value === undefined) return false
+    if (!checkString(value, path, MAX_URL_LENGTH)) {
+      fail(path, 'must be a string URL')
+      return false
+    }
+    if (!isUrl(value)) fail(path, 'must be an http or https URL')
+    return true
+  }
+  const checkDate = (value, path) => {
+    if (value === undefined) return false
+    if (!checkString(value, path, 32)) {
+      fail(path, 'must be YYYY-MM-DD')
+      return false
+    }
+    try {
+      assertIsoDate(value, path)
+      return true
+    } catch (error) {
+      fail(path, error.message)
+      return false
+    }
+  }
+  const checkDateTime = (value, path) => {
+    if (!checkString(value, path, 64)) {
+      fail(path, 'must be an ISO date-time')
+      return false
+    }
+    if (!DATE_TIME_PATTERN.test(value) || Number.isNaN(Date.parse(value))) {
+      fail(path, 'must be an ISO date-time')
+      return false
+    }
+    try {
+      assertIsoDate(value.slice(0, 10), path)
+    } catch (error) {
+      fail(path, error.message)
+      return false
+    }
+    return true
+  }
+  const checkObjectKeys = (value, path, allowed) => {
+    if (!isObject(value)) {
+      fail(path, 'must be an object')
+      return false
+    }
+    for (const key of Object.keys(value)) {
+      if (!allowed.has(key)) fail(`${path}.${key}`, 'unknown field')
+    }
+    return true
+  }
+  const walkStrings = (value, path, seen = new Set()) => {
+    if (typeof value === 'string') {
+      checkString(value, path)
+      return
+    }
+    if (!value || typeof value !== 'object' || seen.has(value)) return
+    seen.add(value)
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walkStrings(item, `${path}[${index}]`, seen))
+    } else {
+      for (const [key, item] of Object.entries(value)) walkStrings(item, `${path}.${key}`, seen)
+    }
+  }
+
+  walkStrings(feed, 'feed')
+  if (!isObject(feed)) {
+    fail('feed', 'must be a JSON object')
+    return errors
+  }
+  checkObjectKeys(feed, 'feed', new Set(['spec', 'publisher', 'generated', 'source', 'note', 'policy', 'models']))
+  if (feed.spec !== 'model-eol/0.1') fail('spec', `must be model-eol/0.1, got ${feed.spec}`)
+  if (!checkString(feed.publisher, 'publisher', MAX_IDENTIFIER_LENGTH) || !feed.publisher) fail('publisher', 'must be a non-empty string')
+  checkDateTime(feed.generated, 'generated')
+  checkUrl(feed.source, 'source')
+  if (feed.note !== undefined) checkString(feed.note, 'note', MAX_TEXT_LENGTH)
+  if (!Array.isArray(feed.models)) {
+    fail('models', 'must be an array')
+    return errors
+  }
+
+  if (feed.policy !== undefined && checkObjectKeys(feed.policy, 'policy', new Set(['min_notice_days', 'source']))) {
+    if (!Number.isSafeInteger(feed.policy.min_notice_days) || feed.policy.min_notice_days < 0) {
+      fail('policy.min_notice_days', 'must be a non-negative safe integer')
+    }
+    if (feed.policy.source === undefined) fail('policy.source', 'is required')
+    else checkUrl(feed.policy.source, 'policy.source')
+  }
+
+  const modelKeys = new Set()
+  const seenKeys = new Map()
+  const validDates = []
+  for (const [index, model] of feed.models.entries()) {
+    const at = `models[${index}]`
+    if (!checkObjectKeys(model, at, new Set([
+      'id', 'aliases', 'announced', 'shutdown', 'date_precision', 'replacement',
+      'replacement_options', 'replacement_note', 'notes', 'source', 'distributions',
+    ]))) continue
+
+    const idValid = checkIdentifier(model.id, `${at}.id`, true)
+    if (idValid) {
+      modelKeys.add(model.id)
+      const previous = seenKeys.get(model.id)
+      if (previous) fail(`${at}.id`, `duplicate id/alias "${model.id}" also used at ${previous}`)
+      else seenKeys.set(model.id, `${at}.id`)
+    }
+
+    if (model.aliases !== undefined) {
+      if (!Array.isArray(model.aliases) || model.aliases.length === 0) {
+        fail(`${at}.aliases`, 'must be a non-empty array')
+      } else {
+        for (const [aliasIndex, alias] of model.aliases.entries()) {
+          const aliasPath = `${at}.aliases[${aliasIndex}]`
+          if (!checkIdentifier(alias, aliasPath, true)) continue
+          modelKeys.add(alias)
+          const previous = seenKeys.get(alias)
+          if (previous) fail(aliasPath, `duplicate id/alias "${alias}" also used at ${previous}`)
+          else seenKeys.set(alias, aliasPath)
+        }
+      }
+    }
+
+    const announcedValid = checkDate(model.announced, `${at}.announced`)
+    const shutdownValid = checkDate(model.shutdown, `${at}.shutdown`)
+    if (announcedValid && shutdownValid) validDates.push({ at, announced: model.announced, shutdown: model.shutdown })
+    if (model.date_precision !== undefined) {
+      if (typeof model.date_precision !== 'string' || !DATE_PRECISIONS.has(model.date_precision)) fail(`${at}.date_precision`, 'must be exact or earliest')
+    }
+    if (model.replacement !== undefined) checkIdentifier(model.replacement, `${at}.replacement`)
+    if (model.replacement_options !== undefined) {
+      if (!Array.isArray(model.replacement_options) || model.replacement_options.length === 0) {
+        fail(`${at}.replacement_options`, 'must be a non-empty array')
+      } else {
+        for (const [optionIndex, option] of model.replacement_options.entries()) {
+          checkIdentifier(option, `${at}.replacement_options[${optionIndex}]`, true)
+        }
+      }
+      if (model.replacement !== undefined) fail(at, 'replacement and replacement_options are mutually exclusive')
+    }
+    if (model.replacement_note !== undefined) checkString(model.replacement_note, `${at}.replacement_note`, MAX_TEXT_LENGTH)
+    if (model.notes !== undefined) checkString(model.notes, `${at}.notes`, MAX_TEXT_LENGTH)
+    checkUrl(model.source, `${at}.source`)
+    if (model.announced || model.shutdown) {
+      if (!(model.source || feed.source)) fail(at, 'dated entry needs a source (entry- or feed-level)')
+    }
+    if (model.distributions !== undefined) {
+      if (!Array.isArray(model.distributions)) {
+        fail(`${at}.distributions`, 'must be an array')
+      } else {
+        for (const [distributionIndex, distribution] of model.distributions.entries()) {
+          const dAt = `${at}.distributions[${distributionIndex}]`
+          if (!checkObjectKeys(distribution, dAt, new Set(['via', 'announced', 'shutdown', 'date_precision', 'status', 'source']))) continue
+          if (!checkString(distribution.via, `${dAt}.via`, MAX_IDENTIFIER_LENGTH) || !distribution.via) fail(`${dAt}.via`, 'must be a non-empty string')
+          const distributionAnnounced = checkDate(distribution.announced, `${dAt}.announced`)
+          const distributionShutdown = checkDate(distribution.shutdown, `${dAt}.shutdown`)
+          if (distributionAnnounced && distributionShutdown && distribution.shutdown < distribution.announced) fail(dAt, 'shutdown precedes announced')
+          if (distribution.date_precision !== undefined && (typeof distribution.date_precision !== 'string' || !DATE_PRECISIONS.has(distribution.date_precision))) fail(`${dAt}.date_precision`, 'must be exact or earliest')
+          if (distribution.status !== undefined && (typeof distribution.status !== 'string' || !DISTRIBUTION_STATUSES.has(distribution.status))) fail(`${dAt}.status`, 'has an unsupported status')
+          checkUrl(distribution.source, `${dAt}.source`)
+          if (distribution.shutdown && !(distribution.source || model.source || feed.source)) fail(dAt, 'dated distribution needs a source')
+        }
+      }
+    }
+  }
+
+  for (const date of validDates) {
+    if (date.shutdown < date.announced) fail(date.at, 'shutdown precedes announced')
+  }
+  for (const [index, model] of feed.models.entries()) {
+    if (!isObject(model) || typeof model.replacement !== 'string' || !MODEL_ID_PATTERN.test(model.replacement)) continue
+    if (!modelKeys.has(model.replacement)) fail(`models[${index}].replacement`, `does not resolve to an id or alias in this feed: ${model.replacement}`)
+  }
+  return errors
+}
+
+export const assertValidFeed = (feed, label = 'feed') => {
+  const errors = validateFeed(feed)
+  if (errors.length) {
+    const models = Array.isArray(feed?.models) ? feed.models : []
+    const lines = errors.map(error => {
+      const modelIndex = error.path.match(/^models\[(\d+)\]/)?.[1]
+      const modelId = modelIndex !== undefined ? models[Number(modelIndex)]?.id : models.find(model => model?.id)?.id
+      const context = typeof modelId === 'string' ? ` model ${modelId}` : ''
+      return `${label}${context}: ${error.path}: ${error.message}`
+    })
+    throw new Error(lines.join('\n'))
+  }
+  return feed
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "model-eol",
+  "version": "0.2.1",
+  "description": "A machine-readable deprecation feed format for AI models, plus a zero-dependency checker and inventory CLI.",
+  "type": "module",
+  "bin": {
+    "model-eol": "check.mjs"
+  },
+  "scripts": {
+    "test": "node test/run.mjs && node refresh/test/run.mjs && node bot/test/run.mjs && node scripts/test-feed-changelog.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thossullivan/model-eol.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thossullivan/model-eol/issues"
+  },
+  "homepage": "https://github.com/thossullivan/model-eol",
+  "license": "MIT",
+  "author": "Tom Sullivan",
+  "keywords": [
+    "model deprecation",
+    "eol",
+    "llm",
+    "dependabot",
+    "sbom",
+    "model lifecycle",
+    "ai models",
+    "software bill of materials"
+  ],
+  "files": [
+    "check.mjs",
+    "lib/",
+    "feeds/",
+    "schema/",
+    "SPEC.md",
+    "README.md",
+    "LICENSE",
+    "action.yml"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/schema/model-eol.alert.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.invalid/model-eol/0.1/alert.schema.json",
+  "title": "model-eol alert output",
+  "description": "Machine-readable alert payload emitted by `model-eol alert --json`. Draft 0.1 - the $id is a placeholder until the repo is public.",
+  "type": "object",
+  "required": ["schema", "generated", "threshold_days", "scope", "scan_notes", "errors", "warnings"],
+  "properties": {
+    "schema": { "const": "model-eol/alert@0.1" },
+    "generated": { "type": "string", "format": "date-time" },
+    "threshold_days": { "type": "number" },
+    "distributor": { "type": ["string", "null"] },
+    "scope": { "enum": ["all", "direct"] },
+    "scan_notes": { "type": "array", "items": { "$ref": "model-eol.inventory.schema.json#/definitions/scanNote" } },
+    "errors": { "type": "array", "items": { "$ref": "model-eol.inventory.schema.json#/definitions/modelReference" } },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "$ref": "model-eol.inventory.schema.json#/definitions/modelReference" },
+          { "$ref": "model-eol.inventory.schema.json#/definitions/candidateReference" },
+          { "$ref": "model-eol.inventory.schema.json#/definitions/integrationHint" }
+        ]
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/model-eol.bot-config.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.invalid/model-eol/0.1/bot-config.schema.json",
+  "title": "model-eol bot configuration",
+  "description": "Optional .model-eol.json configuration for the zero-dependency GitHub bot adapter.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "days": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 90,
+      "description": "Open migration work for models retiring within this many days."
+    },
+    "scope": {
+      "enum": ["direct", "all"],
+      "default": "direct",
+      "description": "Use direct API references only, or include generic model references."
+    },
+    "via": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Optional distributor lifecycle clock, such as azure-ai-foundry."
+    },
+    "feeds": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allow_vendored_fallback": {
+          "type": "boolean",
+          "default": false,
+          "description": "Continue with vendored feeds after a remote feed failure in degraded report-only mode."
+        }
+      },
+      "default": { "allow_vendored_fallback": false }
+    },
+    "ignore": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "models": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": [],
+          "description": "Canonical IDs or aliases to ignore. A canonical ID ignores all of its aliases."
+        },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": [],
+          "description": "Repo-relative simple globs supporting *, **, and ?."
+        }
+      },
+      "default": { "models": [], "paths": [] }
+    },
+    "issues": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Maintain GitHub issues for non-patchable actionable findings."
+        }
+      },
+      "default": { "enabled": true }
+    },
+    "eval": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "type": ["string", "null"],
+          "default": null,
+          "description": "Opt-in command run in the temporary clone for changed patches."
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 600000
+        },
+        "max_report_bytes": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 65536
+        },
+        "pass_env": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": [],
+          "description": "Environment variable names explicitly passed to the eval command."
+        }
+      },
+      "default": { "command": null, "timeout_ms": 600000, "max_report_bytes": 65536, "pass_env": [] }
+    }
+  },
+  "default": {
+    "days": 90,
+    "scope": "direct",
+    "via": null,
+    "feeds": { "allow_vendored_fallback": false },
+    "ignore": { "models": [], "paths": [] },
+    "issues": { "enabled": true },
+    "eval": { "command": null, "timeout_ms": 600000, "max_report_bytes": 65536, "pass_env": [] }
+  }
+}

package/schema/model-eol.inventory.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.invalid/model-eol/0.1/inventory.schema.json",
+  "title": "model-eol inventory output",
+  "description": "Machine-readable repository inventory emitted by `model-eol inventory --json`. Draft 0.1 - the $id is a placeholder until the repo is public.",
+  "type": "object",
+  "required": ["schema", "generated", "threshold_days", "scope", "targets", "scanned_files", "scan_notes", "summary", "model_references", "candidate_model_references", "integration_hints"],
+  "properties": {
+    "schema": { "const": "model-eol/inventory@0.1" },
+    "generated": { "type": "string", "format": "date-time" },
+    "threshold_days": { "type": "number" },
+    "distributor": { "type": ["string", "null"] },
+    "scope": { "enum": ["all", "direct"] },
+    "targets": { "type": "array", "items": { "type": "string" } },
+    "scanned_files": { "type": "integer", "minimum": 0 },
+    "scan_notes": { "type": "array", "items": { "$ref": "#/definitions/scanNote" } },
+    "summary": {
+      "type": "object",
+      "required": ["model_references", "candidate_model_references", "integration_hints", "retired_or_retiring", "cloud_or_gateway_hints"],
+      "properties": {
+        "model_references": { "type": "integer", "minimum": 0 },
+        "candidate_model_references": { "type": "integer", "minimum": 0 },
+        "integration_hints": { "type": "integer", "minimum": 0 },
+        "retired_or_retiring": { "type": "integer", "minimum": 0 },
+        "cloud_or_gateway_hints": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "model_references": { "type": "array", "items": { "$ref": "#/definitions/modelReference" } },
+    "candidate_model_references": { "type": "array", "items": { "$ref": "#/definitions/candidateReference" } },
+    "integration_hints": { "type": "array", "items": { "$ref": "#/definitions/integrationHint" } }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "usage": { "enum": ["direct-api", "cloud-provider", "gateway", "model-reference"] },
+    "confidence": { "enum": ["high", "medium", "low"] },
+    "status": { "enum": ["retired", "retiring", "scheduled", "watch", "ok"] },
+    "location": {
+      "type": "object",
+      "required": ["file", "line"],
+      "properties": {
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "modelReference": {
+      "allOf": [
+        { "$ref": "#/definitions/location" },
+        {
+          "type": "object",
+          "required": ["kind", "matched", "id", "publisher", "usage", "resolved_provider", "confidence", "evidence", "status", "shutdown", "via", "days", "safe_until", "replacement", "source"],
+          "properties": {
+            "kind": { "const": "model-reference" },
+            "matched": { "type": "string" },
+            "id": { "type": "string" },
+            "publisher": { "type": "string" },
+            "usage": { "$ref": "#/definitions/usage" },
+            "resolved_provider": { "type": "string" },
+            "confidence": { "$ref": "#/definitions/confidence" },
+            "evidence": { "type": "string" },
+            "status": { "$ref": "#/definitions/status" },
+            "shutdown": { "type": ["string", "null"] },
+            "via": { "type": ["string", "null"] },
+            "days": { "type": ["integer", "null"] },
+            "safe_until": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+            "replacement": { "type": ["string", "null"] },
+            "source": { "type": ["string", "null"] },
+            "policy": {
+              "type": ["object", "null"],
+              "required": ["min_notice_days", "source"],
+              "properties": {
+                "min_notice_days": { "type": "integer", "minimum": 0 },
+                "source": { "type": "string", "format": "uri" }
+              },
+              "additionalProperties": false
+            },
+            "feed_generated": { "type": ["string", "null"], "format": "date-time" }
+          }
+        }
+      ]
+    },
+    "candidateReference": {
+      "allOf": [
+        { "$ref": "#/definitions/location" },
+        {
+          "type": "object",
+          "required": ["kind", "matched", "usage", "resolved_provider", "confidence", "evidence", "reason"],
+          "properties": {
+            "kind": { "const": "candidate-model-reference" },
+            "matched": { "type": "string" },
+            "usage": { "$ref": "#/definitions/usage" },
+            "resolved_provider": { "type": "string" },
+            "confidence": { "$ref": "#/definitions/confidence" },
+            "evidence": { "type": "string" },
+            "reason": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "integrationHint": {
+      "allOf": [
+        { "$ref": "#/definitions/location" },
+        {
+          "type": "object",
+          "required": ["kind", "usage", "provider", "matched", "evidence"],
+          "properties": {
+            "kind": { "const": "integration-hint" },
+            "usage": { "enum": ["direct-api", "cloud-provider", "gateway"] },
+            "provider": { "type": "string" },
+            "matched": { "type": "string" },
+            "evidence": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "scanNote": {
+      "type": "object",
+      "required": ["reason"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1 },
+        "file": { "type": "string" },
+        "message": { "type": "string" },
+        "bytes": { "type": "integer", "minimum": 0 },
+        "limit_bytes": { "type": "integer", "minimum": 0 },
+        "limit_files": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/model-eol.plan.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.invalid/model-eol/0.1/plan.schema.json",
+  "title": "model-eol migration plan",
+  "description": "Deterministic, hash-guarded migration plan emitted by `model-eol plan`. Draft 0.1 - the $id is a placeholder until the repo is public.",
+  "type": "object",
+  "required": ["plan_schema", "generated", "threshold_days", "via", "scan_notes", "items", "issues"],
+  "properties": {
+    "plan_schema": { "const": "model-eol.plan/0.1" },
+    "generated": { "type": "string", "format": "date-time" },
+    "threshold_days": { "type": "number" },
+    "via": { "type": ["string", "null"] },
+    "scan_notes": { "type": "array", "items": { "$ref": "#/definitions/scanNote" } },
+    "items": { "type": "array", "items": { "$ref": "#/definitions/item" } },
+    "issues": { "type": "array", "items": { "$ref": "#/definitions/issue" } }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "item": {
+      "type": "object",
+      "required": ["file", "line", "occurrence", "matched", "expected_line_sha256", "id", "publisher", "replacement", "shutdown", "days", "status", "sources", "notes"],
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "line": { "type": "integer", "minimum": 1 },
+        "occurrence": { "type": "integer", "minimum": 0 },
+        "matched": { "type": "string", "minLength": 1 },
+        "expected_line_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "id": { "type": "string", "minLength": 1 },
+        "publisher": { "type": "string", "minLength": 1 },
+        "replacement": { "type": "string", "minLength": 1 },
+        "shutdown": { "type": "string" },
+        "days": { "type": "integer" },
+        "status": { "enum": ["retired", "retiring"] },
+        "sources": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "issue": {
+      "type": "object",
+      "required": ["file", "line", "reason"],
+      "properties": {
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "matched": { "type": "string" },
+        "id": { "type": "string" },
+        "publisher": { "type": "string" },
+        "usage": { "enum": ["direct-api", "cloud-provider", "gateway", "model-reference"] },
+        "confidence": { "enum": ["high", "medium", "low"] },
+        "status": { "enum": ["retired", "retiring", "scheduled", "watch", "ok"] },
+        "shutdown": { "type": ["string", "null"] },
+        "via": { "type": ["string", "null"] },
+        "days": { "type": ["integer", "null"] },
+        "replacement": { "type": ["string", "null"] },
+        "replacement_options": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" }
+        },
+        "replacement_note": { "type": "string" },
+        "provider": { "type": "string" },
+        "reason": { "type": "string", "minLength": 1 },
+        "sources": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "scanNote": {
+      "type": "object",
+      "required": ["reason"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1 },
+        "file": { "type": "string" },
+        "message": { "type": "string" },
+        "bytes": { "type": "integer", "minimum": 0 },
+        "limit_bytes": { "type": "integer", "minimum": 0 },
+        "limit_files": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    }
+  }
+}