JSON reports: ascribe versions

The JSON Schemas of what ascribe versions list, changes, release, export, and retire write with --format json.

For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.

The JSON Schemas of what ascribe versions list, changes, release, export, and retire write with --format json. Each document follows the rules of the JSON report contract.

ascribe versions list

The fields of schemas/versions-list.schema.json:

VersionsListReport: Every target’s release lines.

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.
targets object[] yes no Each target with a list in [releases], in the order ascribe.toml declares them.
targets[].target string yes no The target, a versioned dimension value.
targets[].builds string[] yes no The builds versioned by it, which give each live line an output.
targets[].lines object[] yes no Its lines, newest first.
targets[].lines[].line string yes no The line, as the list writes it.
targets[].lines[].status string yes no current (the newest live line), live, planned, or archived.
targets[].lines[].outputs object[] yes no For a live line, its output in each build versioned by the target.
targets[].lines[].outputs[].build string yes no The output’s build: the build’s own name for the current line, <build>@<line> for an older one.
targets[].lines[].outputs[].base string yes no The path its pages are under, ending in /.
targets[].lines[].outputs[].pages integer yes no How many pages it publishes.
targets[].lines[].ended string no no For an archived line, the day its support ended.
targets[].lines[].ends string no no For a live line, the last day it’s supported, from ends.
targets[].lines[].url string no no For an archived line, where it can still be read; absent when nowhere.

ascribe versions changes

The fields of schemas/versions-changes.schema.json:

VersionsChangesReport: What differs between two lines of one target.

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.
target string yes no The target.
from string yes no The line compared from, as the list writes it.
to string yes no The line compared to.
added LineChange[] yes no What to has and from doesn’t, in page order.
removed LineChange[] yes no What from has and to doesn’t.
changed LineChange[] yes no What both have, in a different state.

LineChange: Content one line has and another doesn’t, or has in another state.

Field Type Required Nullable Description
file string yes no The file its mark is in, from the project root, as ascribe check reports it.
line integer yes no The mark’s line, from 1.
kind string yes no What the mark is on: page (the frontmatter’s available), section (a heading’s), block (the block after it), or row (a table row’s).
page string yes no The page’s title, or the file’s path when it has none.
text string yes no Its first line, as written.
from_state string no no The state in from, for a change of state: a lifecycle state, such as preview, or ga.
heading string no no The heading it’s under, or the section’s own heading; absent at the top of the page, and for a page.
in_place_of object no no For a page added, the page from has in its place and to doesn’t, when replaces links the two, either way: the pair is one change, so that page isn’t listed as removed.
in_place_of.file string yes no Its file, from the project root.
in_place_of.line integer yes no Its mark’s line, from 1.
in_place_of.page string yes no Its title, or the file’s path when it has none.
to_state string no no The state in to, for a change of state.

ascribe versions release

The fields of schemas/versions-release.schema.json:

VersionsReleaseReport: What ascribe versions release --format json writes: the line released, the files and marks rewritten, the features moved, and what the release changes in the outputs.

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.
written boolean yes no Whether the files were written: false with --dry-run.
target string yes no The target.
line string yes no The line released, as given.
was_planned boolean yes no Whether the line was in planned; a line that wasn’t is a release nobody planned, such as a patch.
next string yes yes The line planned after the released one, from --next.
next_added boolean yes no Whether next was added to planned, from --next.
archived string yes yes The line that was current, moved to archived with no address, because no build is versioned by the target.
files object[] yes no Each source file whose marks are rewritten, from the project root.
files[].file string yes no The file, from the project root.
files[].marks object[] yes no Each mark rewritten.
files[].marks[].line integer yes no Its line, from 1.
files[].marks[].from string yes no The spec as written.
files[].marks[].to string yes no The spec as rewritten.
cleared object[] yes no Each source file with marks for the target that say nothing once archived is, removed or rewritten, from the project root.
cleared[].file string yes no The file, from the project root.
cleared[].marks object[] yes no Each mark removed or rewritten.
cleared[].marks[].line integer yes no Its line, from 1, before the release.
cleared[].marks[].from string yes no Its entry for the target, as written.
cleared[].marks[].to string yes yes The entry as rewritten; null when the mark is removed.
cleared_features object[] yes no Each feature whose spec says nothing for the target once archived is, rewritten.
cleared_features[].key string yes no Its key.
cleared_features[].from string yes no Its spec before.
cleared_features[].to string yes no Its spec after.
cleared_features[].kept string[] yes no The other targets its spec names, left as they were.
outputs object[] yes no What the release changes in the builds’ outputs, by build and output.
outputs[].build string yes no The build: site, or an older line’s, site@3.4. Empty for the file the lines share.
outputs[].output string yes no The output: site, plain, or json, or _ascribe for the file the lines share.
outputs[].added string[] yes no The files it gains, by their path in the output.
outputs[].removed string[] yes no The files it loses.
outputs[].changed string[] yes no The files that change.
from string yes yes The ascribe.toml the target’s lines are written in, from the current folder, when the project’s [from] takes them from another project’s: the release is made in that project, and files are from its root. null when they’re written in the project’s own.

