Choices, quantities, and ratings
These types put meaning in the schema. A choice has a governed catalog; a quantity has one declared unit; a rating has one declared scale. Clients can therefore interpret a bare record value without guessing what it means.
Type matrix​
| Type | Record write | Canonical read | Required configuration | GraphQL output |
|---|---|---|---|---|
select | Option UUID/value, or an array when multi-select | Option UUID or UUID array | Options; optional is_multiselect, min_items, max_items | Enum when single; [String] when multiple |
state | State UUID or value | State UUID | States with a color | Generated enum |
capacity | JSON number | JSON number | unit_kind, unit_ref | Float |
measure | JSON number | JSON number | unit_ref | Float |
currency | JSON number | JSON number | currency_code | Float |
rating | JSON number | JSON number | Positive max | Float |
The unit, currency, and rating maximum belong to the attribute definition and are not repeated on every record. If one field needs mixed units or currencies, it is not one coherent attribute: normalize the values before writing or model separate fields.
Select​
Use select for a controlled classification. Each option has an immutable id, a mutable machine value,
a display title, and a position.
{
"slug": "category",
"type": "select",
"name": {"en": "Category", "de": "Kategorie"},
"options": [
{"value": "hvac", "title": "HVAC"},
{"value": "elevator", "title": "Elevator"},
{"value": "lighting", "title": "Lighting"}
]
}
A write may use "hvac" or that option's UUID. A read returns the UUID. This lets a schema owner rename
the value without rewriting every record or invalidating a durable integration that stored the ID.
For declarative object updates:
- include an option
idto preserve identity across a value rename; - an id-less option with the same current value also keeps its identity; and
- an omitted option is deleted and can make existing values invalid, so treat removal as a data migration.
Multi-select​
Set is_multiselect: true when a record can carry several choices:
{
"slug": "certifications",
"type": "select",
"name": {"en": "Certifications", "de": "Zertifizierungen"},
"config": {
"is_multiselect": true,
"min_items": 1,
"max_items": 5
},
"options": [
{"value": "tuv", "title": "TÜV"},
{"value": "iso_9001", "title": "ISO 9001"}
]
}
The record value is an array. Merge patch replaces the entire selection: omit the key to preserve it,
send the desired complete array to change it, and send [] or null to clear it when allowed.
GraphQL turns a single select into an enum. Multi-select output remains [String]. If two option values
normalize to the same GraphQL symbol, Tourfold adds a stable suffix derived from the immutable option ID;
download the workspace schema instead of predicting collision names.
State​
Use state when the value represents a lifecycle position rather than a neutral category. A state
requires a color in addition to identity, value, title, and position.
{
"slug": "lifecycle",
"type": "state",
"name": {"en": "Lifecycle", "de": "Lebenszyklus"},
"states": [
{"value": "in_service", "title": "In service", "color": "#16A34A"},
{"value": "maintenance", "title": "Maintenance", "color": "#F59E0B"},
{"value": "retired", "title": "Retired", "color": "#64748B"}
]
}
Tourfold validates membership but does not invent transition rules between custom states. If only
true and false matter, use Boolean. If users may select several independent labels, use multi-select.
State writes accept a UUID or current value and reads return the UUID. As with options, send existing IDs during declarative schema updates to preserve identity across a rename. GraphQL exposes the current state values through a generated enum.
Capacity​
Use capacity for an amount whose unit is either a physical measure or a counted Tourfold object.
Physical capacity:
{
"slug": "tank_capacity",
"type": "capacity",
"name": {"en": "Tank capacity", "de": "Tankkapazität"},
"config": {
"unit_kind": "measure",
"unit_ref": "00000000-0000-4000-8000-000000000701"
}
}
Counted-object capacity uses unit_kind: "object" and the target object's UUID as unit_ref—for
example the maximum number of technicians a resource can accommodate. The record still stores one
numeric amount; it does not create relationships to that many records.
A measure unit cannot be deleted while any capacity or measure attribute of an Object, Task or
Vehicle definition references it: DELETE /api/v2/measure-units/{id} answers
409 capacity/measure-unit-in-use and lists the referencing attributes in data.references. Remove
or retarget those attributes first.
Measure​
Use measure for a physical measurement with one measure-unit identity:
{
"slug": "cooling_output",
"type": "measure",
"name": {"en": "Cooling output", "de": "Kühlleistung"},
"config": {
"unit_ref": "00000000-0000-4000-8000-000000000702"
}
}
The number is stored without a second unit field. Convert incoming values into the declared unit before
writing and convert for display only at the edge of your application.
The referenced unit is protected the same way as for capacity: it cannot be deleted while this
attribute exists.
Currency​
Use currency for money in one ISO 4217 currency:
{
"slug": "replacement_cost",
"type": "currency",
"name": {"en": "Replacement cost", "de": "Ersatzkosten"},
"config": {"currency_code": "EUR"}
}
The record contains the numeric amount only. The three-letter uppercase currency code is part of the definition. Do not combine amounts in different currencies in one attribute without converting them by an explicit business rule.
Rating​
Use rating for a bounded score whose scale is shared by every record:
{
"slug": "condition_rating",
"type": "rating",
"name": {"en": "Condition rating", "de": "Zustandsbewertung"},
"config": {"max": 5}
}
max must be positive. Record values range from 0 (unrated) through the configured maximum. An absent
optional rating is still distinct from zero.
Display​
Display templates render a select or state placeholder as the choice title, and a multi-select as its
titles joined by , . The result is the record's display_name, so changing a title relabels existing
records without updating them.
Query and integration behavior​
Select and state filters accept current values where documented, while REST reads return stable IDs. Numeric families support comparison and ordering like numbers. GraphQL renders the numeric value without the schema's unit metadata, so retain the object definition whenever a consumer needs to label or convert the result.
Schema changes to choices, units, currency, or scale can change validation and generated client types. Plan them with the schema evolution playbook.