The types of fields: what each takes, how it keeps a value, and how it filters.
| Type | A value | Options |
|---|---|---|
text | a text | long: a text of several lines |
number | an integer or a number | format: number, integer, percent or currency; decimals; currency ("EUR") |
checkbox | true or false | |
date | a day, or a moment with time | time: a day and a time, kept in UTC |
select | one of the choices | choices (Cardbox.Choice) |
multi_select | some of the choices | choices |
status | one of the choices, each of a group (to do, doing, done) | choices |
person | the id of a person or an agent of your app | multiple: several |
url, email, phone | a text of that form | |
relation | records of a collection | collection_id (required); limit: at most so many; two_way: the other collection shows the links too, in a field named reverse_name (its own name unless given) |
created_at, updated_at | when the record was made, changed | read-only |
created_by, updated_by | who made it, changed it last | read-only |
How values are kept
A record's values are one JSON map, by field key (Cardbox.Record).
An empty value is no key at all: a text of no characters, an empty
list and an unticked checkbox are kept as nothing, so "is empty" is one
question whatever the type. A day is "2026-10-25", a moment
"2026-10-25T14:30:00Z", both of which sort as text; a choice is its id;
a relation a list of record ids.
The four read-only types are the record's own columns, and are not in its values.
Values given
cast/3 takes what a form posts, what an agent sends and what Elixir
code has: "12.5" and 12.5 for a number, "2026-10-25" and a
Date for a date, a choice's id or its name for a select. Each value
is checked against its field, and an error says what the field takes.
Summary
Functions
Checks a value given for a field, and returns it as it is kept: nil for
an empty value.
Checks a type's options, with previous, the field's options before (so a
choice renamed keeps its id). Returns them as they are kept.
How a field's values compare: :text, :number, :boolean, :date
(a day), :datetime, :choice (one id) or :list (several).
The types, by name.
The filter operators of a field (Cardbox.Filter).
Whether a field sorts: every field but those of several values.
Whether a type is one of the record's own columns, which nobody writes.
Types
Functions
Checks a value given for a field, and returns it as it is kept: nil for
an empty value.
opts: :time_zone, where a day and a time given without an offset are
(UTC unless given).
Checks a type's options, with previous, the field's options before (so a
choice renamed keeps its id). Returns them as they are kept.
How a field's values compare: :text, :number, :boolean, :date
(a day), :datetime, :choice (one id) or :list (several).
A value as it is kept, read for Elixir: a Date or a DateTime for a
date, false for an unticked checkbox, [] for an empty list.
@spec names() :: [String.t()]
The types, by name.
The filter operators of a field (Cardbox.Filter).
Whether a field sorts: every field but those of several values.
Whether a type is one of the record's own columns, which nobody writes.