Writing a model#
A model is a directory of *.yaml files. Each file defines exactly one
top-level type, and the file’s basename is the type’s name — Person.yaml
defines Person. Use PascalCase filenames. The loader reads every *.yaml
directly in the directory; it does not recurse, and it does not read .yml.
Renaming a type means renaming its file, and updating every model_type,
inner_type, and enum-valued tag_type that named it.
Every file sets type: to one of five kinds:
|
Is |
|---|---|
|
A named record of fields. |
|
A named, tagged set of values. |
|
A tagged choice between variants. |
|
An HTTP endpoint with a request and two response types. |
|
An HTTP endpoint serving the files of a path root. |
display, a human label for user interfaces, and desc, a description, are
required on every top-level type and on every field, value, and variant. They
are not decoration: desc becomes the docstring, JSDoc comment, or Go comment
in the generated output, and the column comment in PostgreSQL.
Struct#
type: struct
display: Person
desc: A person with various attributes
fields:
name:
display: Name
desc: The person's name
type: string
required: true
email:
display: Email
desc: Email address with length constraints
type: string
required: true
min_length: 5
max_length: 100
tags:
display: Tags
desc: List of tags
type: list
required: false # optional; omit `required` to default to false
min_length: 1
max_length: 10
values:
type: string
fields maps field name to field definition. Every field has display,
desc, type, and an optional required that defaults to false. The
remaining keys depend on the type — see Field types.
Set top_level: true on a struct to persist it as a PostgreSQL table. See
PostgreSQL.
A struct that is not top_level may set root_type to the top_level struct
it always lives under:
type: struct
display: Chapter
desc: A chapter of a book
root_type: Book
fields: {}
The root must embed the struct, directly or through lists, maps and other
structs. A ref field does not count. Every other type that embeds the struct
must be a struct with the same root_type, so each path to the struct starts
at its root. root_type changes no generated code by itself. It lets a url
base or a path relative_to name a field of the root; see
Root bases. The automodel docs show it as a link to the
root.
Summary#
A struct may declare a summary: a short description of a value, for search
results, pickers, and a reference’s label. It is a title line, and an
optional subtitle under it.
type: struct
display: Person
desc: A person
summary:
fields: [name, employer, tags]
title: '**{{.name}}**{{with .employer}}, of {{.}}{{end}}'
subtitle: '{{with .tags}}Likes {{list "and" .}}{{end}}'
fields: { ... }
title and subtitle are Go
text/templates, and fields names the
fields they read. The title stands on its own: an autocomplete menu, or another
summary that includes this one, shows only it. A search result shows the
subtitle under it, when it renders to some text. Each field is in both
templates’ data under its field name:
Field |
Its value in the template |
|---|---|
a |
its text |
a |
the Go |
an enum |
its value’s |
a struct ( |
that struct’s own summary title |
a |
the summary title of the row it names, or its key when that row is not read |
a |
a list of them, which |
An unset optional field and an empty list are absent, so {{with .x}} and
{{if .x}} test them. A struct or row that a summary includes must declare
one of its own, and no summary may include itself, through any number of
structs and references. Map, union, external, opaque, nerd_font_glyph
and constant fields cannot be in a summary.
Each rendered line is inline Markdown: one paragraph, with no headings,
lists, or other blocks, to render as HTML or in a terminal. A template’s own
text is Markdown, such as the ** above. A field’s text is escaped, so a name
like a*b* shows as written; a struct’s or a row’s title is already
Markdown, and is included as it is.
image names a field that pictures the value: a url, or a path with a
root, but not a list or map of either. It does not have to be in fields,
and the templates do not see it. A REST listing
item links to it as its image.
summary:
fields: [name]
title: '**{{.name}}**'
image: portrait
Perms#
A top_level struct may set perms, the perm each REST action on its rows
requires, and a field may set its own; see Perms.
Enum#
type: enum
display: Priority
desc: Task priority levels
values:
low:
value: 0
display: Low
desc: Low priority
medium:
value: 1
display: Medium
desc: Medium priority
values maps member name to {value, display, desc}. A value is an integer
or a string, and every member must be the same kind. tag_type (int or
str) is inferred from the first member’s value; set it explicitly only to be
unambiguous.
An integer enum generates an IntEnum in Python and its equivalent
elsewhere; a string enum generates a StrEnum.
Union#
type: union
display: Animal
desc: A tagged union of animal kinds
tag_type: str # str | int | <name of an enum type>
tag_name: kind # JSON discriminator key; defaults to "tag"
variants:
Dog:
tag: dog # discriminator value; defaults to the variant name
inner_type: Pet
Cat:
inner_type: Pet # tag omitted -> "Cat"
inline_value: true # Pet's fields beside the tag, not under "value"
Names:
inner_type: # any nested type, as in a list's `values`
type: list
values:
type: string
min_length: 1
variants maps variant name to {inner_type, tag?, inline_value?}.
inner_type is the type of the variant’s value. It is a nested type, the
same mapping a list’s values takes, with its own constraints. A bare name,
such as Pet, is shorthand for {type: model, model_type: Pet}.
tagis the discriminator value written into the serialized form. Omit it and it defaults to the variant name. Every tag must matchtag_type.tag_typeisstr,int, or the name of an enum type in the model. It is inferred when omitted:strif the first variant has notag, otherwise from the firsttag’s type. Forstrandinta dedicated<Name>Tagenum is generated to hold the tags; when it names an existing enum, that enum is reused.tag_nameis the key holding the discriminator in serialized data. It defaults totag, and it cannot bevalueunless every variant is inlined.inline_value: truewrites a variant’s struct flat, as described below. Only a variant holding a struct can set it, and the struct must not have a field namedtag_name.
A union is serialized as an object of two keys: the discriminator, and the
variant’s value under value. This is the same for every kind of value.
An inlined variant is the exception: its struct’s fields sit beside the
discriminator.
{"kind": "dog", "value": {"name": "Rex", "age": 3}}
{"kind": "Names", "value": ["Rex", "Mog"]}
{"kind": "Cat", "name": "Mog", "age": 2}
Validation errors follow the same shape. A violation is reported under
value (value.name), or, for an inlined variant, at the struct’s own path
(name).
Each variant becomes its own type named <Union><Variant>: the Dog variant
of Animal is AnimalDog in every language. A variant may therefore share
its name with the type it holds. The variant name alone is still what the
serialized tag defaults to, what the tag enum members are named after, and
what PostgreSQL column names are built from.
Every generated type name must be unique across the model — the model’s own
types, each <Name>Tag enum, each <Union><Variant> type, and each
top-level struct’s <Name>Ref. A model where two of those collide fails to
load.
File unions#
file: true makes a union read from a file of its own. The file holds one
variant’s struct, with the tag beside its fields, so a directory can mix
kinds of records:
type: union
display: Holding
desc: One record file of the library, by its kind
tag_name: kind
file: true
variants:
Manuscript: {tag: manuscript, inner_type: Manuscript, inline_value: true}
Colophon: {tag: colophon, inner_type: Colophon, inline_value: true}
kind: manuscript
id: a
title: Ants
Every variant of a file union sets inline_value, and holds a top_level
struct with a source path. A file union is
not a field of another type, since it is read from its own file.
Only Go reads and writes file unions now: see File unions. Python and TypeScript generate the union as usual.
Route#
A route is an HTTP endpoint. It names three types the model already defines: what the request carries, what a success returns, and what a failure returns.
type: route
display: Route Op Changes
desc: API endpoint for route operations
method: POST
path: /route_op/changes
request: OptimizedStop
success_response: RouteResponse
error_response: ErrorResponse
go:
handler: HandleRouteOpChanges
Key |
Meaning |
|---|---|
|
One of |
|
The URL path the endpoint is served at, with optional |
|
The top-level type a request body decodes to. |
|
The top-level type returned on success. Optional: leave it out for a route with no model success body. |
|
The top-level type returned on failure. |
|
Optional: |
|
The name of the Go function you write to serve it. |
A route without a success_response still succeeds: its Go handler may
return a status, headers, or a raw body, but not a model, and its TypeScript
interface’s success arm carries only is_success.
A TypeScript route call sets status, is_created, is_accepted, and
is_no_content beside the response’s fields, so neither the
success_response nor the error_response may declare a field of those
names.
A route may set perm, the perm calling it requires; see
Route perms. A route may also set the key of any
extension the model enables. The build warns about a key
that neither a route nor an enabled extension claims.
Merge patch routes#
A PATCH route that sets merge_patch: true takes an
RFC 7386 JSON merge patch of its
request struct, rather than the struct itself. A field the patch sets
replaces the stored one, and a nested struct merges field by field. A field
it sets to null is cleared, and a field it leaves out stays as it is. The
patch says what changes, and the handler applies it to a value of its own:
type: route
display: Route Preferences
desc: Changes the reader's preferences
method: PATCH
path: /preferences
request: Preferences
success_response: Preferences
error_response: ErrorResponse
merge_patch: true
go:
handler: HandleRoutePreferences
The route must be a PATCH with a struct request, and its path can’t
have placeholders, since a patch carries only the fields it changes. Go
gives the handler a <Request>Patch,
and both clients send the patch as written, with its nulls kept: Go’s takes
it as JSON bytes, and TypeScript’s as a MergePatch<Request>.
Path placeholders#
A segment of path written as {name} is a placeholder. It fills the
request field called name from that part of the URL:
path: /owners/{owner}/stops/{stop}
request: StopLookup
Each placeholder must fill a whole segment and must name a string, integer,
UUID, or enum field of the request struct, once. An enum is written in the URL
by its member name. {$}, ServeMux’s end-of-path anchor, is allowed as the last
segment and names nothing.
A segment written as {name...} is a rest-of-path wildcard. It fills a path
field from the segments it matches, and a path field can be filled only this
way. A path has at most one {name...}, in any position, and a path with one
cannot also end in {$}:
path: /owners/{owner}/tree/{location...}
request: TreeLookup
path: /owners/{owner}/tree/{location...}/meta
request: TreeLookup
The wildcard’s value is the path’s text as written: /owners/3/tree/a/b gives
the relative path a/b. An absolute path writes its leading / as %2F, so
/owners/3/tree/%2Fa/b gives /a/b. A . or .. segment is written as
%2E or %2E%2E, because Go’s ServeMux removes the unescaped forms from a
URL before it matches the URL to a route.
When two routes differ only by what follows the wildcard, a URL goes to the
route with the longer match after it. So with both routes above,
/owners/3/tree/a/meta always goes to the /meta route, with the location
a. The first route cannot receive a location whose last segment is meta.
What a route generates differs sharply by language, because only one of the three can serve HTTP on its own:
Go emits working handler wrappers, routing, body decoding, and status selection. You write the handler function; see Go.
TypeScript emits an interface for you to implement. No client, no server wiring; see TypeScript.
Python emits nothing at all for routes.
Routes are separate from the REST endpoints in Go REST endpoints, which are
generated from top_level structs rather than written by hand.
Root endpoint#
A root endpoint serves the files and directories of a
path root over HTTP, with no handler of your
own. It is generated for Go, where
Serving a root describes what it answers, and the
TypeScript Client calls it.
type: root_endpoint
display: Book Files
desc: The files of the books root, and its directory listings.
root: books
path: /files/books/{path...}
perm: books.read
Key |
Meaning |
|---|---|
|
The root it serves, a key of |
|
Literal segments, then one |
|
Optional: the perm reading the root requires, as a route’s. |
It answers GET and HEAD, at path, at path with a trailing /, and at
the literal prefix, with or without one. A route or another root endpoint
that matches the same requests fails the model’s load, as two routes do.
Dependencies between types#
model fields, union inner_types, and enum-valued tag_types all name
another top-level type by its file basename. A nested type names one through
its model_type, wherever it sits. The loader sorts types
topologically so that dependencies are emitted first. Chains are fine; cycles
are not supported.
Queryable fields#
The Go find feature lets end users
query a struct’s fields. Every field stored in one column is queryable unless
it sets a read perm. queryable: false opts one out, for a field that may be
read but should not be filtered or sorted on:
fields:
internal_code:
display: Internal Code
desc: A code only the back office sorts by.
type: string
queryable: false
Free text still finds a word such a field holds, since it reads the search
index. To keep it out of the search index, set searchable: false (see
Full-text search).
A field’s TypeScript metadata has queryable as
what a query can do, not as the key is written: it is false as well for a
read perm or a type with no operators.