JSON reports: ascribe init and ascribe model

The JSON Schemas of what ascribe init and ascribe model 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 init and ascribe model write with --format json. Each document follows the rules of the JSON report contract.

ascribe init

The fields of schemas/init.schema.json:

InitReport: What ascribe init did.

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 string[] yes no The files written, from the new project’s folder, /-separated, in the order they were written: with the templates, eject’s files, then ascribe.toml, then ascribe.addresses, unless one was there already. Empty when the templates were refused. With --dry-run, the files it would write.
dry_run boolean yes no Whether it ran with --dry-run, and wrote and made nothing.
content_root string yes no The content root, from the new project’s folder.
content_root_made boolean yes no Whether the content root was made, or with --dry-run would be: false when the folder was there already, or nothing was written.
pages integer yes no How many pages the content root held already. When it held any, ascribe.toml declares no page types, so none of them needs type:.
templates object yes yes What eject did, when the templates were asked for; otherwise null. When its refused isn’t empty, nothing was written.
templates.schema_version integer yes no The version of this schema. It changes only when a field is removed or changes meaning.
templates.ascribe_version string yes no The release of Ascribe that wrote it, as 0.4.5.
templates.written string[] yes no The files written, from the folder ascribe.toml is in, /-separated, in the order they were written: each template, its guide, and Ascribe’s notes on its type, then templates.lock, then ascribe.toml, when it changed. Empty when anything was refused. With dry_run, the files it would write.
templates.dry_run boolean yes no Whether it ran with --dry-run, and wrote nothing.
templates.added object[] yes no The types added to ascribe.toml, in the order they were named. Empty when anything was refused.
templates.added[].name string yes no The type’s name, [types.<name>], which is the template’s.
templates.added[].summary string yes no Their index’s summary of it.
templates.added[].template string yes no Its template, from the folder ascribe.toml is in.
templates.added[].guide string[] yes no Its guide, from the folder ascribe.toml is in, in the order to read them: their guide, then Ascribe’s notes on the type.
templates.added[].copied string[] yes no The fields of its frontmatter declared as another of the project’s types declares them, rather than as plain strings, in order.
templates.kept object[] yes no The types ascribe.toml declared already and kept, with --keep-type, in the order they were named: each takes its template and guide from templates/templates.lock, or, written in another folder, was given its template and guide, and nothing else in it changed. Empty when anything was refused.
templates.kept[].name string yes no The type’s name, [types.<name>], which is the template’s.
templates.kept[].summary string yes no Their index’s summary of it.
templates.kept[].template string yes no The template it was given, from the folder ascribe.toml is in.
templates.kept[].guide string[] yes no The guide it was given, from the folder ascribe.toml is in, in the order to read them: their guide, then Ascribe’s notes on the type.
templates.kept[].left string[] yes no The type’s keys left as they were, in the order ascribe.toml has them, such as purpose and frontmatter.
templates.refused object[] yes no What was refused, in the order it was named. When it isn’t empty, nothing was written.
templates.refused[].name string yes no The name given.
templates.refused[].reason RefusalReason yes no Why it was refused.
templates.refused[].path string yes yes The file in the way, from the folder ascribe.toml is in, when that’s the reason; otherwise null.
templates.refused[].message string yes no Why, in a sentence.
templates.page_declared boolean yes no Whether ascribe.toml declared no types, so that every page was of the implicit type page, and [types.page] was written out first, as it was, so the pages that aren’t of a type added can name it.
templates.untyped string[] yes no The project’s pages that name no type, from the folder ascribe.toml is in, in order. With the types added the project declares types, so each needs type: in its frontmatter, naming its type.
next string yes no The page to read next: the Astro guide, by its permalink.

RefusalReason: Why a template was refused. One of:

Value Description
"unknown" The set has no template of that name.
"declared" ascribe.toml declares a type of that name already.
"file_in_the_way" A file is where one of its files would be written.
"type_not_table" Asked to keep the type, ascribe.toml writes it as an inline or a dotted table, which eject doesn’t add to.
"type_has_template" Asked to keep the type, it names a template or a guide already, or templates/templates.lock gives it them.
"frontmatter_differs" Asked to keep the type, its frontmatter doesn’t declare a field the template’s has, or declares it as something other than a string.

ascribe model

The fields of schemas/model.schema.json:

