Field types#

Every field sets a type. That choice decides what the field becomes in each language and which extra keys it accepts.

type

Extra keys

Python

TypeScript

Go

boolean

—

bool

boolean

bool

string

min_length, max_length

str

string

string

integer

min, max (ints)

int

bigint

big.Int

decimal

min, max (decimals)

Decimal

Decimal (decimal.js)

decimal.Decimal

estimate

min, max (floats)

float

number

float64

list

values, min_length, max_length

list[T]

Array<T>

[]T

map

keys, values, min_length, max_length

dict[K, V]

ModelMap<K, V>

mdl.Map[K, V]

model

model_type

the referenced type in each language

ref

referenced_type, model, on_delete, on_update

<Target>Ref, holding the target’s key

time

window

datetime.time

string

TimeOfDay

datetime

window

datetime.datetime

Temporal.ZonedDateTime

time.Time

date

—

datetime.date

Temporal.PlainDate

Date

path

root, relative_to, source

str

string

Path

file

max_size, content_types

FileInfo

FileInfo

mdl.File

isbn

—

str

string

ISBN

uuid

version

uuid.UUID

string

mdl.UUID

url

base

yarl.URL

URL

url.URL

nerd_font_glyph

—

libnerd_font.Glyph

Glyph (libnerd_font)

nerdfont.Glyph

password

—

str

string

secret.Password

secret

—

str

string

secret.Secret

constant

subtype, value, enum_name

Literal[value]

the value’s literal type

the base type

opaque

—

Any

unknown

any

Every constraint key is optional. min_length and max_length are natural numbers. On a string they count Unicode code points in every output — Python, TypeScript, Go, and PostgreSQL alike — not bytes, not UTF-16 code units, and not graphemes.

Constraints are metadata carried into the generated code, so pick the type by what the value is: decimal when exactness matters, such as money, and estimate for approximate floats, such as a rating.

Nested types#

list.values, map.keys, and map.values take a nested type, not a field. A nested type is an inline mapping with its own type and its own constraints, and never takes display, desc, or required — those belong to fields only.

  metadata:
    display: Metadata
    desc: Product metadata
    type: map
    keys:
      type: string
      min_length: 1
    values:
      type: string

  matrix:
    display: Matrix
    desc: A list of lists
    type: list
    values:
      type: list          # nested types nest arbitrarily
      values:
        type: integer
        min: 0

A map key must be a single value: not a list, a map, a struct or a union, since every format writes it as the text of an object key. An enum is a single value, and so is a ref, which is written as its target’s key, a Nerd Font glyph, which is written as its full name, and a url, which is written as its value is. A key cannot be a secret or a password, nor a ref to a struct keyed by one, since a key is written out in the clear.

Embedding another type#

A model field points at another top-level type by name, through model_type. The name must match another file’s basename in the same directory.

  customer:
    display: Customer
    desc: The customer who placed the order
    type: model
    model_type: Person
    required: true

  products:
    display: Products
    desc: List of products in the order
    type: list
    required: true
    min_length: 1
    values:
      type: model
      model_type: Product

A model field embeds: PostgreSQL flattens the target’s columns into this table, prefixed with the field name. It creates no foreign key. For that, use a ref.

Foreign keys#

A ref field names a row in another table rather than embedding its shape. Its value is that row’s primary key.

The target must be a top_level: true struct with exactly one primary_key field, and that field must be a single value: not a list, a map, or a struct. It cannot be a url with a base yet. It can be another ref, as long as that ref’s own target meets these rules. A chain of keys like that must end somewhere, so a struct can’t be keyed by a reference that leads back to itself. When it is a path with a root, the reference holds the absolute path the key resolves to in that root, not the value as written; see Rooted paths.

  customer:
    display: Customer
    desc: The person who placed the order
    type: ref
    referenced_type: Person
    required: true
    on_delete: cascade

On the wire, a reference is the bare key, the same value the target’s key field holds. In memory it is the target’s reference type, PersonRef, which every language declares beside Person when something refers to it. A client library, the TypeScript output and the Go client, declares one for every top_level struct with a single key, so that another model can refer to it:

