JSON reports: ascribe report
The JSON Schema of what ascribe report writes with --format json.
For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.
The JSON Schema of what ascribe report writes with --format json. The document follows the rules of the JSON report contract.
ascribe report
The fields of schemas/report.schema.json:
ReportReport: What ascribe report --format json writes: one document, whatever the outcome. A reader ignores fields it doesn’t know.
| Field | Type | Required | Nullable | Description |
|---|---|---|---|---|
schema_version |
integer |
yes | no | The version of this schema. It changes only when a field is removed or changes meaning. |
ascribe_version |
string |
yes | no | The release of Ascribe that wrote it, as 0.4.5. |
error |
string |
yes | yes | Why the report couldn’t be made (exit code 2), or null. When it isn’t null, no section is there. |
sections |
string[] |
yes | no | The sections asked for, in the order the report has them: problems, inventory, builds, pages, links, delivery. |
builds_checked |
string[] |
yes | no | The builds problems checked and builds and pages report on, in ascribe.toml’s order. |
not_run |
string[] |
yes | no | The sections asked for that couldn’t run. Each says why in its own not_run. With --exit-code, any is exit code 2. |
summary |
Summary |
yes | no | How many problems of each severity the sections that ran have, and of each kind of next step: the diagnostics of problems, links, and delivery. |
next_command |
string |
yes | yes | The command that lists everything a list here leaves out, when one does; null otherwise. |
builds |
object[] |
no | no | builds, when asked for: one for each build checked. |
builds[].build |
string |
yes | no | The build. |
builds[].pages |
object |
yes | no | The pages it doesn’t publish, in path order. |
builds[].pages.items |
object[] |
yes | no | The items, at most --limit of them. |
builds[].pages.items[].file |
string |
yes | no | The page, relative to the project root, as a diagnostic’s file is. |
builds[].pages.items[].kind |
string |
yes | no | availability when its available frontmatter leaves it out, or variant when its variant frontmatter does. |
builds[].pages.items[].mark |
string |
yes | no | That frontmatter’s value, as written: self-managed 3.5, or deployment=cloud for variant, with a dimension’s values joined by |. |
builds[].pages.items[].kept_by |
string[] |
yes | no | The builds that publish it. |
builds[].pages.shown |
integer |
yes | no | How many are listed. |
builds[].pages.total |
integer |
yes | no | How many there are. |
builds[].pages.truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
builds[].content |
object |
yes | no | The marks that take content out of the pages it publishes, in file and source order: each @available and variant arm once, however many blocks it takes out. |
builds[].content.items |
object[] |
yes | no | The items, at most --limit of them. |
builds[].content.items[].file |
string |
yes | no | The file the mark is written in: the page, or a fragment it includes. |
builds[].content.items[].range |
Range |
yes | no | Where in the file: the @available line, the table row, or the variant arm. |
builds[].content.items[].page |
string |
yes | no | The page it’s taken out of, as file is. |
builds[].content.items[].heading |
string |
yes | yes | The text of the heading the mark is under, or null: the section’s own heading, for a section’s @available. |
builds[].content.items[].kind |
string |
yes | no | variant for a variant arm, or availability for content a feature’s availability takes out. |
builds[].content.items[].scope |
string |
yes | no | What the mark takes out: section, block, row (a table row), or arm (a variant arm). |
builds[].content.items[].why |
string |
yes | no | Why, with the content model’s labels: Shows only os=linux. |
builds[].content.items[].kept_by |
string[] |
yes | no | The builds that keep it. |
builds[].content.shown |
integer |
yes | no | How many are listed. |
builds[].content.total |
integer |
yes | no | How many there are. |
builds[].content.truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
delivery |
object |
no | no | delivery, when asked for. |
delivery.not_run |
NotRunJson |
yes | yes | Why it couldn’t run, or null when it ran. When it isn’t null, the rest is empty. |
delivery.site |
string |
yes | no | The site checked, as --site gives it; empty when none was given. |
delivery.results |
object[] |
yes | no | Each check’s result, in the checker’s order. |
delivery.results[].id |
string |
yes | no | The check’s id, such as llms-txt-exists. |
delivery.results[].category |
string |
yes | no | Its category in the spec. |
delivery.results[].status |
string |
yes | no | pass, warn, fail, skip, or error. |
delivery.results[].message |
string |
yes | no | What the checker said. |
delivery.results[].owner |
string |
yes | no | Who changes what it checks: ascribe (what Ascribe writes), hosting (where the site is hosted), or pages (the pages, which ascribe check reports on). |
delivery.diagnostics |
Capped_Entry |
yes | no | A diagnostic for each check that failed or warned that the hosting or Ascribe owns. One a page owns is ascribe check’s, and isn’t repeated. |
delivery.previous_run |
string |
yes | yes | The day of the last report that checked the same site, YYYY-MM-DD, or null on a first run, with --no-history, or when the last report checked another site or none. |
delivery.new |
integer |
yes | yes | How many checks fail or warn now that passed on the last report or weren’t in it, or null when previous_run is. A check is told from another by the site’s address and its id. |
delivery.resolved |
integer |
yes | yes | How many checks that failed or warned on the last report pass now or aren’t in this one, or null when previous_run is. |
delivery.new_checks |
string[] |
yes | no | The ids of the checks new counts, in the checker’s order; empty when previous_run is null. |
inventory |
object |
no | no | inventory, when asked for. |
inventory.pages |
integer |
yes | no | How many pages. |
inventory.by_type |
object[] |
yes | no | How many pages of each type, most first. |
inventory.by_type[].type |
string |
yes | yes | The type’s name; null for the pages no one type applies to. |
inventory.by_type[].pages |
integer |
yes | no | How many pages. |
inventory.by_owner |
object[] |
yes | no | How many pages each owner has, most first: the value of the frontmatter field the page’s type marks role = "owner". |
inventory.by_owner[].owner |
string |
yes | yes | The owner, as the frontmatter gives it; null for the pages without one. |
inventory.by_owner[].pages |
integer |
yes | no | How many pages. |
inventory.overdue |
Capped_Entry |
yes | no | The pages whose recheck date has passed (recheck-overdue). |
inventory.orphans |
Capped_Entry |
yes | no | The pages nothing links to (page-orphan). |
inventory.unused |
Capped_Entry |
yes | no | The fragments, phrases, features, glossary terms, and images nothing uses. |
inventory.apis |
object[] |
no | no | How many of each declared API’s operations the pages cover, for each API whose spec could be read, in the content model’s order. Absent when the project declares no API. |
inventory.apis[].api |
string |
yes | no | The API’s name, its key in [apis]. |
inventory.apis[].operations |
integer |
yes | no | How many operations its spec has. |
inventory.apis[].linked |
integer |
yes | no | How many of them a link names, by operationId or by method and path. |
inventory.apis[].examples |
integer |
yes | no | How many of them a checked example claims as its request or response. |
inventory.examples |
object[] |
no | no | The tested examples the snippets show, for each source in the same repository with an ascribe.examples.toml, in the content model’s order. Absent when no source has one. |
inventory.examples[].source |
string |
yes | no | The source’s name. |
inventory.examples[].snippets |
integer |
yes | no | How many @snippet lines, in pages and fragments, show one of its examples. |
inventory.examples[].current |
integer |
yes | no | How many of those show an example an observation is current for. |
inventory.examples[].stale |
integer |
yes | no | How many show one that changed after every observation listing it. |
inventory.examples[].unobserved |
integer |
yes | no | How many show one no observation lists. |
links |
object |
no | no | links, when asked for. |
links.not_run |
NotRunJson |
yes | yes | Why it couldn’t run, or null when it ran. When it isn’t null, the rest is empty. |
links.checked |
integer |
yes | no | How many different addresses were checked: asked and reused. |
links.asked |
integer |
yes | no | How many different addresses the link checker was asked about in this run. |
links.reused |
integer |
yes | no | How many different addresses’ answers were reused from an earlier run, within [checks.links] reuse-days. None of diagnostics is from a reused answer: only an answer with nothing to report is kept. |
links.oldest_answer |
string |
yes | yes | The day of the oldest answer reused, YYYY-MM-DD, or null when none was. |
links.ignored |
integer |
yes | no | How many [checks.links] ignore left out. |
links.diagnostics |
Capped_Entry |
yes | no | A diagnostic for each link that moved or is broken, at its place, and for each acknowledgement of a broken link that covers nothing. |
links.acknowledged |
Capped_AcknowledgedEntry |
yes | no | The broken links acknowledged as intended, confirmed or not. |
links.previous_run |
string |
yes | yes | The day of the run the link history is from, YYYY-MM-DD, or null on a first run, or with --no-history. |
links.new |
integer |
yes | yes | How many of diagnostics the previous run didn’t report, or null when previous_run is. |
links.resolved |
integer |
yes | yes | How many addresses the previous run reported that this one doesn’t, fixed or no longer linked to, or null when previous_run is. |
links.unconfirmed |
object |
yes | no | The broken links that answered before and aren’t reported until they’ve kept failing for [checks.links] confirm-days. They aren’t in diagnostics or the summary, and don’t fail --exit-code. |
links.unconfirmed.items |
object[] |
yes | no | The items, at most --limit of them. |
links.unconfirmed.items[].file |
string |
yes | no | The file, as a diagnostic’s file is. |
links.unconfirmed.items[].range |
Range |
yes | no | Where in the file: the link. |
links.unconfirmed.items[].url |
string |
yes | no | The link’s address. |
links.unconfirmed.items[].status |
string |
yes | no | What the link checker said: a status, such as 503 Service Unavailable, or why it didn’t answer. |
links.unconfirmed.items[].last_answered |
string |
yes | no | The last day it answered, YYYY-MM-DD. |
links.unconfirmed.items[].failing_since |
string |
yes | no | The day it started failing, YYYY-MM-DD. |
links.unconfirmed.items[].reported_from |
string |
yes | no | The day it’s reported from if it’s still failing, YYYY-MM-DD. |
links.unconfirmed.shown |
integer |
yes | no | How many are listed. |
links.unconfirmed.total |
integer |
yes | no | How many there are. |
links.unconfirmed.truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
pages |
object[] |
no | no | pages, when asked for: one for each build checked. |
pages[].build |
string |
yes | no | The build. |
pages[].published |
integer |
yes | no | How many pages the build publishes. |
pages[].not_listed |
integer |
yes | no | How many of them aren’t listed: unquoted or unlisted. |
pages[].records |
object |
yes | no | The records, sorted by route: every page’s, or with --not-listed those that aren’t listed. Each has the fields of its entry in the build’s _ascribe/pages.json (output-layout contract §1.3), by the same names, with route, the key it’s under there. |
pages[].records.items |
object[] |
yes | no | The items, at most --limit of them. |
pages[].records.items[].route |
string |
yes | no | The page’s address, from the host’s root, as the site output’s links write it. |
pages[].records.items[].source |
string |
yes | no | The page’s source path, from the content root. |
pages[].records.items[].listing |
string |
yes | no | listed, unquoted, or unlisted. |
pages[].records.items[].listing_from |
object |
yes | no | Where listing comes from. |
pages[].records.items[].listing_from.level |
string |
yes | no | default when nothing sets it, page for the page’s own listing, or the level of the rule of [listing] it’s under: site, older-lines, folder, or type. |
pages[].records.items[].listing_from.folder |
string |
no | no | For a folder’s rule, the folder, as [listing.folders] names it. |
pages[].records.items[].listing_from.line |
integer |
no | no | For a rule, its line in ascribe.toml. |
pages[].records.items[].listing_from.rule |
string |
no | no | For a rule, the rule as written in ascribe.toml. |
pages[].records.items[].listing_from.type |
string |
no | no | For a type’s rule, the type. |
pages[].records.items[].breadcrumbs |
object[] |
yes | no | Its place in the site, from the top down to the page itself. |
pages[].records.items[].breadcrumbs[].route |
string |
yes | no | The step’s page’s address, as route is. |
pages[].records.items[].breadcrumbs[].title |
string |
yes | no | The step’s page’s title, as plain text. |
pages[].records.items[].canonical |
string |
no | no | Its own address, absolute; absent without [consumer] site. |
pages[].records.items[].description |
string |
no | no | Its description, as plain text on one line; absent when it has none. |
pages[].records.items[].markdown |
string |
no | no | Its Markdown version’s address, from the host’s root; absent when the build publishes none. |
pages[].records.items[].title |
string |
no | no | Its title, as plain text; absent when it has none. |
pages[].records.shown |
integer |
yes | no | How many are listed. |
pages[].records.total |
integer |
yes | no | How many there are. |
pages[].records.truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
pages[].site |
string |
no | no | The project’s address, [consumer] site, as the build’s _ascribe/pages.json has it; absent when it isn’t set. |
problems |
object |
no | no | problems, when asked for. |
problems.summary |
Summary |
yes | no | How many errors, warnings, and advice, and of each kind of next step. |
problems.by_check |
object |
yes | no | How many diagnostics each check reports, most first. |
problems.by_check.items |
object[] |
yes | no | The items, at most --limit of them. |
problems.by_check.items[].code |
string |
yes | no | The code, such as ASC036. |
problems.by_check.items[].slug |
string |
yes | no | The check’s name, such as link-target-missing. |
problems.by_check.items[].severity |
string |
yes | no | error, warning, or advice. |
problems.by_check.items[].next |
string |
yes | no | Its kind of next step, as a diagnostic’s next is. |
problems.by_check.items[].count |
integer |
yes | no | How many. |
problems.by_check.shown |
integer |
yes | no | How many are listed. |
problems.by_check.total |
integer |
yes | no | How many there are. |
problems.by_check.truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
problems.by_file |
object |
yes | no | How many diagnostics each file has, most first. |
problems.by_file.items |
object[] |
yes | no | The items, at most --limit of them. |
problems.by_file.items[].file |
string |
yes | no | The file, relative to the project root, as a diagnostic’s file is. |
problems.by_file.items[].errors |
integer |
yes | no | How many errors. |
problems.by_file.items[].warnings |
integer |
yes | no | How many warnings. |
problems.by_file.items[].advice |
integer |
yes | no | How many advice. |
problems.by_file.shown |
integer |
yes | no | How many are listed. |
problems.by_file.total |
integer |
yes | no | How many there are. |
problems.by_file.truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
problems.acknowledged |
Capped_AcknowledgedEntry |
yes | no | The problems acknowledged as intended, with their reasons, in file order. |
problems.list_command |
string |
yes | no | The command that lists each problem: ascribe check, as JSON. |
problems.previous_run |
string |
yes | yes | The day of the last report, YYYY-MM-DD, or null on a first run, with --no-history, or when the last report checked other builds. |
problems.new |
integer |
yes | yes | How many problems the last report didn’t list, or null when previous_run is. A problem is told from another by its check, its file, the text it’s about, and its order among those alike. |
problems.resolved |
integer |
yes | yes | How many problems the last report listed that this one doesn’t, fixed or with the text they’re about edited, or null when previous_run is. |
problems.new_items |
Capped_Entry |
yes | no | The problems the last report didn’t list, in the order ascribe check reports them; none when previous_run is null. |
problems.baselined |
integer |
no | no | How many advice are baselined, listed in ascribe.baseline, which the counts leave out: the project’s backlog. Left out when there are none, and with --no-baseline. |
Summary: How many problems of each severity, and of each kind of next step.
| Field | Type | Required | Nullable | Description |
|---|---|---|---|---|
errors |
integer |
yes | no | How many errors. |
warnings |
integer |
yes | no | How many warnings. |
advice |
integer |
yes | no | How many advice. |
by_next |
object[] |
yes | no | How many of each kind of next step, in the order fix, choose, write, review, outside; a kind with none is left out. |
by_next[].next |
string |
yes | no | fix, choose, write, review, or outside, as a diagnostic’s next is. |
by_next[].count |
integer |
yes | no | How many. |
Range: A span of a file. end is just past its last character; an empty range (an insertion) has equal positions.
| Field | Type | Required | Nullable | Description |
|---|---|---|---|---|
start |
Pos |
yes | no | Its first character. |
end |
Pos |
yes | no | Just past its last character. |
NotRunJson: Why a section couldn’t run, and what would let it.
| Field | Type | Required | Nullable | Description |
|---|---|---|---|---|
reason |
string |
yes | no | Why, as a sentence. |
how |
string |
yes | no | What to do so that it runs, as a sentence. |
Capped_Entry: A list of at most --limit items.
| Field | Type | Required | Nullable | Description |
|---|---|---|---|---|
items |
object[] |
yes | no | The items, at most --limit of them. |
items[].code |
string |
yes | no | The code, such as ASC036. |
items[].slug |
string |
yes | no | The diagnostic’s name, such as link-target-missing. |
items[].severity |
string |
yes | no | error, warning, or advice. Advice never fails the command. More severities may be added; a reader treats one it doesn’t know as it treats advice. |
items[].next |
string |
yes | no | The kind of next step: fix when Ascribe can make the edit, choose when the writer picks among things Ascribe can list, write when it needs writing or judgment, outside when nothing in the source can fix it, and review when it may be fine as it is. |
items[].message |
string |
yes | no | What’s wrong, and what to do about it. |
items[].file |
string |
yes | no | The file, relative to the project root (the folder of ascribe.toml), with / separators. ascribe.toml for a content-model problem. |
items[].range |
Range |
yes | no | Where in the file. |
items[].related |
object[] |
yes | no | Other places that explain it. |
items[].related[].file |
string |
yes | no | The file, as a diagnostic’s file is. |
items[].related[].range |
Range |
yes | no | Where in the file. |
items[].related[].message |
string |
yes | no | What it has to do with the diagnostic. |
items[].fixes |
object[] |
yes | no | Edits that would fix it. |
items[].fixes[].title |
string |
yes | no | What the fix does. |
items[].fixes[].file |
string |
yes | no | The file the edits are in, as a diagnostic’s file is. |
items[].fixes[].edits |
object[] |
yes | no | The edits, each replacing the text of its range. |
items[].fixes[].edits[].range |
Range |
yes | no | The text it replaces. |
items[].fixes[].edits[].new_text |
string |
yes | no | The text that replaces it. |
items[].fixes[].applicability |
string |
yes | no | safe when applying the edits as they are can’t change what the page says and leaves nothing to decide; unsafe otherwise. |
items[].builds |
string[] |
yes | no | The builds a page-level diagnostic appears in, in ascribe.toml’s order. Empty for a file-level diagnostic, and for one in content no build publishes. With --build, only that build. |
items[].unpublished |
boolean |
yes | no | Whether it’s in content that no build publishes. |
items[].help |
string |
yes | no | How to fix it, in general: the diagnostics reference’s advice for its code, in Markdown, whose links are the docs’ permalinks, such as https://ascribed-dev.com/go/22-checks/. |
items[].docs |
string |
yes | no | The address of its entry in the diagnostics reference: the docs’ permalink for its code, such as https://ascribed-dev.com/go/ASC036/, which forwards to the entry wherever it is. |
items[].repeats |
integer |
yes | no | For a problem in included content reported because one of its related places is in a path named: at how many other includes it’s reported too, collapsed into this one. 0 otherwise. |
items[].rule |
string |
no | no | The rule of the program that found it, such as Ascribe.Repeated from Vale, for a prose diagnostic. Absent for Ascribe’s own. |
shown |
integer |
yes | no | How many are listed. |
total |
integer |
yes | no | How many there are. |
truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
Capped_AcknowledgedEntry: A list of at most --limit items.
| Field | Type | Required | Nullable | Description |
|---|---|---|---|---|
items |
object[] |
yes | no | The items, at most --limit of them. |
items[].code |
string |
yes | no | The code of the check that found it, such as ASC036. |
items[].slug |
string |
yes | no | The check’s name. |
items[].message |
string |
yes | no | What the check found. |
items[].file |
string |
yes | no | The file, as a diagnostic’s file is. |
items[].range |
Range |
yes | no | Where in the file. |
items[].builds |
string[] |
yes | no | The builds it appears in, as a diagnostic’s builds are. |
items[].reason |
string |
yes | no | Why it’s intended: the acknowledgement’s reason. |
items[].at |
object |
yes | no | Where the acknowledgement is written. |
items[].at.file |
string |
yes | no | The file, as a diagnostic’s file is. |
items[].at.range |
Range |
yes | no | Where in the file. |
shown |
integer |
yes | no | How many are listed. |
total |
integer |
yes | no | How many there are. |
truncated |
boolean |
yes | no | Whether some are left out: shown is less than total. The report’s next_command lists them all. |
Pos: A position in a file.
| Field | Type | Required | Nullable | Description |
|---|---|---|---|---|
line |
integer |
yes | no | The line, from 1. |
column |
integer |
yes | no | The column, from 1, in Unicode characters (not bytes or UTF-16 units). |
offset |
integer |
yes | no | The byte offset from the start of the file. |