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:

type

Is

struct

A named record of fields.

enum

A named, tagged set of values.

union

A tagged choice between variants.

route

An HTTP endpoint with a request and two response types.

root_endpoint

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#

Person.yaml#
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:

Chapter.yaml#
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.

Person.yaml#
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 string, integer, decimal, estimate, date, datetime, time, url, path, isbn, or uuid

its text

a boolean

the Go bool, so {{if .active}} tests it

an enum

its value’s display

a struct (model)

that struct’s own summary title

a ref

the summary title of the row it names, or its key when that row is not read

a list of any of those but booleans

a list of them, which {{list "and" .}} joins as “a, b, and c” (or "or")

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

Only Go renders a summary; see Summaries and Summaries.

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#

Priority.yaml#
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#

Animal.yaml#
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}.

  • tag is the discriminator value written into the serialized form. Omit it and it defaults to the variant name. Every tag must match tag_type.

  • tag_type is str, int, or the name of an enum type in the model. It is inferred when omitted: str if the first variant has no tag, otherwise from the first tag’s type. For str and int a dedicated <Name>Tag enum is generated to hold the tags; when it names an existing enum, that enum is reused.

  • tag_name is the key holding the discriminator in serialized data. It defaults to tag, and it cannot be value unless every variant is inlined.

  • inline_value: true writes 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 named tag_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:

Holding.yaml#
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}
drafts/a.yaml#
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.

RouteOpChanges.yaml#
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

method

One of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

path

The URL path the endpoint is served at, with optional {name} placeholders.

request

The top-level type a request body decodes to.

success_response

The top-level type returned on success. Optional: leave it out for a route with no model success body.

error_response

The top-level type returned on failure.

merge_patch

Optional: true to make the body a merge patch of request.

go.handler

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:

RoutePreferences.yaml#
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.

BookFiles.yaml#
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

root

The root it serves, a key of [tool.model.go.roots].

path

Literal segments, then one {name...} wildcard, which names the file or directory in the root.

perm

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.