Skip to main content

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โ€‹

TypeRecord valueType-specific configurationGraphQL output
textJSON stringpattern, min_length, max_lengthString
numberJSON numberminimum, maximumFloat
dateRFC 3339 full-date stringโ€”Date
date_timeRFC 3339 timestamp with offsetโ€”DateTime
booleanJSON Booleanโ€”Boolean
emailEmail-address stringโ€”String
phoneTelephone 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.