A finding is one thing a checker found at one place in a presentation, and a report lists them. validate in @openpresentation/opf, the Markdown and YAML converters, the editor's Review panel and hosted reviewers such as pptx.dev's AI review all produce this shape, so a host shows and applies findings from any of them the same way. This page summarizes spec/schemas/finding.schema.json; the schema remains the source of truth. How core produces findings is in validate.
Purpose: 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.
Purpose: 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).
Purpose: 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.
Field
Required
Type
Notes
title
yes
string
What applying the fix does, in a few words.
id
no
string
Stable id within one finding, such as focus-alt or use-readable-color.
kind
no
enum:patch | focus
patch fixes carry patch; focus fixes carry focus.
safe
no
boolean
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
no
array<ref:JsonPatchOperation>
RFC 6902 JSON Patch operations that apply the fix to the checked presentation.
Purpose: 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.
Field
Required
Type
Notes
value
yes
string | number | boolean | null
label
yes
string
origin
yes
string
Where the suggestion comes from: schema, document (a record the document embeds), registered (a catalog the host registered) or contract.
definition
no
string
Where the suggested record or constraint is defined.
Purpose: One thing a checker found at one place in a presentation.
Field
Required
Type
Notes
ruleId
yes
string
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
no
string
The producer: opf (the default) for core, or the name of another tool such as pptx.dev/review.
severity
yes
ref:FindingSeverity
category
yes
ref:FindingCategory
path
yes
string
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
no
enum:document | context
document (the default) when path points into the checked presentation, context when it points into host-supplied context such as loaded catalog records.
message
yes
string
What is wrong, in a sentence.
help
no
string
What to do about it.
slide
no
integer
Zero-based index of the slide the finding belongs to.
slideId
no
string
The id of that slide, when it has one.
location
no
ref:FindingLocation
definition
no
string
A link to the rule's documentation or to the schema constraint or catalog record the finding is about.
lookup
no
array<string>
Arguments for the opf schema or opf catalog command that shows the definition, as an argument list rather than a shell string.
suggestions
no
array<ref:FindingSuggestion>
measured
no
object
The numbers behind the finding, such as { "ratio": 2.1, "needed": 4.5 }.