{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://apigenie.pl/schemas/apigenie-window-report.json",
  "title": "apigenie window --format json",
  "description": "The report of `apigenie window --format json` (experimental): the support window of an OpenAPI document, what ended it, the version annotations written, and the self-check of every version of the window. Adding members keeps formatVersion; removing a member or changing its meaning or type increments it.",
  "type": "object",
  "required": ["formatVersion", "result", "document", "output", "window", "end", "annotations", "dropped", "annotationIssues", "checks"],
  "properties": {
    "formatVersion": {
      "description": "The version of this format.",
      "const": 1
    },
    "result": {
      "description": "`annotated` when every self-check passed, every annotation names a version clients can place, and the document was written (exit status 0); `failed` otherwise, and nothing was written (exit status 2).",
      "enum": ["annotated", "failed"]
    },
    "document": { "type": "string", "description": "SPEC, as given." },
    "output": {
      "description": "Where the annotated document went: the file of --out, an empty string for the standard output, null when nothing was written.",
      "type": ["string", "null"]
    },
    "window": {
      "type": "object",
      "required": ["from", "to", "versions", "revisions"],
      "properties": {
        "from": { "$ref": "#/$defs/revision", "description": "The oldest revision of the window." },
        "to": { "$ref": "#/$defs/revision", "description": "The newest revision: SPEC." },
        "versions": {
          "description": "The versions of the window, oldest first, as written to info.x-apigenie-versions.",
          "type": "array",
          "items": { "type": "string" }
        },
        "revisions": {
          "description": "The revisions of the window, oldest first.",
          "type": "array",
          "items": { "$ref": "#/$defs/revision" }
        }
      }
    },
    "end": {
      "description": "What ended the window, looking back from the newest revision.",
      "type": "object",
      "required": ["reason", "changes"],
      "properties": {
        "reason": {
          "description": "`history-start`: the oldest revision is in the window; `breaking`: the change into the window's oldest revision breaks clients; `blocking`: it has a change no annotation carries to older servers; `same-version`: the revision before has the same info.version and differs in what the annotations say; `no-version`: the revision before has no info.version.",
          "enum": ["history-start", "breaking", "blocking", "same-version", "no-version"]
        },
        "before": { "$ref": "#/$defs/revision", "description": "The revision before the window; absent for history-start." },
        "changes": {
          "description": "The breaking or blocking changes that ended the window.",
          "type": "array",
          "items": { "$ref": "#/$defs/change" }
        }
      }
    },
    "annotations": {
      "description": "The annotations written, oldest version first.",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["annotation", "element", "version", "location"],
        "properties": {
          "annotation": {
            "enum": ["x-apigenie-added", "x-apigenie-removed", "x-apigenie-made-optional", "x-apigenie-made-required", "x-apigenie-renamed-from", "x-apigenie-type-changed-from", "x-apigenie-enum-added"]
          },
          "element": { "type": "string", "description": "The JSON pointer (with #) of the annotated element in the written document." },
          "version": { "type": "string" },
          "value": { "type": "string", "description": "The enum value of x-apigenie-enum-added; present for that annotation only, even when the value is empty." },
          "location": { "type": "string", "description": "The location of the change the annotation comes from, as diff reports it." }
        }
      }
    },
    "dropped": {
      "description": "Annotations of SPEC taken out: their versions were listed in its info.x-apigenie-versions and are older than the window now.",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["annotation", "element", "version"],
        "properties": {
          "annotation": {
            "enum": ["x-apigenie-added", "x-apigenie-removed", "x-apigenie-made-optional", "x-apigenie-made-required", "x-apigenie-renamed-from", "x-apigenie-type-changed-from", "x-apigenie-enum-added"]
          },
          "element": { "type": "string", "description": "The JSON pointer (with #) of the element in SPEC." },
          "version": { "type": "string" },
          "value": { "type": "string", "description": "The enum value of x-apigenie-enum-added." }
        }
      }
    },
    "annotationIssues": {
      "description": "What the version-annotations-valid lint rule reports on the annotated document. An issue that fails the run names a version clients can't place: they would ignore the annotation.",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["element", "reason", "message", "fails"],
        "properties": {
          "element": { "type": "string", "description": "The JSON pointer (with #) of the value." },
          "reason": { "enum": ["malformed", "unknown-version", "newer-than-document", "still-present", "misplaced", "bad-version-list"] },
          "message": { "type": "string" },
          "fails": { "type": "boolean" }
        }
      }
    },
    "checks": {
      "description": "The self-check of every revision of the window, oldest first: the annotated document projected to its version, diffed against the revision.",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["revision", "status", "differences"],
        "properties": {
          "revision": { "$ref": "#/$defs/revision" },
          "status": { "enum": ["ok", "failed"] },
          "differences": {
            "type": "array",
            "items": { "$ref": "#/$defs/change" }
          }
        }
      }
    }
  },
  "$defs": {
    "revision": {
      "type": "object",
      "required": ["label", "id", "version"],
      "properties": {
        "label": { "type": "string", "description": "The tag, the short commit id, or the file." },
        "id": { "type": "string", "description": "The commit id, or the file." },
        "version": { "type": "string", "description": "Its info.version." }
      }
    },
    "change": {
      "type": "object",
      "required": ["location", "change"],
      "properties": {
        "location": { "type": "string" },
        "change": { "type": "string", "description": "The change as diff describes it." },
        "why": { "type": "string" }
      }
    }
  }
}
