JSON reports: ascribe templates
The JSON Schemas of what ascribe templates writes 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 templates list
schemas/templates-list.schema.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:
{
"$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:
{
"$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
{
"$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"
}