Language

PersonRef

Resolve

Go

struct{ Key big.Int }

Resolve(ctx) reads the row with the postgres feature, and returns errors.ErrUnsupported without it; the Go client’s reads it from the server (see Types)

Python

Ref[Person, int], from model.ref

resolve() raises NotImplementedError

TypeScript

class extends Ref<Person, bigint>

resolve() reads it from the server with the REST client, and rejects without one (see Resolving references)

The name <Target>Ref is reserved for every top-level struct, so no other type may take it.

A ref can be a field of any struct, top-level or not, a list or map value, a map key, or a primary key. As a primary key it may be the struct’s only key or one of several, and its column holds the target’s key under a foreign key, so a row cannot outlive the row its key names unless on_delete allows it.

A reference to a struct keyed by a reference holds that reference. Suppose Profile is keyed by user: ref User. Then a ref to Profile holds a ProfileRef whose Key is a UserRef. On the wire, in its column, and in a URL, it is written as User’s key, the key at the end of the chain. Such a reference cannot be a map key yet. A ref map key is written as its target’s key, for example {"42": ...}, and two refs are the same key when their keys are equal. A ref to a struct whose key is an enum cannot be a map key yet, because Go cannot name that ref type in mdl.KeyType.

on_delete and on_update take no_action (the default), restrict, cascade, set_null, or set_default. The last two are rejected on a required reference and on a list or map item, since they would write NULL over a value that cannot be null.

Validate() never checks a reference, not even that the row exists. It is handed a single value in memory and cannot know which rows exist. Only the system of record can answer that, so the foreign key is what enforces a reference. required: true makes its column NOT NULL.

Reference cycles are allowed, where a cycle of model fields is still an error: embedding expands one shape into another and has no finite form, while a reference only names a row.

PostgreSQL gets a FOREIGN KEY clause on the reference’s column, including the column of a list or map item, or of a map key, in its child table. Tables are ordered so every target is created first. A key closing a cycle cannot be written inline, so it is added afterwards as an ALTER TABLE and marked DEFERRABLE INITIALLY DEFERRED — checked at commit, which is the only way both rows of a cycle can be written.

PostgreSQL indexes the key a foreign key targets, not the columns referring to it, so each reference also gets an index on its columns, named <table>_<column>_index. Without it, deleting or rekeying a target row, and finding the rows that refer to it (Go’s ReferencedBy), reads the whole referring table.

References into another model#

A ref with a model key names a struct of another model, which another server stores, such as the accounts of an auth server. Every model referring to a user then names the one Account, rather than each copying it:

  owner:
    display: Owner
    desc: The account the note belongs to
    type: ref
    model: auth
    referenced_type: Account
    required: true

model names a foreign model in model.toml. Its types are loaded, to check the target and learn its key, but never generated: each language imports the target’s reference type from the client library the foreign model’s own output is, so a Go field is an authapi.AccountRef of its Go client package, and a TypeScript one an AccountRef of its TypeScript module. The target is the struct as a client sees it, without the fields no response carries, and has to meet the same rules as any target’s.

Its target is not in this model’s store, so:

  • PostgreSQL gets no FOREIGN KEY, and no index, for it: the column holds the key and nothing checks that the row exists. on_delete and on_update must be no_action.

  • Go’s ReferencedBy and Related, and the REST .../referenced_by and .../related, do not count it, and a summary cannot include it.

  • In Go, Resolve(ctx) is the Go client’s, which reads the row from the foreign model’s server through the client WithClient put in ctx.

Two models cannot refer into each other: loading one would load the other forever, so it is an error.

Dates#

A date field is a calendar day with no time of day and no zone, such as a birthday or a due date. It is serialized as "YYYY-MM-DD" in every format, and a day that does not exist, such as "2023-02-29", is rejected. Use datetime for an instant.

Datetimes#

A datetime field is an instant and the time zone it was written in. It is serialized as RFC 9557 text in every format, the timestamp followed by the zone’s IANA name in brackets:

2026-10-06T21:00:00-04:00[America/New_York]

