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.
Part of the JSON report contract, whose rules every document here follows.
ascribe versions list
schemas/versions-list.schema.json:
{
"$defs": {
"LineOutput": {
"description": "A live line's output in one build.",
"properties": {
"base": {
"description": "The path its pages are under, ending in `/`.",
"type": "string"
},
"build": {
"description": "The output's build: the build's own name for the current line,\n`<build>@<line>` for an older one.",
"type": "string"
},
"pages": {
"description": "How many pages it publishes.",
"minimum": 0,
"type": "integer"
}
},
"required": [
"build",
"base",
"pages"
],
"type": "object"
},
"ListedLine": {
"description": "One line of a target.",
"properties": {
"ended": {
"description": "For an archived line, the day its support ended.",
"type": [
"string",
"null"
]
},
"ends": {
"description": "For a live line, the last day it's supported, from `ends`.",
"type": [
"string",
"null"
]
},
"line": {
"description": "The line, as the list writes it.",
"type": "string"
},
"outputs": {
"description": "For a live line, its output in each build versioned by the target.",
"items": {
"$ref": "#/$defs/LineOutput"
},
"type": "array"
},
"status": {
"description": "`current` (the newest live line), `live`, `planned`, or `archived`.",
"type": "string"
},
"url": {
"description": "For an archived line, where it can still be read; absent when\nnowhere.",
"type": [
"string",
"null"
]
}
},
"required": [
"line",
"status",
"outputs"
],
"type": "object"
},
"TargetLines": {
"description": "One target's lines.",
"properties": {
"builds": {
"description": "The builds versioned by it, which give each live line an output.",
"items": {
"type": "string"
},
"type": "array"
},
"lines": {
"description": "Its lines, newest first.",
"items": {
"$ref": "#/$defs/ListedLine"
},
"type": "array"
},
"target": {
"description": "The target, a versioned dimension value.",
"type": "string"
}
},
"required": [
"target",
"builds",
"lines"
],
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Every target's release lines.",
"properties": {
"ascribe_version": {
"description": "The version of Ascribe that wrote it.",
"type": "string"
},
"schema_version": {
"description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
"minimum": 0,
"type": "integer"
},
"targets": {
"description": "Each target with a list in `[releases]`, in the order `ascribe.toml`\ndeclares them.",
"items": {
"$ref": "#/$defs/TargetLines"
},
"type": "array"
}
},
"required": [
"schema_version",
"ascribe_version",
"targets"
],
"title": "VersionsListReport",
"type": "object"
}ascribe versions changes
schemas/versions-changes.schema.json:
{
"$defs": {
"LineChange": {
"description": "Content one line has and another doesn't, or has in another state.",
"properties": {
"file": {
"description": "The file its mark is in, from the project root, as `ascribe check`\nreports it.",
"type": "string"
},
"from_state": {
"description": "The state in `from`, for a change of state: a lifecycle state, such\nas `preview`, or `ga`.",
"type": [
"string",
"null"
]
},
"heading": {
"description": "The heading it's under, or the section's own heading; absent at the\ntop of the page, and for a page.",
"type": [
"string",
"null"
]
},
"in_place_of": {
"anyOf": [
{
"$ref": "#/$defs/PlaceOf"
},
{
"type": "null"
}
],
"description": "For a page added, the page `from` has in its place and `to`\ndoesn't, when `replaces` links the two, either way: the pair is one\nchange, so that page isn't listed as removed."
},
"kind": {
"description": "What the mark is on: `page` (the frontmatter's `available`),\n`section` (a heading's), `block` (the block after it), or `row` (a\ntable row's).",
"type": "string"
},
"line": {
"description": "The mark's line, from 1.",
"minimum": 0,
"type": "integer"
},
"page": {
"description": "The page's title, or the file's path when it has none.",
"type": "string"
},
"text": {
"description": "Its first line, as written.",
"type": "string"
},
"to_state": {
"description": "The state in `to`, for a change of state.",
"type": [
"string",
"null"
]
}
},
"required": [
"file",
"line",
"kind",
"page",
"text"
],
"type": "object"
},
"PlaceOf": {
"description": "The page another takes the place of.",
"properties": {
"file": {
"description": "Its file, from the project root.",
"type": "string"
},
"line": {
"description": "Its mark's line, from 1.",
"minimum": 0,
"type": "integer"
},
"page": {
"description": "Its title, or the file's path when it has none.",
"type": "string"
}
},
"required": [
"file",
"line",
"page"
],
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "What differs between two lines of one target.",
"properties": {
"added": {
"description": "What `to` has and `from` doesn't, in page order.",
"items": {
"$ref": "#/$defs/LineChange"
},
"type": "array"
},
"ascribe_version": {
"description": "The version of Ascribe that wrote it.",
"type": "string"
},
"changed": {
"description": "What both have, in a different state.",
"items": {
"$ref": "#/$defs/LineChange"
},
"type": "array"
},
"from": {
"description": "The line compared from, as the list writes it.",
"type": "string"
},
"removed": {
"description": "What `from` has and `to` doesn't.",
"items": {
"$ref": "#/$defs/LineChange"
},
"type": "array"
},
"schema_version": {
"description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
"minimum": 0,
"type": "integer"
},
"target": {
"description": "The target.",
"type": "string"
},
"to": {
"description": "The line compared to.",
"type": "string"
}
},
"required": [
"schema_version",
"ascribe_version",
"target",
"from",
"to",
"added",
"removed",
"changed"
],
"title": "VersionsChangesReport",
"type": "object"
}ascribe versions release
schemas/versions-release.schema.json:
{
"$defs": {
"ClearedFileJson": {
"description": "A source file with marks that say nothing once the line that was\ncurrent is archived.",
"properties": {
"file": {
"description": "The file, from the project root.",
"type": "string"
},
"marks": {
"description": "Each mark removed or rewritten.",
"items": {
"$ref": "#/$defs/ClearedMarkJson"
},
"type": "array"
}
},
"required": [
"file",
"marks"
],
"type": "object"
},
"ClearedMarkJson": {
"description": "A mark that says nothing, removed or rewritten.",
"properties": {
"from": {
"description": "Its entry for the target, as written.",
"type": "string"
},
"line": {
"description": "Its line, from 1, before the release.",
"minimum": 0,
"type": "integer"
},
"to": {
"description": "The entry as rewritten; null when the mark is removed.",
"type": [
"string",
"null"
]
}
},
"required": [
"line",
"from",
"to"
],
"type": "object"
},
"FeatureJson": {
"description": "A feature moved by the release.",
"properties": {
"from": {
"description": "Its spec before.",
"type": "string"
},
"kept": {
"description": "The other targets its spec names, left as they were.",
"items": {
"type": "string"
},
"type": "array"
},
"key": {
"description": "Its key.",
"type": "string"
},
"to": {
"description": "Its spec after.",
"type": "string"
}
},
"required": [
"key",
"from",
"to",
"kept"
],
"type": "object"
},
"FileJson": {
"description": "A source file the release rewrites.",
"properties": {
"file": {
"description": "The file, from the project root.",
"type": "string"
},
"marks": {
"description": "Each mark rewritten.",
"items": {
"$ref": "#/$defs/MarkJson"
},
"type": "array"
}
},
"required": [
"file",
"marks"
],
"type": "object"
},
"MarkJson": {
"description": "A mark the release rewrites.",
"properties": {
"from": {
"description": "The spec as written.",
"type": "string"
},
"line": {
"description": "Its line, from 1.",
"minimum": 0,
"type": "integer"
},
"to": {
"description": "The spec as rewritten.",
"type": "string"
}
},
"required": [
"line",
"from",
"to"
],
"type": "object"
},
"OutputJson": {
"description": "One output the release changes.",
"properties": {
"added": {
"description": "The files it gains, by their path in the output.",
"items": {
"type": "string"
},
"type": "array"
},
"build": {
"description": "The build: `site`, or an older line's, `site@3.4`. Empty for the\nfile the lines share.",
"type": "string"
},
"changed": {
"description": "The files that change.",
"items": {
"type": "string"
},
"type": "array"
},
"output": {
"description": "The output: `site`, `plain`, or `json`, or `_ascribe` for the file\nthe lines share.",
"type": "string"
},
"removed": {
"description": "The files it loses.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"build",
"output",
"added",
"removed",
"changed"
],
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "What `ascribe versions release --format json` writes: the line released,\nthe files and marks rewritten, the features moved, and what the release\nchanges in the outputs.",
"properties": {
"archived": {
"description": "The line that was current, moved to `archived` with no address,\nbecause no build is versioned by the target.",
"type": [
"string",
"null"
]
},
"ascribe_version": {
"description": "The version of Ascribe that wrote it.",
"type": "string"
},
"cleared": {
"description": "Each source file with marks for the target that say nothing once\n`archived` is, removed or rewritten, from the project root.",
"items": {
"$ref": "#/$defs/ClearedFileJson"
},
"type": "array"
},
"cleared_features": {
"description": "Each feature whose spec says nothing for the target once `archived`\nis, rewritten.",
"items": {
"$ref": "#/$defs/FeatureJson"
},
"type": "array"
},
"files": {
"description": "Each source file whose marks are rewritten, from the project root.",
"items": {
"$ref": "#/$defs/FileJson"
},
"type": "array"
},
"from": {
"description": "The `ascribe.toml` the target's lines are written in, from the\ncurrent folder, when the project's `[from]` takes them from another\nproject's: the release is made in that project, and `files` are from\nits root. `null` when they're written in the project's own.",
"type": [
"string",
"null"
]
},
"line": {
"description": "The line released, as given.",
"type": "string"
},
"next": {
"description": "The line planned after the released one, from `--next`.",
"type": [
"string",
"null"
]
},
"next_added": {
"description": "Whether `next` was added to `planned`, from `--next`.",
"type": "boolean"
},
"outputs": {
"description": "What the release changes in the builds' outputs, by build and\noutput.",
"items": {
"$ref": "#/$defs/OutputJson"
},
"type": "array"
},
"schema_version": {
"description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
"minimum": 0,
"type": "integer"
},
"target": {
"description": "The target.",
"type": "string"
},
"was_planned": {
"description": "Whether the line was in `planned`; a line that wasn't is a release\nnobody planned, such as a patch.",
"type": "boolean"
},
"written": {
"description": "Whether the files were written: false with `--dry-run`.",
"type": "boolean"
}
},
"required": [
"schema_version",
"ascribe_version",
"written",
"target",
"line",
"was_planned",
"next",
"next_added",
"archived",
"files",
"cleared",
"cleared_features",
"outputs",
"from"
],
"title": "VersionsReleaseReport",
"type": "object"
}ascribe versions export
schemas/versions-export.schema.json:
{
"$defs": {
"UnlinkedJson": {
"description": "A link an archive writes as its text.",
"properties": {
"file": {
"description": "The page it's on, from the project root.",
"type": "string"
},
"href": {
"description": "Where it led.",
"type": "string"
},
"line": {
"description": "For a link out of the line, the line it led to.",
"type": [
"string",
"null"
]
},
"text": {
"description": "Its text.",
"type": "string"
}
},
"required": [
"file",
"text",
"href",
"line"
],
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "What `ascribe versions export --format json` writes: the line, the\nfolder, and what's in it.",
"properties": {
"ascribe_version": {
"description": "The version of Ascribe that wrote it.",
"type": "string"
},
"assets": {
"description": "How many copies of images and files they use it has.",
"minimum": 0,
"type": "integer"
},
"build": {
"description": "The build the line is a line of, as it's declared.",
"type": "string"
},
"contents": {
"description": "The contents page, from the folder: `index.html`, or\n`contents.html` when the line's root page is `index.html`.",
"type": "string"
},
"folder": {
"description": "The folder written, from the current folder, with `/`.",
"type": "string"
},
"line": {
"description": "The line exported, as `[releases.<target>]` writes it.",
"type": "string"
},
"pages": {
"description": "How many pages the archive has.",
"minimum": 0,
"type": "integer"
},
"removed": {
"description": "How many files of an archive written there before it no longer\nhas, removed.",
"minimum": 0,
"type": "integer"
},
"schema_version": {
"description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
"minimum": 0,
"type": "integer"
},
"search_index_bytes": {
"description": "The size of the search index, `search-index.js`, in bytes.",
"minimum": 0,
"type": "integer"
},
"search_index_large": {
"description": "Whether the search index is large enough that a reader's first\nsearch waits for it to load.",
"type": "boolean"
},
"status": {
"description": "The line's status: `current`, `live`, or `planned`.",
"type": "string"
},
"target": {
"description": "The target.",
"type": "string"
},
"unlinked": {
"description": "Each link written as its text: a link out of the line, or to an\naddress no page of the line has.",
"items": {
"$ref": "#/$defs/UnlinkedJson"
},
"type": "array"
}
},
"required": [
"schema_version",
"ascribe_version",
"target",
"line",
"status",
"build",
"folder",
"contents",
"pages",
"assets",
"removed",
"search_index_bytes",
"search_index_large",
"unlinked"
],
"title": "VersionsExportReport",
"type": "object"
}ascribe versions retire
schemas/versions-retire.schema.json:
{
"$defs": {
"FeatureJson": {
"description": "A feature moved by the release.",
"properties": {
"from": {
"description": "Its spec before.",
"type": "string"
},
"kept": {
"description": "The other targets its spec names, left as they were.",
"items": {
"type": "string"
},
"type": "array"
},
"key": {
"description": "Its key.",
"type": "string"
},
"to": {
"description": "Its spec after.",
"type": "string"
}
},
"required": [
"key",
"from",
"to",
"kept"
],
"type": "object"
},
"FileJson": {
"description": "A source file the release rewrites.",
"properties": {
"file": {
"description": "The file, from the project root.",
"type": "string"
},
"marks": {
"description": "Each mark rewritten.",
"items": {
"$ref": "#/$defs/MarkJson"
},
"type": "array"
}
},
"required": [
"file",
"marks"
],
"type": "object"
},
"MarkJson": {
"description": "A mark the release rewrites.",
"properties": {
"from": {
"description": "The spec as written.",
"type": "string"
},
"line": {
"description": "Its line, from 1.",
"minimum": 0,
"type": "integer"
},
"to": {
"description": "The spec as rewritten.",
"type": "string"
}
},
"required": [
"line",
"from",
"to"
],
"type": "object"
},
"OutputJson": {
"description": "One output the release changes.",
"properties": {
"added": {
"description": "The files it gains, by their path in the output.",
"items": {
"type": "string"
},
"type": "array"
},
"build": {
"description": "The build: `site`, or an older line's, `site@3.4`. Empty for the\nfile the lines share.",
"type": "string"
},
"changed": {
"description": "The files that change.",
"items": {
"type": "string"
},
"type": "array"
},
"output": {
"description": "The output: `site`, `plain`, or `json`, or `_ascribe` for the file\nthe lines share.",
"type": "string"
},
"removed": {
"description": "The files it loses.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"build",
"output",
"added",
"removed",
"changed"
],
"type": "object"
},
"RedirectJson": {
"description": "An address and where it should go, as the headers list writes a path.",
"properties": {
"from": {
"description": "The address, from the site's root.",
"type": "string"
},
"to": {
"description": "Where it should go: a path from the site's root, or the archive's\nfull address.",
"type": "string"
}
},
"required": [
"from",
"to"
],
"type": "object"
},
"UnusedJson": {
"description": "Content no line has, or a mark that says nothing.",
"properties": {
"file": {
"description": "The file, from the project root.",
"type": "string"
},
"kind": {
"description": "`page`, `section`, `block`, `row`, or `mark`, for a mark that says\nnothing and can go while its content stays.",
"type": "string"
},
"line": {
"description": "The mark's line, from 1.",
"minimum": 0,
"type": "integer"
},
"text": {
"description": "Its first line: a page's title, a section's heading, a block's or a\nrow's first line, or the mark.",
"type": "string"
}
},
"required": [
"file",
"line",
"kind",
"text"
],
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "What `ascribe versions retire --format json` writes: the line, its\naddress, the marks rewritten, what no line has any more, and where each\nof the line's addresses should go.",
"properties": {
"ascribe_version": {
"description": "The version of Ascribe that wrote it.",
"type": "string"
},
"ended": {
"description": "The day the line's support ended: its `ends`, or the day it was\nretired.",
"type": [
"string",
"null"
]
},
"expected": {
"description": "The outputs of builds that aren't lines of the target whose pages\nchange only in the target's part of their availability lines, by\nbuild and output: expected, so they need no `--force`.",
"items": {
"$ref": "#/$defs/OutputJson"
},
"type": "array"
},
"features": {
"description": "Each feature whose spec is rewritten.",
"items": {
"$ref": "#/$defs/FeatureJson"
},
"type": "array"
},
"files": {
"description": "Each source file whose marks are rewritten, from the project root.",
"items": {
"$ref": "#/$defs/FileJson"
},
"type": "array"
},
"from": {
"description": "The `ascribe.toml` the target's lines are written in, from the\ncurrent folder, when the project's `[from]` takes them from another\nproject's: the retirement is made in that project, and `files` are\nfrom its root. `null` when they're written in the project's own.",
"type": [
"string",
"null"
]
},
"line": {
"description": "The line, as `[releases.<target>]` writes it.",
"type": "string"
},
"outputs": {
"description": "The outputs of builds that aren't lines of the target that the\nrewrite changes, by build and output: they need `--force`, and a dry\nrun lists them.",
"items": {
"$ref": "#/$defs/OutputJson"
},
"type": "array"
},
"recorded": {
"description": "Whether `ascribe.addresses` records the redirects that go to a page\nin the current line, in `[moved]` keyed by the address, so the build\nwrites them: true when the project has the file and the line has\none. With `--dry-run`, whether it would. Those to the archive are\nnever recorded.",
"type": "boolean"
},
"redirects": {
"description": "Where each address the line published should go, by address: the\nsame page in the current line, the page that replaces it there, or\nits page in the archive.",
"items": {
"$ref": "#/$defs/RedirectJson"
},
"type": "array"
},
"removed": {
"description": "Whether what `unused` lists was deleted, with `--remove-unused`.",
"type": "boolean"
},
"retired": {
"description": "Whether this run retired the line: false when it was archived\nalready, and the run only listed or removed what it left.",
"type": "boolean"
},
"schema_version": {
"description": "The version of this schema. It changes only when a field is removed\nor changes meaning.",
"minimum": 0,
"type": "integer"
},
"target": {
"description": "The target.",
"type": "string"
},
"unused": {
"description": "What no live or planned line has, and the marks that say nothing\nonce rewritten, by file and line.",
"items": {
"$ref": "#/$defs/UnusedJson"
},
"type": "array"
},
"url": {
"description": "Where the line's archive is read.",
"type": [
"string",
"null"
]
},
"written": {
"description": "Whether the files were written: false with `--dry-run`.",
"type": "boolean"
}
},
"required": [
"schema_version",
"ascribe_version",
"written",
"retired",
"target",
"line",
"url",
"ended",
"features",
"files",
"unused",
"removed",
"redirects",
"recorded",
"outputs",
"expected",
"from"
],
"title": "VersionsRetireReport",
"type": "object"
}