> 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 templates`

> Reference · The JSON Schemas of what ascribe templates writes 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 templates list`

Available: Ascribe (in main, not yet released, 0.4.5)

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

```json
{
  "$defs": {
    "ListTemplate": {
      "description": "A template in `ascribe templates list --format json`.",
      "properties": {
        "name": {
          "description": "Its name, which `ascribe templates eject` takes, and its type's.",
          "type": "string"
        },
        "summary": {
          "description": "What it's for.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "summary"
      ],
      "type": "object"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe templates list --format json` writes: the templates\nAscribe carries, and where they're from.",
  "properties": {
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "commit": {
      "description": "The tag's commit.",
      "type": "string"
    },
    "license": {
      "description": "Their license.",
      "type": "string"
    },
    "repository": {
      "description": "The repository of The Good Docs Project's templates.",
      "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"
    },
    "tag": {
      "description": "The tag of theirs the templates were converted from.",
      "type": "string"
    },
    "templates": {
      "description": "The templates, in the set's order.",
      "items": {
        "$ref": "#/$defs/ListTemplate"
      },
      "type": "array"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "repository",
    "tag",
    "commit",
    "license",
    "templates"
  ],
  "title": "TemplatesListReport",
  "type": "object"
}
```

## `ascribe templates eject`

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

```json
{
  "$defs": {
    "Added": {
      "description": "A type eject added to `ascribe.toml`.",
      "properties": {
        "copied": {
          "description": "The fields of its frontmatter declared as another of the project's\ntypes declares them, rather than as plain strings, in order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "guide": {
          "description": "Its guide, from the folder `ascribe.toml` is in, in the order to\nread them: their guide, then Ascribe's notes on the type.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "name": {
          "description": "The type's name, `[types.<name>]`, which is the template's.",
          "type": "string"
        },
        "summary": {
          "description": "Their index's summary of it.",
          "type": "string"
        },
        "template": {
          "description": "Its template, from the folder `ascribe.toml` is in.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "summary",
        "template",
        "guide",
        "copied"
      ],
      "type": "object"
    },
    "Kept": {
      "description": "A type `ascribe.toml` declared already, which eject kept, giving it only\nits template and guide.",
      "properties": {
        "guide": {
          "description": "The guide it was given, from the folder `ascribe.toml` is in, in the\norder to read them: their guide, then Ascribe's notes on the type.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "left": {
          "description": "The type's keys left as they were, in the order `ascribe.toml` has\nthem, such as `purpose` and `frontmatter`.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "name": {
          "description": "The type's name, `[types.<name>]`, which is the template's.",
          "type": "string"
        },
        "summary": {
          "description": "Their index's summary of it.",
          "type": "string"
        },
        "template": {
          "description": "The template it was given, from the folder `ascribe.toml` is in.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "summary",
        "template",
        "guide",
        "left"
      ],
      "type": "object"
    },
    "Refusal": {
      "description": "A template eject refused, and why.",
      "properties": {
        "message": {
          "description": "Why, in a sentence.",
          "type": "string"
        },
        "name": {
          "description": "The name given.",
          "type": "string"
        },
        "path": {
          "description": "The file in the way, from the folder `ascribe.toml` is in, when that's\nthe reason; otherwise null.",
          "type": [
            "string",
            "null"
          ]
        },
        "reason": {
          "$ref": "#/$defs/RefusalReason",
          "description": "Why it was refused."
        }
      },
      "required": [
        "name",
        "reason",
        "path",
        "message"
      ],
      "type": "object"
    },
    "RefusalReason": {
      "description": "Why a template was refused.",
      "oneOf": [
        {
          "const": "unknown",
          "description": "The set has no template of that name.",
          "type": "string"
        },
        {
          "const": "declared",
          "description": "`ascribe.toml` declares a type of that name already.",
          "type": "string"
        },
        {
          "const": "file_in_the_way",
          "description": "A file is where one of its files would be written.",
          "type": "string"
        },
        {
          "const": "type_not_table",
          "description": "Asked to keep the type, `ascribe.toml` writes it as an inline or a\ndotted table, which eject doesn't add to.",
          "type": "string"
        },
        {
          "const": "type_has_template",
          "description": "Asked to keep the type, it names a `template` or a `guide` already,\nor `templates/templates.lock` gives it them.",
          "type": "string"
        },
        {
          "const": "frontmatter_differs",
          "description": "Asked to keep the type, its frontmatter doesn't declare a field the\ntemplate's has, or declares it as something other than a string.",
          "type": "string"
        }
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe templates eject` did: the files it wrote and the types it\nadded, or, when it refused anything, what it refused, and then it wrote\nnothing.",
  "properties": {
    "added": {
      "description": "The types added to `ascribe.toml`, in the order they were named.\nEmpty when anything was refused.",
      "items": {
        "$ref": "#/$defs/Added"
      },
      "type": "array"
    },
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "dry_run": {
      "description": "Whether it ran with `--dry-run`, and wrote nothing.",
      "type": "boolean"
    },
    "kept": {
      "description": "The types `ascribe.toml` declared already and kept, with `--keep-type`,\nin the order they were named: each takes its template and guide from\n`templates/templates.lock`, or, written in another folder, was given\nits `template` and `guide`, and nothing else in it changed. Empty when\nanything was refused.",
      "items": {
        "$ref": "#/$defs/Kept"
      },
      "type": "array"
    },
    "page_declared": {
      "description": "Whether `ascribe.toml` declared no types, so that every page was of\nthe implicit type `page`, and `[types.page]` was written out first,\nas it was, so the pages that aren't of a type added can name it.",
      "type": "boolean"
    },
    "refused": {
      "description": "What was refused, in the order it was named. When it isn't empty,\nnothing was written.",
      "items": {
        "$ref": "#/$defs/Refusal"
      },
      "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"
    },
    "untyped": {
      "description": "The project's pages that name no type, from the folder `ascribe.toml`\nis in, in order. With the types added the project declares types, so\neach needs `type:` in its frontmatter, naming its type.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "written": {
      "description": "The files written, from the folder `ascribe.toml` is in,\n`/`-separated, in the order they were written: each template, its\nguide, and Ascribe's notes on its type, then `templates.lock`, then\n`ascribe.toml`, when it changed. Empty when anything was refused.\nWith `dry_run`, the files it would write.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "written",
    "dry_run",
    "added",
    "kept",
    "refused",
    "page_declared",
    "untyped"
  ],
  "title": "TemplatesEjectReport",
  "type": "object"
}
```

## `ascribe templates status`

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

```json
{
  "$defs": {
    "Change": {
      "description": "Whether the project has changed a template, or a file of one, since the\ncopy.",
      "oneOf": [
        {
          "const": "unchanged",
          "description": "The file is what was written.",
          "type": "string"
        },
        {
          "const": "changed",
          "description": "The file isn't what was written.",
          "type": "string"
        },
        {
          "const": "deleted",
          "description": "The file isn't there.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Nothing is remembered of what was written, so it can't be told.",
          "type": "string"
        }
      ]
    },
    "FileKind": {
      "description": "Which of a template's files a file is.",
      "oneOf": [
        {
          "const": "template",
          "description": "The template, which a page is copied from.",
          "type": "string"
        },
        {
          "const": "guide",
          "description": "Their guide.",
          "type": "string"
        },
        {
          "const": "notes",
          "description": "Ascribe's notes on the type.",
          "type": "string"
        }
      ]
    },
    "FileStatus": {
      "description": "A file of a template the project took.",
      "properties": {
        "kind": {
          "$ref": "#/$defs/FileKind",
          "description": "Which of the template's files it is."
        },
        "matches_set": {
          "description": "Whether the file is the set's text now; null when it isn't there, or\nthe set doesn't have it.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "path": {
          "description": "The file, from the folder `ascribe.toml` is in.",
          "type": "string"
        },
        "project": {
          "$ref": "#/$defs/Change",
          "description": "Whether the project has changed the file since the copy."
        },
        "sections": {
          "description": "What's different in the set by section, when the set changed it and\nthe project didn't, so the file is what was written; otherwise null.",
          "items": {
            "$ref": "#/$defs/SectionChange"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "upstream": {
          "$ref": "#/$defs/UpstreamChange",
          "description": "Whether the set's text has changed since the copy."
        }
      },
      "required": [
        "path",
        "kind",
        "upstream",
        "project",
        "matches_set",
        "sections"
      ],
      "type": "object"
    },
    "NotTaken": {
      "description": "A template of the set the project doesn't have.",
      "properties": {
        "name": {
          "description": "Its name.",
          "type": "string"
        },
        "summary": {
          "description": "Their index's summary of it.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "summary"
      ],
      "type": "object"
    },
    "Record": {
      "description": "What `templates.lock` remembers of a template.",
      "oneOf": [
        {
          "const": "entry",
          "description": "An entry, with a hash of each file as written.",
          "type": "string"
        },
        {
          "const": "no_lock",
          "description": "There's no `templates.lock` where it was looked for.",
          "type": "string"
        },
        {
          "const": "no_entry",
          "description": "The lock is there, and has no entry for it.",
          "type": "string"
        },
        {
          "const": "invalid_lock",
          "description": "The lock is there, and isn't one eject wrote.",
          "type": "string"
        }
      ]
    },
    "SectionChange": {
      "description": "A section that's different in the set.",
      "properties": {
        "change": {
          "$ref": "#/$defs/SectionChangeKind",
          "description": "How it's different."
        },
        "heading": {
          "description": "The section's heading, as written; null for what comes before the\nfirst heading, frontmatter included.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "heading",
        "change"
      ],
      "type": "object"
    },
    "SectionChangeKind": {
      "description": "How a section is different in the set.",
      "oneOf": [
        {
          "const": "added",
          "description": "The set has it, and the copy doesn't.",
          "type": "string"
        },
        {
          "const": "removed",
          "description": "The copy has it, and the set doesn't.",
          "type": "string"
        },
        {
          "const": "changed",
          "description": "Both have it, with different text.",
          "type": "string"
        }
      ]
    },
    "SetRelease": {
      "description": "Which release of theirs a set was converted from.",
      "properties": {
        "commit": {
          "description": "The tag's commit.",
          "type": "string"
        },
        "repository": {
          "description": "Their repository.",
          "type": "string"
        },
        "tag": {
          "description": "Their release's tag.",
          "type": "string"
        }
      },
      "required": [
        "repository",
        "tag",
        "commit"
      ],
      "type": "object"
    },
    "TemplateStatus": {
      "description": "A template the project took: its lock entry, its type, or both.",
      "properties": {
        "copied_from": {
          "description": "Their release the copy was made from, as the lock records it; null\nwithout an entry.",
          "type": [
            "string",
            "null"
          ]
        },
        "files": {
          "description": "Its files: the template, their guide, and Ascribe's notes.",
          "items": {
            "$ref": "#/$defs/FileStatus"
          },
          "type": "array"
        },
        "lock": {
          "description": "The lock its entry is in, or the one looked in when there's no entry,\nfrom the folder `ascribe.toml` is in.",
          "type": "string"
        },
        "lock_problem": {
          "description": "Why the lock can't be read, when `record` is `invalid_lock`; otherwise\nnull.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "Its name, which is its type's.",
          "type": "string"
        },
        "project": {
          "$ref": "#/$defs/Change",
          "description": "Whether the project has changed its copy: `changed` when any of its\nfiles has, or is gone."
        },
        "record": {
          "$ref": "#/$defs/Record",
          "description": "What `templates.lock` remembers of it."
        },
        "upstream": {
          "$ref": "#/$defs/UpstreamChange",
          "description": "Whether the set has changed it since the copy: `changed` when any of\nits files has."
        }
      },
      "required": [
        "name",
        "record",
        "lock",
        "lock_problem",
        "copied_from",
        "upstream",
        "project",
        "files"
      ],
      "type": "object"
    },
    "UpstreamChange": {
      "description": "Whether the set has changed a template, or a file of one, since the copy.",
      "oneOf": [
        {
          "const": "unchanged",
          "description": "The set's text is what was written.",
          "type": "string"
        },
        {
          "const": "changed",
          "description": "The set's text isn't what was written.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Nothing is remembered of what was written, so it can't be told.",
          "type": "string"
        },
        {
          "const": "removed",
          "description": "The set no longer has it.",
          "type": "string"
        }
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe templates status` found: for each template the project\ntook, whether the set and the project have changed it since the copy, and\neach template of the set it doesn't have.",
  "properties": {
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "not_taken": {
      "description": "Each template of the set the project doesn't have, in the set's\norder.",
      "items": {
        "$ref": "#/$defs/NotTaken"
      },
      "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"
    },
    "set": {
      "$ref": "#/$defs/SetRelease",
      "description": "The set this `ascribe` carries, which the copies are compared with."
    },
    "templates": {
      "description": "Each template the project took, in the set's order, then any the set\nno longer has, by name.",
      "items": {
        "$ref": "#/$defs/TemplateStatus"
      },
      "type": "array"
    },
    "upstream_changed": {
      "description": "Whether the set has changed a template the project took since the\ncopy, as `templates.lock` remembers it, or no longer has one. What\n`--exit-code` exits with 1 for.",
      "type": "boolean"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "set",
    "upstream_changed",
    "templates",
    "not_taken"
  ],
  "title": "TemplatesStatusReport",
  "type": "object"
}
```

## `ascribe new`

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

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "What `ascribe new` wrote, or with `--dry-run` would write.",
  "properties": {
    "ascribe_version": {
      "description": "The version of Ascribe that wrote it.",
      "type": "string"
    },
    "guide": {
      "description": "The type's guide, from the folder `ascribe.toml` is in, in the order\nto read it.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "path": {
      "description": "The page, from the folder `ascribe.toml` is in, `/`-separated.",
      "type": "string"
    },
    "placeholders": {
      "description": "How many places the page has that its template left to fill in, as\n`template-placeholder-left` finds them: its placeholders, and the\nfrontmatter values still the template's.",
      "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"
    },
    "template": {
      "description": "The type's template, from the folder `ascribe.toml` is in, or `null`\nwhen it has none and the page is its frontmatter alone.",
      "type": [
        "string",
        "null"
      ]
    },
    "text": {
      "description": "The page's text.",
      "type": "string"
    },
    "title": {
      "description": "The title given, or `null` when the page keeps the template's.",
      "type": [
        "string",
        "null"
      ]
    },
    "type": {
      "description": "Its type.",
      "type": "string"
    },
    "written": {
      "description": "Whether the page was written: `false` with `--dry-run`.",
      "type": "boolean"
    }
  },
  "required": [
    "schema_version",
    "ascribe_version",
    "path",
    "type",
    "title",
    "template",
    "guide",
    "placeholders",
    "written",
    "text"
  ],
  "title": "NewReport",
  "type": "object"
}
```