ascribe versions export

The fields of schemas/versions-export.schema.json:

VersionsExportReport: What ascribe versions export --format json writes: the line, the folder, and what’s in it.

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.
target string yes no The target.
line string yes no The line exported, as [releases.<target>] writes it.
status string yes no The line’s status: current, live, or planned.
build string yes no The build the line is a line of, as it’s declared.
folder string yes no The folder written, from the current folder, with /.
contents string yes no The contents page, from the folder: index.html, or contents.html when the line’s root page is index.html.
pages integer yes no How many pages the archive has.
assets integer yes no How many copies of images and files they use it has.
removed integer yes no How many files of an archive written there before it no longer has, removed.
search_index_bytes integer yes no The size of the search index, search-index.js, in bytes.
search_index_large boolean yes no Whether the search index is large enough that a reader’s first search waits for it to load.
unlinked object[] yes no Each link written as its text: a link out of the line, or to an address no page of the line has.
unlinked[].file string yes no The page it’s on, from the project root.
unlinked[].text string yes no Its text.
unlinked[].href string yes no Where it led.
unlinked[].line string yes yes For a link out of the line, the line it led to.

ascribe versions retire

The fields of schemas/versions-retire.schema.json:

VersionsRetireReport: What ascribe versions retire --format json writes: the line, its address, the marks rewritten, what no line has any more, and where each of the line’s addresses should go.

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.
written boolean yes no Whether the files were written: false with --dry-run.
retired boolean yes no Whether this run retired the line: false when it was archived already, and the run only listed or removed what it left.
target string yes no The target.
line string yes no The line, as [releases.<target>] writes it.
url string yes yes Where the line’s archive is read.
ended string yes yes The day the line’s support ended: its ends, or the day it was retired.
features object[] yes no Each feature whose spec is rewritten.
features[].key string yes no Its key.
features[].from string yes no Its spec before.
features[].to string yes no Its spec after.
features[].kept string[] yes no The other targets its spec names, left as they were.
files object[] yes no Each source file whose marks are rewritten, from the project root.
files[].file string yes no The file, from the project root.
files[].marks object[] yes no Each mark rewritten.
files[].marks[].line integer yes no Its line, from 1.
files[].marks[].from string yes no The spec as written.
files[].marks[].to string yes no The spec as rewritten.
unused object[] yes no What no live or planned line has, and the marks that say nothing once rewritten, by file and line.
unused[].file string yes no The file, from the project root.
unused[].line integer yes no The mark’s line, from 1.
unused[].kind string yes no page, section, block, row, or mark, for a mark that says nothing and can go while its content stays.
unused[].text string yes no Its first line: a page’s title, a section’s heading, a block’s or a row’s first line, or the mark.
removed boolean yes no Whether what unused lists was deleted, with --remove-unused.
redirects object[] yes no Where each address the line published should go, by address: the same page in the current line, the page that replaces it there, or its page in the archive.
redirects[].from string yes no The address, from the site’s root.
redirects[].to string yes no Where it should go: a path from the site’s root, or the archive’s full address.
recorded boolean yes no Whether ascribe.addresses records the redirects that go to a page in the current line, in [moved] keyed by the address, so the build writes them: true when the project has the file and the line has one. With --dry-run, whether it would. Those to the archive are never recorded.
outputs OutputJson[] yes no The outputs of builds that aren’t lines of the target that the rewrite changes, by build and output: they need --force, and a dry run lists them.
expected OutputJson[] yes no The outputs of builds that aren’t lines of the target whose pages change only in the target’s part of their availability lines, by build and output: expected, so they need no --force.
from string yes yes The ascribe.toml the target’s lines are written in, from the current folder, when the project’s [from] takes them from another project’s: the retirement is made in that project, and files are from its root. null when they’re written in the project’s own.

OutputJson: One output the release changes.

Field Type Required Nullable Description
build string yes no The build: site, or an older line’s, site@3.4. Empty for the file the lines share.
output string yes no The output: site, plain, or json, or _ascribe for the file the lines share.
added string[] yes no The files it gains, by their path in the output.
removed string[] yes no The files it loses.
changed string[] yes no The files that change.