Field types#
Every field sets a type. That choice decides what the field becomes in each
language and which extra keys it accepts.
|
Extra keys |
Python |
TypeScript |
Go |
|---|---|---|---|---|
|
— |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
the referenced type in each language |
||
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
— |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
— |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
— |
|
|
|
|
— |
|
|
|
|
— |
|
|
|
|
|
|
the value’s literal type |
the base type |
|
— |
|
|
|
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 |
|
Resolve |
|---|---|---|
Go |
|
|
Python |
|
|
TypeScript |
|
|
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_deleteandon_updatemust beno_action.Go’s
ReferencedByandRelated, and the REST.../referenced_byand.../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 clientWithClientput inctx.
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_toneeds aroot.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
rootyet.
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_levelstruct, not thevaluesorkeysof a list or map.A struct has one source path at most.
A source path has no
relative_toand noxmlbinding.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_sizeis the largest file in bytes. A larger upload is refused with413.content_typeslists the media types the content may be sniffed as, bare and in lower case, asimage/png. A sniffed type is matched without its parameters, sotext/plainallowstext/plain; charset=utf-8. Another type is refused with415.
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 samerootforrelative_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 outsidestoriescannot usestories.*.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
|
Python |
TypeScript |
Go |
PostgreSQL |
|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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_fontextra,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
Glyphandlookupfrom thelibnerd_fontnpm 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.stringifywrites aGlyphas its full name.Go imports
gitlab.com/terryp/libnerd_font/clients/go. It loads the C library at run time without cgo. SetLIBNERD_FONT_PATHto the library’s path if it is not where the dynamic loader looks. The zeronerdfont.Glyphis 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 withGOEXPERIMENT=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’sDestroywipes 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.