Each language keeps the zone: Python as an aware datetime.datetime with a ZoneInfo, TypeScript as a Temporal.ZonedDateTime, Go as a time.Time with its Location, and PostgreSQL in a second <column>_zone column (see Datetimes). All three languages write the same text for the same value.

A plain RFC 3339 timestamp is accepted on input, as is a native TOML or YAML timestamp. Z is the zone UTC, and a numeric offset is a zone fixed at that offset, written back as 2026-10-06T21:00:00-04:00[-04:00]. A timestamp with no offset, an unknown zone name, or an offset the zone does not have at that instant is rejected. Two datetimes are equal when their instants are, whatever their zones, so a map holds one key per instant.

Time windows#

A time field is a time of day, serialized as "HH:MM:SS". "HH:MM" is also accepted on input. A datetime field is an instant — a date and a time with a zone — and takes the same window key.

Its one extra key, window, is not a constraint. It is the hours the field’s values typically fall in, and it exists so a loosely typed clock entry like 7 can be read the way the person meant it.

start_time:
  display: Start Time
  desc: Time of day the stream starts
  type: time
  required: true
  window:
    from: "18:00"
    to: "02:00"

to is exclusive, and a to at or before from wraps midnight, as above. A field that declares no window falls back to 09:00–21:00, under which 7 reads as 7:00 PM and 10 as 10:00 AM.

The window reaches every language. Go compiles it into the generated Fyne New<Field>Entry widget, TypeScript exports it as <Struct><Field>Window, and Python emits it as a <field>_window class constant. It never affects validation: a value outside the window is still valid. Time input behavior states the behavior in full.

Paths#

A path field is a slash-separated filesystem path.

  location:
    display: Location
    desc: Where the document lives in the tree
    type: path
    required: true

A segment may hold any text except /. Spaces, dots, and non-ASCII all round-trip, which is exactly the rule a real path segment already follows. A segment may not be empty, so repeated and trailing separators are errors rather than something to normalize away, and one path has exactly one text form.

The leading / is part of the value: /a/b and a/b are different paths and never compare equal. / alone is the empty absolute path, and "" the empty relative one.

Roots and bases#

Two optional keys say where a path’s file is. root names the filesystem the path lives in, and / is the top of that filesystem. relative_to is what a relative value resolves against inside the root: a literal absolute path, or another path field on the same struct.

  package:
    display: Package file
    desc: Where the book's manifest lives
    type: path
    root: books

  cover:
    display: Cover
    desc: The cover picture
    type: path
    root: books
    relative_to:
      kind: field
      field: package

A value is never rewritten. It is decoded, encoded and stored exactly as written, and resolves only when code opens the file. A base that names a file resolves against the directory the file is in. So with package set to /book/book.toml and cover to ./cover.png, cover opens book/cover.png in the books root. .. stops at the top of the root, and an absolute value ignores relative_to. With no relative_to, a relative value resolves against the top of the root. In Go, each field with a root gets a With<Field> method that opens the file through a function you name in model.toml; see Path roots. Python and TypeScript keep the value as written and open nothing. PostgreSQL keeps the value as written too, and beside it the absolute path it resolves to, which the Go code computes on every write; a rooted primary key is keyed on that resolved path. See Rooted paths.

relative_to can also name a field of the struct’s root; see Root bases.

The model is checked for these rules:

  • relative_to needs a root.

  • A literal base is an absolute path: {kind: literal, path: /notes}.

  • A field base names a path field on the same struct, not the field itself, and not a list or map of paths. That field has the same root.

  • Field bases cannot form a cycle.

  • A path in a union variant’s value cannot have a root yet.

root and relative_to can also go on the path values of a list or map, and on the path keys of a map. A path with neither key is a pure path: with no root there is nothing to resolve it in, so no resolution or clean-up happens, in any language or in PostgreSQL. It behaves as described above, . and .. segments included, and /a/./b and /a/b stay two different values.

Support differs by language. Go gets a Path type that parses, compares, and stores the value — see The go-runtime API. TypeScript’s valibot schema checks the grammar. Python carries a path as a plain str and does not validate it, because the type declares no constraints and so has no hook in the msgspec generator.

