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. |