ModelReport: What ascribe model --format json answers: the content model’s sections, or the one asked for.

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.
apis object[] no no APIs, in declaration order.
apis[].name string yes no Its name, as @operation and api: addresses write it.
apis[].spec string yes no The spec’s file, from the folder ascribe.toml is in.
apis[].reference string yes no Where its reference is: the renderer’s page, or an address pattern, as written.
apis[].renderer string no no The renderer its reference is published with, redoc; absent when reference is an address pattern.
builds object[] no no Builds, in declaration order, a versioned build as one for each live line, the current line first.
builds[].name string yes no Its name.
builds[].variants string yes no Which variant arms it keeps: switch for all of them, or the selection, such as deployment=cloud.
builds[].availability string yes no How it treats availability: badge, or the target it filters for, such as filter self-managed 3.3.
builds[].editor boolean yes no Whether it’s the build the editor checks ([editor] build).
builds[].line string no no For a line of a versioned build, the line, as [releases.<target>] writes it.
builds[].versions string no no For a line of a versioned build, the target it’s versioned by.
checks ModelSetting[] no no [checks]: each key of [checks.vale] and [checks.links], with its value in effect, and each check the file sets, by its slug.
consumer ModelSetting[] no no [consumer]: each key, with its value in effect.
crawlers ModelSetting[] no no [crawlers]: each key, with its value in effect.
dimensions object[] no no Dimensions, in declaration order.
dimensions[].name string yes no Its name.
dimensions[].label string yes no Its label.
dimensions[].values object[] yes no Its values, in display order.
dimensions[].values[].value string yes no The value.
dimensions[].values[].label string yes no Its label.
dimensions[].values[].versionless boolean yes no Whether it has no versions, so an availability spec gives it a state but no version.
editor ModelSetting[] no no [editor]: each key, with its value in effect.
features object[] no no Features, in declaration order.
features[].key string yes no Its key, which an availability spec can name.
features[].name string yes no Its name.
features[].availability string yes no Its availability spec, as written.
fragments object no no [fragments]: the files that are fragments, and the fields a fragment’s frontmatter may give.
fragments.patterns string[] yes no The patterns of the files that are fragments besides those whose path has a file or folder name starting with _, from the content root.
fragments.fields ModelField[] yes no The fields a fragment’s frontmatter may give, in declaration order.
from object[] no no [from]: each file the project takes from, in the order take names them, with what it takes.
from[].file string yes no The file, from the folder ascribe.toml is in.
from[].take string[] yes no What it takes, as take names it: releases, consumer.site.
frontmatter ModelField[] no no [frontmatter]: the fields every page type has, as written, in declaration order. Each type’s fields has them already.
glossary object[] no no Glossary terms, in the order of [glossary] pages, and on each page in document order.
glossary[].id string yes no Its id: its heading’s id.
glossary[].term string yes no The term: its heading’s text.
glossary[].aliases string[] yes no Other ways it’s written.
glossary[].match string yes no Which occurrences are linked: first on each page, every one, or only those a writer links (marked).
glossary[].case_sensitive boolean yes no Whether an occurrence must match its case.
glossary[].page string yes no The file its heading is written in, from the content root: its glossary page, or a fragment the page includes.
glossary[].line integer yes no The heading’s line in that file, from 1.
images ModelAttribute[] no no [images.attributes]: the keys an image’s attribute block may give, in declaration order.
intended object[] no no [[intended]]: the acknowledged problems, in declaration order.
intended[].check string yes no The check, by its slug.
intended[].kind string yes no What it’s about: phrase, feature, or image.
intended[].name string yes no Its key, or the image’s path.
intended[].reason string yes no Why the problem is intended.
lifecycle object[] no no Lifecycle states: the built-in ones, as the project adjusts them, then the ones it declares.
lifecycle[].name string yes no Its name, which an availability spec gives.
lifecycle[].label string yes no Its label.
lifecycle[].available boolean yes no Whether content in it counts as available.
lifecycle[].builtin boolean yes no Whether it’s built in, rather than declared by the project.
listing ModelSetting[] no no [listing]: each key, with its value in effect.
navigation ModelNavSection no no The project’s navigation, its root section: every page that isn’t unlisted, in order, as each build’s _ascribe/nav.json has its share of it. In the whole report, and with --section navigation.
notes object[] no no Note types, the values of @note’s type: the built-in ones, as the project labels them, then the ones it declares.
notes[].name string yes no Its name, which @note’s type gives.
notes[].label string yes no Its label.
notes[].builtin boolean yes no Whether it’s built in, rather than declared by the project.
phrases object[] no no Phrases, in declaration order.
phrases[].key string yes no Its key, written {key} in a page.
phrases[].value string yes no Its value.
project ModelSetting[] no no [project]: each key, with its value in effect.
releases object[] no no [releases.<target>], in declaration order: each target’s lines, with their status.
releases[].target string yes no The target: a versioned dimension value.
releases[].lines object[] yes no Its lines, newest first: planned, live, then archived.
releases[].lines[].line string yes no The line, as the list writes it.
releases[].lines[].status string yes no current, live, planned, or archived.
releases[].lines[].builds string[] yes no The builds that are this line, one for each build versioned by the target: site@3.4, or site for the current line.
sources object[] no no Sources, in declaration order.
sources[].name string yes no Its name, as addresses write it: code: for a source named code.
sources[].path string yes no Its folder, relative to the project’s folder: the path written, or, for a source in another repository, the folder of its copies.
sources[].include string[] yes no The patterns of the files it makes readable, relative to its folder; empty for every file.
sources[].ignore string[] yes no The patterns of the files it doesn’t make readable, though include matches them.
sources[].git object yes yes The repository it’s in, for a source in another repository.
sources[].git.url string yes no Its URL.
sources[].git.branch string yes yes The branch an update follows; null for the repository’s default.
sources[].examples object no no Its tested examples, for a source with an ascribe.examples.toml: absent for any other. For a source in another repository, they’re read from its copies.
sources[].examples.valid boolean yes no Whether its ascribe.examples.toml can be read. One that can’t makes no file an example.
sources[].examples.files integer yes no How many of the files the source makes readable its config makes examples.
sources[].examples.observations object[] yes no Its observations, in name order: those that can’t be read left out.
sources[].examples.observations[].name string yes no Its name: default, or the name ascribe observe --name gave it.
sources[].examples.observations[].environment { [name]: string } yes no Its environment as it has it, by name: os, arch, and each entry’s kept line.
sources[].examples.observations[].tested string yes no What a page says it was tested with, by this observation alone.
sources[].examples.observations[].listed integer yes no How many files it lists. For a source in another repository, only those it has copies of, since the others weren’t copied.
sources[].examples.observations[].current integer yes no How many of those are as it found them: the rest changed since, or are gone.
types object[] no no Page types, in declaration order: the implicit page type when none is declared.
types[].name string yes no Its name, which each page of the type gives as its type; the implicit page type’s pages give none.
types[].fields ModelField[] yes no Its frontmatter fields, in declaration order.
types[].guide string[] no no What to read before writing a page of the type, in the order to read it, from the folder ascribe.toml is in, from the type’s guide or the lock, as template is; absent when it has none.
types[].purpose string no no What a page of the type is for, as the content model says; absent when it says nothing.
types[].template string no no The page a page of the type starts from, from the folder ascribe.toml is in: the type’s template, or the one templates/templates.lock gives a type that names neither a template nor a guide; absent when it has none.
versions ModelSetting[] no no [versions]: each key, with its value in effect.
widgets object[] no no Project widgets, in declaration order.
widgets[].name string yes no Its name, written @name.
widgets[].description string yes yes What it’s for, as the content model describes it.
widgets[].line boolean yes no Whether it may be one line.
widgets[].container boolean yes no Whether it may be a container, closed by @end.
widgets[].attributes ModelAttribute[] yes no Its attributes, in canonical order.

