Validation results

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openpresentation.org/schema/opf-finding/v1",
  "title": "Validation results",
  "description": "Errors, warnings and suggested fixes.",
  "type": "object",
  "required": [
    "valid",
    "findings",
    "counts"
  ],
  "properties": {
    "valid": {
      "type": "boolean",
      "description": "True when no finding has severity `error`."
    },
    "findings": {
      "type": "array",
      "description": "Every finding, in report order.",
      "items": {
        "$ref": "#/$defs/Finding"
      }
    },
    "counts": {
      "type": "object",
      "description": "How many findings each severity has.",
      "required": [
        "error",
        "warning",
        "info"
      ],
      "additionalProperties": false,
      "properties": {
        "error": {
          "type": "integer",
          "minimum": 0
        },
        "warning": {
          "type": "integer",
          "minimum": 0
        },
        "info": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  },
  "$defs": {
    "FindingSeverity": {
      "type": "string",
      "enum": [
        "error",
        "warning",
        "info"
      ],
      "description": "`error` makes a report invalid. `warning` is a problem the author should fix. `info` is advisory."
    },
    "FindingCategory": {
      "description": "What kind of question the finding answers. Core uses `format` (is it well-formed OPF), `references` (does everything it points at resolve), `policy` (host house rules), `accessibility`, `layout` (will it present as authored) and `content` (is anything left unfinished). Other producers may use their own category names, such as `narrative` or `audience-fit`.",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "format",
            "references",
            "policy",
            "accessibility",
            "layout",
            "content"
          ]
        },
        {
          "type": "string",
          "minLength": 1
        }
      ]
    },
    "FindingLocation": {
      "type": "object",
      "description": "A range in the checked text: UTF-16 offset and length from the start, and the one-based line and column of the start. Present when the finding was produced from text (JSON, Markdown or YAML).",
      "required": [
        "offset",
        "length",
        "line",
        "column"
      ],
      "additionalProperties": false,
      "properties": {
        "offset": {
          "type": "integer",
          "minimum": 0
        },
        "length": {
          "type": "integer",
          "minimum": 0
        },
        "line": {
          "type": "integer",
          "minimum": 1
        },
        "column": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "JsonPatchOperation": {
      "description": "One RFC 6902 JSON Patch operation. Paths are JSON Pointers into the checked presentation.",
      "oneOf": [
        {
          "type": "object",
          "required": [
            "op",
            "path",
            "value"
          ],
          "additionalProperties": false,
          "properties": {
            "op": {
              "type": "string",
              "enum": [
                "add",
                "replace",
                "test"
              ]
            },
            "path": {
              "type": "string"
            },
            "value": {}
          }
        },
        {
          "type": "object",
          "required": [
            "op",
            "path"
          ],
          "additionalProperties": false,
          "properties": {
            "op": {
              "type": "string",
              "const": "remove"
            },
            "path": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "op",
            "from",
            "path"
          ],
          "additionalProperties": false,
          "properties": {
            "op": {
              "type": "string",
              "enum": [
                "move",
                "copy"
              ]
            },
            "from": {
              "type": "string"
            },
            "path": {
              "type": "string"
            }
          }
        }
      ]
    },
    "FindingFocus": {
      "type": "object",
      "description": "The field an author has to fill in, for a fix that cannot be written as a patch.",
      "required": [
        "path",
        "field"
      ],
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string",
          "description": "JSON Pointer of the field to edit."
        },
        "field": {
          "type": "string",
          "description": "What the field is, such as `alt`, `title`, `text`, `link`, `language` or `fontSize`."
        },
        "value": {
          "type": [
            "string",
            "number",
            "boolean",
            "null",
            "array",
            "object"
          ],
          "description": "The field's current value, when it has one."
        }
      }
    },
    "FindingFix": {
      "type": "object",
      "description": "A suggested repair. Core never applies it: the host shows it and applies it through its own undoable edit path. A `patch` fix carries JSON Patch operations; a `focus` fix only names the field the author has to fill in.",
      "required": [
        "title"
      ],
      "additionalProperties": false,
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "description": "What applying the fix does, in a few words."
        },
        "id": {
          "type": "string",
          "description": "Stable id within one finding, such as `focus-alt` or `use-readable-color`."
        },
        "kind": {
          "type": "string",
          "enum": [
            "patch",
            "focus"
          ],
          "default": "patch",
          "description": "`patch` fixes carry `patch`; `focus` fixes carry `focus`."
        },
        "safe": {
          "type": "boolean",
          "description": "True when applying the fix cannot change what the content says or how it looks beyond the repair, such as switching a failing colour to the one the theme chose. False fixes need a deliberate choice."
        },
        "patch": {
          "type": "array",
          "description": "RFC 6902 JSON Patch operations that apply the fix to the checked presentation.",
          "items": {
            "$ref": "#/$defs/JsonPatchOperation"
          }
        },
        "focus": {
          "$ref": "#/$defs/FindingFocus"
        }
      }
    },
    "FindingSuggestion": {
      "type": "object",
      "description": "A value the author could use instead, such as a catalog record that exists. Suggestions name records actually present in the checked context and never replace authored values silently.",
      "required": [
        "value",
        "label",
        "origin"
      ],
      "additionalProperties": false,
      "properties": {
        "value": {
          "type": [
            "string",
            "number",
            "boolean",
            "null"
          ]
        },
        "label": {
          "type": "string"
        },
        "origin": {
          "type": "string",
          "description": "Where the suggestion comes from: `schema`, `document` (a record the document embeds), `registered` (a catalog the host registered) or `contract`."
        },
        "definition": {
          "type": "string",
          "description": "Where the suggested record or constraint is defined."
        }
      }
    },
    "ValidationIssue": {
      "type": "object",
      "description": "The raw schema or semantic issue behind a finding, kept with every union alternative so a host can inspect the exact constraint.",
      "required": [
        "path",
        "message",
        "keyword",
        "schemaPath",
        "params"
      ],
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "keyword": {
          "type": "string",
          "description": "The JSON Schema keyword that failed, or `opf` for a rule the schema cannot express."
        },
        "schemaPath": {
          "type": "string"
        },
        "params": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "Finding": {
      "type": "object",
      "description": "One thing a checker found at one place in a presentation.",
      "required": [
        "ruleId",
        "severity",
        "category",
        "path",
        "message"
      ],
      "additionalProperties": false,
      "properties": {
        "ruleId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$",
          "description": "Stable `<producer>/<rule>` id, such as `opf/text-contrast` for core or `pptx.dev/narrative-gap` for a hosted reviewer. Ids do not change between releases."
        },
        "source": {
          "type": "string",
          "description": "The producer: `opf` (the default) for core, or the name of another tool such as `pptx.dev/review`."
        },
        "severity": {
          "$ref": "#/$defs/FindingSeverity"
        },
        "category": {
          "$ref": "#/$defs/FindingCategory"
        },
        "path": {
          "type": "string",
          "description": "JSON Pointer to the value the finding is about, such as `/slides/4/title`. Empty for the whole document, or for a value in a supplied context such as a loaded catalog."
        },
        "scope": {
          "type": "string",
          "enum": [
            "document",
            "context"
          ],
          "description": "`document` (the default) when `path` points into the checked presentation, `context` when it points into host-supplied context such as loaded catalog records."
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "description": "What is wrong, in a sentence."
        },
        "help": {
          "type": "string",
          "description": "What to do about it."
        },
        "slide": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index of the slide the finding belongs to."
        },
        "slideId": {
          "type": "string",
          "description": "The id of that slide, when it has one."
        },
        "location": {
          "$ref": "#/$defs/FindingLocation"
        },
        "definition": {
          "type": "string",
          "description": "A link to the rule's documentation or to the schema constraint or catalog record the finding is about."
        },
        "lookup": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Arguments for the `opf schema` or `opf catalog` command that shows the definition, as an argument list rather than a shell string."
        },
        "suggestions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FindingSuggestion"
          }
        },
        "measured": {
          "type": "object",
          "description": "The numbers behind the finding, such as `{ \"ratio\": 2.1, \"needed\": 4.5 }`.",
          "additionalProperties": {
            "type": [
              "number",
              "string",
              "boolean",
              "null"
            ]
          }
        },
        "fixes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FindingFix"
          }
        },
        "validation": {
          "$ref": "#/$defs/ValidationIssue"
        }
      }
    }
  }
}