For how a path is stored and ordered in PostgreSQL, see PostgreSQL.

Source paths#

source: true makes a path field hold the file its struct was read from. The field is set from the file’s path, and is not written in the file.

  file:
    display: File
    desc: The file this manuscript was read from
    type: path
    required: true
    source: true
    root: books

  cover:
    display: Cover
    desc: The cover picture, beside the manuscript's file
    type: path
    root: books
    relative_to:
      kind: field
      field: file

The value is the file’s absolute path in the filesystem it was read from. A base that names a file resolves in its directory, so cover above opens beside the manuscript’s file. Everywhere but the file, the field is an ordinary path: REST carries it, and PostgreSQL stores it.

Only Go supports source paths now: see Source files. Python and TypeScript treat the field as an ordinary path, so a file that Go wrote has no key for it there.

The model is checked for these rules:

  • A source path is a field of a top_level struct, not the values or keys of a list or map.

  • A struct has one source path at most.

  • A source path has no relative_to and no xml binding.

  • A struct with a source path is not a field, list item or union variant of another type, because its path would then be written in another file. Refer to it with a ref, or make it an inlined variant of a file union.

Files#

A file field is bytes its row owns: an avatar, an attachment. The file has no name of its own, and lives and dies with its row. It is stored in the row’s table, so a write of the row and its file commits or rolls back as one, and a backup of the database holds it.

  avatar:
    display: Avatar
    desc: The user's picture
    type: file
    max_size: 2097152
    content_types: [image/png, image/jpeg, image/gif, image/webp]

Use a path instead when the file exists apart from the row, or its name matters, and for anything large or streamed: PostgreSQL reads a file whole, so a file is for a few MiB at most.

The field’s value is not the file but what the server recorded of it when it was uploaded, which is all the row’s JSON, YAML or TOML ever holds:

{"content_type": "image/png", "size": 1234, "sha256": "9f86d0…"}

content_type is the type the server sniffed from the content, with any parameters (text/plain; charset=utf-8), never the type a client claimed. size is in bytes, and sha256 is the content’s SHA-256 in hex. The bytes are at the row’s file URL, <row URL>/file/<field>, where a GET reads them and a POST uploads them; see File fields. Only an upload sets the field, so a client cannot change it. It can clear it, which deletes the file.

The two constraint keys are both optional:

  • max_size is the largest file in bytes. A larger upload is refused with 413.

  • content_types lists the media types the content may be sniffed as, bare and in lower case, as image/png. A sniffed type is matched without its parameters, so text/plain allows text/plain; charset=utf-8. Another type is refused with 415.

A file is a direct field of a top_level struct. It cannot be in a list, a map, a union, or a struct that is not a table, nor in a struct embedded in another, since its bytes belong to its own row. It cannot be part of a primary key, and it cannot be required: a row is created before a file is uploaded to it. A file is never part of a summary, and never searched.

Only the Go output’s postgres feature stores files; a Go output without it is refused. PostgreSQL holds a file in four columns; see Files. Go holds the value as an mdl.File, TypeScript as a read-only FileInfo from @omniblack/model-runtime, and Python as a model.file_info.FileInfo.

ISBNs#

An isbn field is an International Standard Book Number.

  isbn:
    display: ISBN
    desc: The book's ISBN
    type: isbn
    required: true

It reads an ISBN-10 or an ISBN-13, and hyphens and spaces may separate the digits. It holds the compact ISBN-13: "0-306-40615-2", "0306406152" and "978 0 306 40615 7" all decode to "9780306406157", and that is what every format writes back. So one book has one value, and its two ISBNs compare equal.

A wrong check digit is rejected. So is an ISBN-10 whose last character is a lower-case x rather than X, and an ISBN-13 that does not start with 978 or 979. The Go, Python, and TypeScript outputs accept and reject exactly the same strings.

Quote an ISBN in a hand-written YAML or TOML file. Unquoted, it is an integer, and an ISBN-10 such as 0306406152 loses its leading zero. Go still reads it, because its YAML decoder keeps the text, but Python refuses it.

