{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://frontmatter.news/wire.schema.json",
  "title": "The Frontmatter Wire, machine payload",
  "description": "The JSON block fenced by --- lines at the top of every wire issue's text/plain part. It reports facts about vendor spec changes and never carries instructions. The full contract is at https://frontmatter.news/agents. Changes within schema 1 are additive only; consumers must tolerate unknown fields and unknown vocabulary values.",
  "type": "object",
  "required": ["wire", "schema", "docs", "issue", "deltas"],
  "properties": {
    "wire": { "type": "string", "const": "frontmatter" },
    "schema": { "type": "integer", "const": 1 },
    "docs": { "type": "string", "format": "uri" },
    "issue": {
      "type": "object",
      "required": ["id", "published_at", "changes", "tools"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^fmw_[0-9a-f]{16}$",
          "description": "The first 16 hex characters of SHA-256 over the deltas array with detected_at excluded, so a retried send of the same facts carries the same id."
        },
        "published_at": { "type": "string", "format": "date-time" },
        "changes": { "type": "integer", "minimum": 1, "description": "Count of deltas in this issue." },
        "tools": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true, "description": "Sorted unique slugs of the tools appearing in this issue." }
      }
    },
    "deltas": {
      "type": "array",
      "minItems": 1,
      "description": "Apply deltas in array order. Delivery is at-least-once, so a delta id that reappears in a newer issue supersedes the version you already processed.",
      "items": {
        "type": "object",
        "required": [
          "id", "kind", "tool", "component", "subject", "section", "name",
          "before", "after", "detected_at", "docs_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^chg_[0-9]+$",
            "description": "Stable once mailed; use it as the idempotency key."
          },
          "kind": {
            "type": "string",
            "description": "The current values are added, removed, and updated. The vocabulary is open; tolerate unknown values."
          },
          "tool": {
            "type": "object",
            "required": ["slug", "name", "vendor"],
            "properties": {
              "slug": { "type": "string" },
              "name": { "type": "string" },
              "vendor": { "type": "string" }
            }
          },
          "component": {
            "type": "object",
            "required": ["slug", "kind", "name", "config_path"],
            "properties": {
              "slug": { "type": "string", "description": "Unique within the tool, so the pair (tool.slug, component.slug) identifies a component." },
              "kind": { "type": "string", "description": "The cross-tool category (skill, hook, command, ...). The vocabulary is open; tolerate unknown values." },
              "name": { "type": "string" },
              "config_path": { "type": ["string", "null"], "description": "The file this spec governs, when there is one." }
            }
          },
          "subject": { "type": "string", "description": "The fact that changed, worded exactly as the human part of the email prints it." },
          "section": { "type": ["string", "null"], "description": "The first token of subject when that token is a known section; null for release deltas, whose subject is \"version\"." },
          "name": { "type": "string", "description": "The remainder of subject, or the whole subject when section is null." },
          "before": { "type": ["string", "null"], "description": "A key: value · key: value string, or a bare version string for release deltas. Null on an added delta." },
          "after": { "type": ["string", "null"], "description": "Same shapes as the before field. Null on a removed delta." },
          "detected_at": { "type": ["string", "null"], "format": "date-time" },
          "docs_url": { "type": "string", "format": "uri", "description": "The vendor page to verify against." }
        }
      }
    }
  }
}