Scalar and formatted values
Scalar attributes store one value directly on the record. They are the best choice for facts that do not need a controlled catalog or a link to another Tourfold resource.
Type matrixโ
| Type | Record value | Type-specific configuration | GraphQL output |
|---|---|---|---|
text | JSON string | pattern, min_length, max_length | String |
number | JSON number | minimum, maximum | Float |
date | RFC 3339 full-date string | โ | Date |
date_time | RFC 3339 timestamp with offset | โ | DateTime |
boolean | JSON Boolean | โ | Boolean |
email | Email-address string | โ | String |
phone | Telephone string accepted and normalized by Tourfold | โ | String |
is_required and default apply to every type in this table. is_unique is available for supported
single string- and number-backed values, but not Boolean values. Uniqueness is immutable after the
attribute is created because it is part of the persisted business-key contract.
Textโ
Use text for names, external identifiers, notes, and codes that are not better represented by a
controlled option or a typed format.
{
"slug": "asset_tag",
"type": "text",
"name": {"en": "Asset tag", "de": "Anlagenkennzeichen"},
"description": "Stable identifier printed on the equipment label.",
"config": {
"is_required": true,
"is_unique": true,
"pattern": "[A-Z]{3}-[A-Z0-9-]+",
"min_length": 5,
"max_length": 40
}
}
pattern is a linear-time regular expression. Lookaheads and backreferences are rejected rather than
allowing a schema author to introduce pathological matching behavior. Length limits are inclusive and
count the stored string.
An empty string is a value, not a request to clear the attribute. If it violates length, pattern, or
required-value rules, the write returns 422; clear an optional text value with null in a merge patch.
Typical filters are equality, set membership, containment, prefix, suffix, and null checks. Use a unique
text attribute with GET /api/v2/objects/{object_ref}/records/by/{attribute_ref}?attribute_value=...
for business-key lookup. URL-encode the value in the attribute_value query parameter.
Numberโ
Use number for a dimensionless value that needs optional lower or upper bounds.
{
"slug": "service_interval_days",
"type": "number",
"name": {"en": "Service interval (days)", "de": "Wartungsintervall (Tage)"},
"config": {
"minimum": 1,
"maximum": 3650,
"default": 365
}
}
The REST API accepts a JSON number and validates inclusive minimum and maximum bounds. Do not use
number when the unit is part of the meaning: use measure, capacity, or currency so the unit lives
in the schema and cannot vary record by record.
GraphQL exposes all numeric families as Float; there is no separate generated integer type. If exact
decimal arithmetic matters to your integration, retain the REST JSON representation rather than routing
financial calculations through GraphQL floating-point values.
Date and date-timeโ
Use date for a calendar day whose meaning does not depend on a time zone:
{"data":{"commissioned_on":"2026-08-27"}}
Use date_time for an instant. Supply RFC 3339 with an explicit offset:
{"data":{"last_inspected_at":"2026-08-27T13:45:00+02:00"}}
Do not turn a local date into midnight UTC merely to satisfy a timestamp field; that changes the model.
Dates and timestamps support equality, ordering, ranges, and null checks. GraphQL represents them with
the generated Date and DateTime scalars.
Booleanโ
Use boolean only when true and false are the complete business states. If โunknown,โ โnot checked,โ
or a workflow transition matters, keep the attribute optional or use state instead.
{
"slug": "operational",
"type": "boolean",
"name": {"en": "Operational", "de": "Betriebsbereit"},
"config": {"default": true}
}
An omitted optional Boolean, false, and null are three distinct situations. JSON must contain the
Boolean literals true or false, never their string forms.
Emailโ
Use email when the value is intended to be an email address and consumers benefit from format
validation. Use ordinary text for arbitrary delivery syntax or a comma-separated list.
{
"slug": "service_contact_email",
"type": "email",
"name": {"en": "Service contact email", "de": "E-Mail des Servicekontakts"}
}
One attribute holds one address. Model several contacts as related records rather than hiding a list in one string.
Phoneโ
Use phone for dialable telephone numbers. Tourfold parses accepted input and returns a normalized E.164
value such as +43123456789.
{
"slug": "service_phone",
"type": "phone",
"name": {"en": "Service phone", "de": "Servicetelefon"}
}
Store extensions or free-form instructions in a separate text attribute. Integrations should compare the normalized read value, not the formatting supplied by a user.
Errors and change eventsโ
A wrong JSON type, invalid format, violated bound, or non-unique value returns 422 with a pointer such
as #/data/asset_tag. See the error contract.
Object-record webhook payloads use an open schema. On an update,
data.previous_attributes contains the old value only for keys that changed. Ignore unknown payload
keys and use the event's object and attribute identities where durable routing matters.