Support differs by language. Go gets an ISBN type, built only by parsing, so an invalid one cannot exist; its zero value holds no number, and encoding it fails — see The go-runtime API. TypeScript’s valibot schema checks and converts the value. Python normalizes it in from_raw, which needs the isbn extra, pip install model[isbn]. As for every other field, Python does not check an ISBN passed to a struct’s constructor. In PostgreSQL, the column is the isn extension’s isbn13 — see PostgreSQL.

UUIDs#

A uuid field is an RFC 9562 universally unique identifier. Its one extra key, version, is the version, 1 to 8, every value must have; leave it out to take a UUID of any version.

  id:
    display: Identifier
    desc: The ticket's identifier
    type: uuid
    version: 7
    required: true
    primary_key: true

It reads the hyphenated hex form, 0190f5c6-7d8e-7a3b-9c4d-5e6f7a8b9c0d, in either case, and writes it lower-case. Braces, a urn:uuid: prefix and bare hex are rejected. The Go, Python, and TypeScript outputs accept and reject exactly the same strings. The nil UUID, all zeros, is a value like any other.

A value of another version breaks the version constraint, which is checked where constraints are: by Validate in Go and validate in Python, by the valibot schema in TypeScript, and by a CHECK in PostgreSQL.

Go holds a UUID as an mdl.UUID, which compares with ==; its zero value holds no UUID, and encoding it fails — see The go-runtime API. Python holds a uuid.UUID, and TypeScript the lower-case string. PostgreSQL stores it as uuid. A uuid can be a primary key, and so fills one segment of a REST or route path, as /api/ticket/0190f5c6-7d8e-7a3b-9c4d-5e6f7a8b9c0d.

URLs#

A url field holds an absolute URL: yarl.URL in Python, the global URL in TypeScript, net/url’s url.URL in Go, and text in PostgreSQL.

Its one extra key, base, is what a relative reference resolves against. It is a literal URL, or another url field on the same struct:

  homepage:
    display: Homepage
    desc: The site's front page
    type: url
    required: true

  docs:
    display: Docs
    desc: The site's documentation
    type: url
    base:
      kind: literal
      url: https://docs.example.com/manual/

  icon:
    display: Icon
    desc: The site's icon
    type: url
    base:
      kind: field
      field: homepage

A literal base must be absolute. A field base must name a url field on the same struct, and not the field itself. A base can also name a url of the struct’s root; see Root bases. A base field can have a field base of its own, but the fields cannot form a cycle. base can also go on the url values of a list or map, and on the url keys of a map. A map’s keys and values each resolve against their own base:

  titles:
    display: Titles
    desc: The title of each page, keyed by the page
    type: map
    keys:
      type: url
      base:
        kind: field
        field: homepage
    values:
      type: string

A url key is compared by its absolute URL, so about.html and https://example.com/site/about.html against that homepage are the same key.

On decode, a reference is resolved against the base as RFC 3986 describes. With homepage set to https://example.com/site/, an icon of img/icon.png becomes https://example.com/site/img/icon.png. With no base, a relative reference is rejected. So is a reference against an optional base field that is absent. The value in memory, and in PostgreSQL, is always the absolute URL, so a column can be indexed and compared.

On encode, Go and Python write a URL relative to its base when the scheme, user, host and port are the same:

  • A URL under the base’s directory is written relative to that directory, such as img/icon.png.

  • Any other URL on the same host is written from the root, such as /news.xml.

  • A URL on a different host is written in full.

Decoding what was encoded gives the same URL. TypeScript has no encoder: JSON.stringify writes a URL as its absolute href, which every decoder accepts.

Each language parses a URL with its own library, so two languages can spell the same absolute URL differently. For example, the WHATWG parser adds a / to https://example.com. test/url-cases.json lists the spellings that all three agree on.

Python resolves the URL in from_raw, which needs the url extra, pip install model[url]. As with every other field, Python does not check a URL passed to a struct’s constructor. In Go, url.URL.String has a pointer receiver, so call it on a field or on Optional.Ptr, not on the result of GetOrZero.

Root bases#

