Skip to main content
A collection declares its fields with Field.*. Each constructor emits a SnackBase storage definition plus the semantic metadata every surface switches on: which renderer a value gets, which operands a filter may use against it, and whether it can be sorted. Unknown types raise at declaration rather than at schema sync. Which ui.* primitive renders a type is decided by the type, not by the surface, so a date is a date picker in a form, a table cell, and a filter bar alike.

The registry

This table is generated from serialize_registry() in src/snackapp/fields/registry.py. It is not transcribed, so it cannot describe a registry that has changed.
currency and full_name compile their operands against sub-paths (value.amount, name.first). SnackBase’s filter validator allows a JSON-typed column nothing but IS NULL / IS NOT NULL, so those expressions parse and the backend rejects them until SnackBase gains JSON-path filtering. Filtering inside a composite is a compile-level capability today, not a live one — which is why a collection searched by name wants a text display field.

Composite contracts

Four shapes are fixed by the registry, which validates them on the way in and on the way out. A value that does not match raises ValidationError rather than reaching storage.

currency — {amount, code}

Both keys are required. The aggregate endpoint refuses sum() over a JSON column, so a number a board column or a dashboard has to total should be Field.number, not Field.currency.

full_name — {first, last}

Either key may be null; a value that is not an object raises.

address — {street1, street2, city, region, postcode, country}

Every key is present in the stored value, missing ones as null.
Each entry needs a value. Exactly one entry is primary: a second claim is dropped, and a list that claims none gets it on the first entry.

Types

Field.text

A single line. unique becomes a unique index on the column.

Field.long_text

Many lines, stored as text, rendered as a textarea.

Field.rich_text

A document, stored as json and edited with TipTap. The value is a string of HTML — what the editor emits and what the display sanitises and renders; an object with an html key is accepted too. Not sortable: a document has no order.

Field.number

The only type sum() and avg() accept, which is what a board column total and a dashboard aggregate need.

Field.currency

Money as {amount, code}.

Field.percent

A number rendered with a % suffix. Stored as the number, not as a fraction.

Field.rating

Stars. max above 10 raises.

Field.boolean

A switch.

Field.date

A calendar day, with no time and no zone. ui.calendar places records on one of these.

Field.datetime

An instant, stored in UTC.

Field.select

One of options, stored as text. The choices drive the editor, and ui.kanban takes its columns from them when none are named.

Field.multi_select

Several of options, stored as json. Not sortable: a set has no order.

Field.email

Validated as an address, and marked PII with email masking.

Field.emails

Several addresses as [{value, label, primary}].

Field.phone

One number, marked PII with phone masking.

Field.phones

Several numbers as [{value, label, primary}].

Field.url

Validated as a URL and rendered as a link.
Several URLs as [{value, label, primary}].

Field.full_name

A person’s name as {first, last}.

Field.address

A postal address as {street1, …}.

Field.json

Anything JSON. Its only operands are is_empty and is_not_empty, because that is all the backend can ask of a JSON column.

Field.array

A JSON list, filtered with the array operands.

Field.file

One upload, stored as a file reference.

Field.files

Several uploads, stored as json.

Field.relation

One record of the to collection. display names the field a chip shows; without it the target’s label_field, then name, then title, then id is used. on_delete is "restrict", "set_null", or "cascade". A column of relations is expanded by the backend in one batched lookup, so a hundred rows with an owner cost the row query plus one lookup.

Field.relation_many

Several records of the to collection. A multi-relation is what a ui.record(tabs=[{"field": ...}]) tab lists.

Field.user

A user of this account. on_delete="cascade" raises: deleting a person must not delete their records. access="private" adds one of these as owner when the collection does not declare it.

Computed fields

Field.computed

A column the backend computes on read. It is read-only in every editor — a table cell, a field grid, a form, and the CSV import wizard all refuse it — because there is nothing to write to. return_type is "text", "number", "boolean", or "datetime". It decides the operand set (text or number) and the sortability: text, number, boolean, and datetime sort; anything else does not. The permitted functions are exactly: date_diff and date_add take a string-literal unit: 'days', 'hours', 'minutes', 'seconds', 'months', or 'years'.

Declared view placeholders

A declared default view — views= on a collection — cannot name the caller or the current month when it is written, so four placeholder values are substituted where the filter is read: