> For the complete documentation index, see [llms.txt](https://ascribed-dev.com/docs/llms.txt). This documentation describes Ascribe 0.4.4. Anything marked in main, not yet released isn't in that release yet.

# JSON reports: `ascribe versions`

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

Part of the [JSON report contract](https://ascribed-dev.com/docs/contracts/json-reports.md), whose rules every document here follows.

## `ascribe versions list`

[`schemas/versions-list.schema.json`](https://github.com/ascribed-dev/ascribe/blob/main/schemas/versions-list.schema.json):

```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`](https://github.com/ascribed-dev/ascribe/blob/main/schemas/versions-changes.schema.json):

```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`](https://github.com/ascribed-dev/ascribe/blob/main/schemas/versions-release.schema.json):

```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`](https://github.com/ascribed-dev/ascribe/blob/main/schemas/versions-export.schema.json):

```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`](https://github.com/ascribed-dev/ascribe/blob/main/schemas/versions-retire.schema.json):

```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"
}
```