A url base and a path relative_to can also name a field of the struct’s root. Give the struct a root_type (see Writing a model), and write the base as {kind: root, field: <dot path>}. The dot path starts at the root:

# Passage.yaml: a Passage is in a list in a Story, which is in a list in an
# Anthology.
root_type: Anthology
fields:
  link:
    display: Link
    desc: The passage's page, relative to its story's page
    type: url
    required: true
    base:
      kind: root
      field: stories.*.homepage

  file:
    display: File
    desc: The passage's file, relative to the anthology's manifest
    type: path
    required: true
    root: books
    relative_to:
      kind: root
      field: manifest

Each segment names a field. Every segment except the last is a field that embeds a struct, or a list or map of structs followed by *. The last is a url field for a url base, or a path field in the same root for a path base. A * is the element that holds the struct. So stories.*.homepage is the homepage of the story that the passage is in, not of some other story.

The model is checked for these rules:

  • The struct that holds the field declares a root_type.

  • Each segment is a field, and * follows only a list or map.

  • A list or map that the path goes through is followed by *.

  • The path leads to a url field for base, or to a path field in the same root for relative_to, and not to the field itself.

  • Every place the root embeds the struct is inside the path up to its last *. A struct that is also in a list outside stories cannot use stories.*.homepage.

  • A url base is decoded before the url, so the first field after the last * cannot hold the struct. Path bases cannot form a cycle.

A url resolves when its root is decoded. The root, or the element that the last * stands for, reads the base as it decodes. Then it gives the base to the structs below it. Encoding writes each url relative to its base again. A struct that is decoded without its root has no root base, so a relative url is rejected, as for an optional base field that is not set. It is written absolute.

In Go, the With<Field> method of a path with a root base takes the root, and the index or key of the element that each * stands for, before its other arguments:

func (self *Passage) WithFile(root *Anthology, storiesIndex int, use func(fsys fs.FS, name string) error) error

An index or key that is not in the root returns mdl.ErrNoBase. PostgreSQL stores the resolved path as for any rooted path, from the root row that is written.

Constants#

A constant field always holds one value, which the model gives in value. subtype says what kind of value it is: integer, string, or enum. An enum constant names a top-level enum in enum_name, and one of its members, by name, in value.

  kind:
    display: Kind
    desc: Always "circle"
    type: constant
    subtype: string
    value: circle
    required: true

  priority:
    display: Priority
    desc: Circles are always high priority
    type: constant
    subtype: enum
    enum_name: Priority
    value: high
    required: true

subtype

Python

TypeScript

Go

PostgreSQL

string

Literal["circle"]

"circle"

string

text

integer

Literal[2]

2n

big.Int

numeric

enum

Literal[Priority.high]

typeof Priority.high

Priority

priority

Go has no literal types, so a Go field is the type the constant is a value of.

Every output refuses another value. Python and TypeScript refuse it when they decode, and Go refuses it when it decodes and reports it from Validate(), since Go code can set any value of the base type. Python’s validate() reports one too. In PostgreSQL, the column is the base type, with a CHECK that it equals the constant. An enum constant is stored as its member’s value, as an enum field is.

In Python, a required constant field defaults to its constant, so a struct can be built without it. The key is still required on the wire.

A constant can only be a struct field. It cannot be a list or map value, a map key, or a union variant.

Nerd Font glyphs#

A nerd_font_glyph field holds one Nerd Font glyph. On the wire, and in PostgreSQL, a glyph is its full name: its set, a :, and its name, as in md:folder. In memory, the field holds the glyph object of the libnerd_font client for the language: Glyph in Python and TypeScript, and nerdfont.Glyph in Go.

  icon:
    display: Icon
    desc: The glyph the shortcut is drawn with
    type: nerd_font_glyph
    required: true

Decoding looks the name up in libnerd_font and rejects a name that is not a glyph. The name must be exact: nothing is trimmed or folded to lower case, so MD:folder and md_folder are both rejected. So is md-folder, the glyphnames.json spelling that model used before it moved to a :. Encoding writes the full name back. test/nerd-font-glyph-cases.json lists the names that the Go, Python, and TypeScript outputs all accept and reject.

