schema:metaschema

`schema:metaschema@0.0.0`

`version`

Field	Type	Required	Default	Description
`major`	`integer`	Yes		The first segment of the version as written: `1` in `1.2.3`
`minor`	`integer`	No	`0`	The second segment: `2` in `1.2.3`, and `0` where the version was written without one
`patch`	`integer`	No	`0`	The third segment: `3` in `1.2.3`, and `0` where the version was written without one
`prerelease`	`string`	No	`""`	How this version has moved since it was released, with its own leading `-`, or empty where it has not. `-dev` marks a schema whose content has changed since the version it declares; a release replaces it with the bumped version and no suffix.

Written as, for example:

"1.2.3"
"0.1"
"2.0.0-dev"

`typeVariant`

One of the types string, typeDefinition.

`externalSchemaSpec`

Field	Type	Required	Default	Description
`id`	`string`	No		The referenced schema document by coordinate, `<namespace>:<name>@<version>`, resolved against the schema store of the repository holding the referencing document. A coordinate written without a version, or with `@latest`, floats. An entry locates its document by `id` or by `path`, and `id` is read first.
`path`	`string`	No		The referenced schema document as a file path, relative to the document making the reference, or as a `file://` URI. For a reference inside one module; read where the entry states no `id`.
`name`	`string`	No		A second name a field may reach this entry by, beside the alias it is keyed under: `<name>.<definitionKey>` resolves as `<alias>.<definitionKey>` does
`target`	`string`	No		The Python package whose generated `__types__` package holds the referenced classes. Generated code imports them from there, which makes the reference a runtime dependency on that package. Required unless `vendor` is `true`.
`typeOnly`	`boolean`	No	`false`	Whether the generated import is written under `if TYPE_CHECKING:`, so the referenced classes serve annotations and are never imported at run time. Accepted only in a definition that declares `generics`; it still needs a `target` and cannot be combined with `vendor`.
`vendor`	`boolean`	No	`false`	Whether the referenced definitions, and the definitions those reference in turn, are generated into the referencing package's own `__types__` package, so its generated code imports nothing from the package that owns the schema. Needs no `target` and cannot be combined with `typeOnly`.

`schemaMetadata`

Field	Type	Required	Default	Description
`schemaVersion`	`version`	Yes		The meta-schema version this schema document was written under -- the referencing end, hand-written here alone because this document defines the grant that fills it in everywhere else
`name`	`string`	No		The schema's name, the second part of the coordinate `<namespace>:<name>@<version>` an exported schema is referenced by. A field in the document may also name one of its own definitions as `<name>.<definitionKey>`.
`version`	`version`	Yes		The version this schema defines itself at -- the defining end, which every schema has and none may omit. Three segments, so a hotfix to a released schema has one to move; a `-dev` suffix marks content that has changed since this version was released.
`namespace`	`string`	No		The namespace the schema is published under, the first part of the coordinate `<namespace>:<name>@<version>`. An exported schema needs it, and `name`, to be resolvable by coordinate.
`export`	`boolean`	No	`false`	Whether the schema is published: `true`, with a `name` and a `namespace`, puts it in a schema store, where another document references it by coordinate through the `id` of an `externalSchemas` entry. `false` keeps it internal to the module that holds it, reachable by `path` alone.
`documentRoots`	`list[string]`	No	`[]`	The definitions in this schema that describe a stored document rather than a component of one. Each named definition is granted a `schemaVersion` field -- the referencing end -- so a document can say what it was written under without its author declaring the field. A definition left out describes a component, and a component carries no version of its own. A schema that describes no document names none.

`typeDefinition`

Field	Type	Required	Default	Description
`base`	`enum` one of `list`, `dict`, `union`, `enum`	Yes		Which structured type this is: a `list` of `item`, a `dict` from `key` to `item`, a `union` of the types in `anyOf`, or an `enum` of the strings in `enumValues`
`enumValues`	`list[string]`	No		For `base: enum`: the string values the field may hold. A set that more than one field holds is declared once instead, as a definition stating `enum`.
`item`	`typeVariant`	No		For `base: list`, the type of each element; for `base: dict`, the type of each value. Absent, elements and values are of any type.
`key`	`typeVariant`	No		For `base: dict`: the type of each key. Absent, keys are strings.
`anyOf`	`list[typeVariant]`	No		For `base: union`: the types a value may be. A value is tried against each in the order written.

`toStringSpec`

Field	Type	Required	Default	Description
`label`	`string`	No		The field whose value heads a rendered node, in place of the type name
`children`	`string`	No		The list field whose items are rendered as this node's own children, without a heading of their own

`shorthandSpec`

Field	Type	Required	Default	Description
`pattern`	`string`	Yes		A regular expression a string must match to be read as a value of the definition. Each named capture group fills the field of that name, so every group names a declared field and there is at least one; a group that matched nothing leaves its field to its default.
`format`	`string`	No		A template that renders a value back to its string form on serialization, declared only where the string holds everything the value does. A `{field}` placeholder names a declared field and may reach into that field's own fields, as `{version.major}`; a stretch between `[` and `]` renders only when every placeholder inside it has a value.

`genericConfig`

