{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/blinkpdf-io/json-schema/blinkpdf-io-render-diagnostic-schema.json",
  "title": "Render.Diagnostic",
  "description": "One entry of the actionable render diagnostic list, the element shape of the `X-Render-Diagnostics` array and of the validate `diagnostics` array: an occurrence, or an omission (it carries `omitted`). The list shows at most 10 occurrences of each code and severity, in wire order (errors, then warns, then infos; source order within each), and counts the rest of that code and severity in one omission, so its size follows the codes a document reports, not the document's size.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/blinkpdf-io-stamp-api-openapi.yml#/components/schemas/Render.Diagnostic",
  "anyOf": [
    {
      "additionalProperties": false,
      "description": "One occurrence: what the document reported at one site.",
      "type": "object",
      "required": [
        "severity",
        "code",
        "impact",
        "message",
        "help"
      ],
      "properties": {
        "severity": {
          "description": "`error` (content will be missing, e.g. an image that will not decode or fetch, or a missing glyph), `warn` (output altered or a conformance note), `info` (advisory such as a remote source or an auto-fit).",
          "type": "string",
          "enum": [
            "info",
            "warn",
            "error"
          ]
        },
        "code": {
          "description": "Stable diagnostic code (e.g. `image-fetch-failed`, `title-omitted`, `glyph-component-dropped`, `table-row-split-forced`).",
          "type": "string"
        },
        "impact": {
          "description": "What it changed in the PDF against the request, graded by BlinkPDF so no client keeps a table of codes: `content` (part of what was asked is missing, cut off, covered, or may not be read), `appearance` (everything asked is painted and readable, only its look or navigation differs: another face or cut, a smaller size, another place or page break, a decoration, link, or bookmark dropped), `none` (an advisory: the PDF is as asked). A code BlinkPDF adds later comes graded too.",
          "type": "string",
          "enum": [
            "none",
            "appearance",
            "content"
          ]
        },
        "message": {
          "description": "Human-readable, agent-actionable explanation.",
          "type": "string"
        },
        "resource": {
          "description": "Locator: the image URL or source snippet windowed to ~80 chars with a middle ellipsis (never the full asset), or for a compose layout warning the RFC 6901 fragment pointer (`#/sections/…`) of the node it names, verbatim. Absent on document-level diagnostics.",
          "type": "string"
        },
        "position": {
          "additionalProperties": false,
          "description": "Where the Markdown source the diagnostic is about starts: tells apart two occurrences that share a `resource` (two images with one URL). Absent when no Markdown span locates it: a document-level note, a furniture or compose image, or a diagnostic located by a request pointer.",
          "type": "object",
          "required": [
            "line",
            "column"
          ],
          "properties": {
            "line": {
              "minimum": 1,
              "description": "1-based line where the located Markdown starts.",
              "type": "integer"
            },
            "column": {
              "minimum": 1,
              "description": "1-based column, in UTF-16 code units, where the located Markdown starts.",
              "type": "integer"
            }
          }
        },
        "httpStatus": {
          "description": "HTTP status when the diagnostic stems from a remote fetch failure (`image-fetch-failed`).",
          "type": "number"
        },
        "scaleFactor": {
          "description": "Uniform downscale factor in `(0, 1)` for `image-fit-to-column`; absent otherwise.",
          "type": "number"
        },
        "effectiveDpi": {
          "description": "Effective print resolution in DPI for `image-fit-to-column` / `image-low-resolution`; absent otherwise.",
          "type": "number"
        },
        "help": {
          "description": "Reference doc deep-link for the diagnostic family (a `blinkpdf://reference/…` URI).",
          "type": "string"
        }
      }
    },
    {
      "additionalProperties": false,
      "description": "The count of the occurrences of one code and severity the list does not show, placed right after the last one it shows.",
      "type": "object",
      "required": [
        "severity",
        "code",
        "impact",
        "message",
        "help",
        "omitted"
      ],
      "properties": {
        "severity": {
          "description": "`error` (content will be missing, e.g. an image that will not decode or fetch, or a missing glyph), `warn` (output altered or a conformance note), `info` (advisory such as a remote source or an auto-fit).",
          "type": "string",
          "enum": [
            "info",
            "warn",
            "error"
          ]
        },
        "code": {
          "description": "Stable diagnostic code (e.g. `image-fetch-failed`, `title-omitted`, `glyph-component-dropped`, `table-row-split-forced`).",
          "type": "string"
        },
        "impact": {
          "description": "What it changed in the PDF against the request, graded by BlinkPDF so no client keeps a table of codes: `content` (part of what was asked is missing, cut off, covered, or may not be read), `appearance` (everything asked is painted and readable, only its look or navigation differs: another face or cut, a smaller size, another place or page break, a decoration, link, or bookmark dropped), `none` (an advisory: the PDF is as asked). A code BlinkPDF adds later comes graded too.",
          "type": "string",
          "enum": [
            "none",
            "appearance",
            "content"
          ]
        },
        "message": {
          "description": "Agent-actionable sentence: how many more occurrences of `code` the document reported than the list shows, and how to see them.",
          "type": "string"
        },
        "help": {
          "description": "Reference doc deep-link for the diagnostic family (a `blinkpdf://reference/…` URI).",
          "type": "string"
        },
        "omitted": {
          "minimum": 1,
          "description": "Occurrences of `code` at `severity` past the first 10 the list shows; they count toward the render status and the document `impact` like the listed ones.",
          "type": "integer"
        }
      }
    }
  ]
}