A glyph can be a map key. The key is written as the glyph’s full name, and two keys are the same when they are the same glyph.

Generated code needs libnerd_font at run time, in each language:

  • Python needs the nerd_font extra, pip install model[nerd_font]. The client loads the libnerd_font C library when it is imported. As for every other field, Python does not check a value passed to a struct’s constructor.

  • TypeScript imports Glyph and lookup from the libnerd_font npm package, which is the library compiled to WebAssembly. It is an ES module that awaits the WebAssembly at the top level, so a CommonJS consumer needs a bundler. JSON.stringify writes a Glyph as its full name.

  • Go imports gitlab.com/terryp/libnerd_font/clients/go. It loads the C library at run time without cgo. Set LIBNERD_FONT_PATH to the library’s path if it is not where the dynamic loader looks. The zero nerdfont.Glyph is no glyph, and encoding it fails.

In PostgreSQL, the column is text. Reading back a name that is not a glyph is an error — see PostgreSQL.

Passwords and secrets#

A password field holds a password, and a secret field holds a value the program reads back, such as an API token. In Go both are kept in guarded memory by go-secret: memfd_secret pages that are out of the kernel’s direct map, never swapped, and readable only inside a callback.

  password:
    display: Password
    desc: The password, stored as its hash
    type: password
    required: true
    perms:
      read: false
  api_token:
    display: API Token
    desc: The token the account calls the API with
    type: secret
    required: false
    perms:
      read: false
      update: accounts.admin

A password is a plaintext going in and its Argon2id hash coming out. Go decodes a plaintext into guarded memory and writes the hash, in the PHC string format ($argon2id$v=19$m=65536,t=3,p=4$…). Where the value comes from decides how it is read: text, from JSON, YAML, TOML or XML, is always a plaintext, and only a PostgreSQL column holds a hash. So a hash sent over the wire is hashed again, like any other plaintext, and cannot stand in for the password it was made from. It follows that decoding what Go wrote does not give back the same password, which is why a password field is usually read: false. Password.Check tells whether a password matches, and Password.Plain hands over the plaintext, to check its quality before it is stored.

A secret writes what it read. Writing it means copying it out of guarded memory, so a secret that should stay on the server is declared with read: false, as above. That keeps it out of every response, and the same holds for a password’s hash. Neither type can be part of a summary, and neither is searched.

Go compares two secrets in constant time inside guarded memory. It compares two passwords the same way when both are plaintexts, and by their hash when both are hashes. A plaintext never equals a hash, even its own. So sending a password back counts as changing it, as far as an update perm is concerned.

Neither may be empty: Go and TypeScript both reject "".

Support differs by language:

  • Go imports gitlab.com/terryp/model/go-runtime/secret, which needs Linux with memfd_secret and building with GOEXPERIMENT=runtimesecret. Only a model with a password or secret field imports it. The zero value of either type holds nothing, and encoding it fails. A generated struct’s Destroy wipes both, and a route wrapper calls it on each request; see Destroying secrets and The go-runtime API.

  • TypeScript holds both as a string.

  • Python holds both as a str, for now.

In PostgreSQL a password is its hash, as text, and a secret is its plaintext, as bytea — see Passwords and secrets.

Opaque values#

An opaque field holds any JSON value — an object, an array, a string, a number or a boolean — and the model neither validates it nor looks inside it. It is for data whose shape is someone else’s: a server can store a client’s blob, and the client decode it with a model of its own.

  app:
    display: App Settings
    desc: The app's own settings, which it decodes itself
    type: opaque
    required: false

It is Any in Python, unknown in TypeScript and any in Go, and takes no constraints. null is no value: a required field holding it is missing, and reports is required, and an optional one is absent. It is not a string type, so "" is a value, as 0 and false are. A JSON merge patch replaces the value whole rather than merging into it, since the model cannot tell what its keys mean.

Go decodes it as encoding/json decodes into any, so an object is a map[string]any and a number a float64. To read it as a type of your own, marshal it back to JSON and decode that.

An opaque field has no PostgreSQL column, and cannot be in a summary.