Field	Type	Required	Default	Description
`optional`	`boolean`	No	`false`	Whether a field typed by this parameter may hold no value: the generated type variable is bound to a model or `None`, where otherwise it is bound to a model alone
`covariant`	`boolean`	No	`false`	Whether the generated type variable is declared covariant, so the definition parameterized by a subtype is accepted where it is expected parameterized by the base type
`contravariant`	`boolean`	No	`false`	Whether the generated type variable is declared contravariant, so the definition parameterized by a base type is accepted where it is expected parameterized by a subtype

`fieldSpec`

Field	Type	Required	Default	Description
`type`	`typeVariant`	Yes		What the field holds: a built-in type token, the key of a definition in the same document, an `<alias>.<definitionKey>` reference through `externalSchemas`, a type parameter the definition declares in `generics`, or a structured type stating a `base`. A field written as a bare string states this and nothing else.
`help`	`string`	No		A sentence saying what the field holds or is for. It becomes the description of the generated field, readable at run time, and is published in documentation beside the field's name and type.
`format`	`string`	No		A template the field's value is rendered through on serialization, of `{field}` placeholders naming fields of the definition the field is typed by: `{major}.{minor}` writes a version as two segments. Accepted only on a field whose type is a reference to a definition.
`optional`	`boolean`	No	`false`	Whether a document may leave the field out. Left out with no `default`, the field holds no value, except a boolean, which is `false`.
`default`	`any`	No		The value the field takes where a document leaves it out. On a field typed by an enum it is one of the enum's values; on a field typed by a model it is that model's shorthand string, or `{}` for the model built from its own defaults.
`alias`	`string`	No		The key a document writes the field under, where that is not the field's name here, as a key holding a hyphen is not: `x-normalize` for `xNormalize`
`xNormalize`	`list[string]`	No		Normalization rules applied to the field's value when a document is loaded, after any the field's type declares. Each is a built-in rule, a parameterized form such as `sort-by:<key>`, or `local:<rule>` for a hook the package owning the schema supplies.
`xValidate`	`list[string]`	No		Validation rules the field's value must pass when a document is loaded, after any the field's type declares. Each is a built-in rule, a parameterized form such as `pattern:<regex>`, or `local:<rule>` for a hook the package owning the schema supplies.

`schemaDefinition`

Field	Type	Required	Default	Description
`name`	`string`	Yes		The definition's name, which its generated class and module are named from: `module-kind` generates the class `ModuleKind` in the module `module_kind`. It may not contain a period.
`fields`	`dict[string, fieldSpec]`	No	`{}`	The fields of a model, by field name. Each is a field spec, or a bare type as the short form of a spec stating only `type`. Not declared beside `anyOf` or `enum`.
`anyOf`	`list[typeVariant]`	No		The types a value of this definition may be, which makes the definition a union: a named type alias with no fields of its own. Not declared beside `fields`, `enum`, `extends`, `protocol` or `generics`.
`enum`	`list[string]`	No		The values this definition names, declared once so every field holding that set references it rather than spelling the values again
`protocol`	`boolean`	No	`false`	Whether a structural interface is generated beside the model, named `<Class>Protocol` and declaring the same fields, for code that accepts anything of that shape. Only a model may declare it: not a union, an enum or a definition with `generics`.
`extends`	`string`	No		The definition this model inherits its fields from, by its key in this document or as an `<alias>.<definitionKey>` reference. An enum cannot be extended, and a union, an enum or a definition with `generics` cannot extend.
`generics`	`dict[string, genericConfig]`	No	`{}`	The type parameters of a generic definition, by parameter name; a field names one as its `type`. A name written with no configuration takes every default. A generic definition is generated as a frozen dataclass and not as a validated model, so it declares no `anyOf`, `protocol`, `extends` or `shorthand`, and its fields declare no `alias`, `x-normalize` or `x-validate`.
`shorthand`	`shorthandSpec`	No		A string form a value of this model may be written in, expanded into its fields when a document is loaded, and optionally the template that renders it back. Needs declared `fields` and is not supported beside `generics`.
`examples`	`list[any]`	No	`[]`	Values of this definition as a document writes them, shown to a reader beside the definition. Worth stating for a definition whose values are written in a form of its own, such as one declaring `shorthand`; each should load as a value of the definition.
`toString`	`toStringSpec`	No		How a value of this model is rendered as text for a reader: which field heads it, and which list field holds the items rendered as its children
`xNormalize`	`list[string]`	No		The normalization rules every field of this type carries, run before the field's own
`xValidate`	`list[string]`	No		The validation rules every field of this type carries, run before the field's own

`schemaDocument`

Field	Type	Required	Default	Description
`metadata`	`schemaMetadata`	Yes		What the document is: the meta-schema version it is written under, the version the schema defines itself at, the name and namespace it is published by, and which of its definitions describe a stored document
`externalSchemas`	`dict[string, externalSchemaSpec]`	No	`{}`	The other schema documents this one references, each under an alias. A field names a definition in one by writing `<alias>.<definitionKey>` as its type.
`definitions`	`dict[string, schemaDefinition]`	Yes		The types the schema declares, by key. A field in the same document names one by its key, and a field in another document names it as `<alias>.<definitionKey>`.
`sourceUri`	`string`	No		Where the document was read from, as a `file://` URI. Filled in when the document is loaded and never written in one; a reference by relative `path` resolves against it.
`sourcePath`	`any`	No		Where the document was read from, as a file path. Filled in when the document is loaded and never written in one; read where `sourceUri` is absent.