ModelSetting: A key of a section of settings, such as [consumer], as the registry of ascribe.toml’s keys has it, with the value in effect.

Field Type Required Nullable Description
table string yes no The table it’s in, as ascribe.toml writes it: consumer, checks.vale.
key string yes no The key: in checks, a check’s slug.
kind string yes no What its value is: switch, choice, number, text, level, list, or table.
set boolean yes no Whether ascribe.toml sets it.
default any no no The value used when the file leaves it out, when that’s one value.
default_text string no no What’s used when the file leaves it out, in the reference’s words, when that isn’t one value.
from string no no The file it’s taken from, when [from] takes it: a path from the folder ascribe.toml is in. Its value is that file’s, and it’s set.
value any no no The value in effect: the file’s, else the default. Absent when the file leaves it out and its default isn’t one value.

ModelField: A frontmatter field.

Field Type Required Nullable Description
name string yes no Its name.
type string yes no Its type in short form: string, list(string), enum(a, b).
required boolean yes no Whether every page of the type must give it.
values string[] yes no The values it allows, for an enumeration or a list of one; empty otherwise.
description string yes yes What it’s for, as the content model describes it.
fields ModelField[] yes no An object’s fields; empty for any other type.
declared string no no Which table declares a page type’s field: frontmatter for [frontmatter], which every type shares, type for the type’s own frontmatter, or implicit for the required string title neither declares. Absent on an object’s fields.

ModelAttribute: An attribute a widget accepts.

Field Type Required Nullable Description
key string yes no The key.
type string yes no The value’s type: string, number, boolean, enum, set, or note-type.
values string[] yes no The values it allows, for enum and a set of named values; empty otherwise.
required boolean yes no Whether every use must give it.
default string yes yes The value used when it’s left out, as written (a set’s members joined by |).
description string yes yes What it’s for.

ModelNavSection: A section of the navigation: a folder and its pages, in order.

Field Type Required Nullable Description
folder string yes no The folder, from the content root, ending in /; "" for the root.
label string yes no Its label: from ascribe.nav, else its own page’s title as plain text, else its folder’s name with - and _ as spaces and its first letter capitalized, and “Start” for the root.
pages ModelNavPage[] yes no Its pages in order, its own page not among them.
sections ModelNavSection[] yes no Its nested sections with a page, in order: each one whose own page is among pages right after that page, then the rest.
listed boolean yes no Whether ascribe.nav lists it.
page ModelNavPage no no Its own page: its index.md, or the page beside the folder with its name, which is then one of the parent’s pages too.

ModelNavPage: A page of the navigation.

Field Type Required Nullable Description
source string yes no Its path from the content root.
label string yes no Its label as plain text: its nav-label, else its title, else its file name without .md.
type string no no Its page type’s name, when it has one.