Choose an attribute type
An attribute type is more than a JSON shape. It determines validation, canonical read values, available filters, GraphQL fields, uniqueness, and how a value appears in webhook payloads. Choose the type whose behavior matches the business fact—not merely the value you happen to have today.
Find the right family​
| You need to represent | Start here |
|---|---|
| Text, identifiers, email, phone, dates, timestamps, numbers, or flags | Scalar and formatted values |
| A controlled list, workflow state, money, a measurement, capacity, or score | Choices, quantities, and ratings |
| Tags, skills, another record, an address, coordinates, or live tracking | Links and locations |
| A structured integration payload or another JSON value that no semantic type fits | Raw JSON documents |
| Formatted notes or descriptions with headings, emphasis, lists and links | Rich text |
| A person's name with an optional title, edited and sorted by its parts | Full name |
| A primary website, mail or phone link with labelled alternatives | Links |
The public API exposes a closed type vocabulary. It never asks clients to submit JSON Schema, database column information, or index details.
Behavior shared by every attribute​
Every user-owned attribute has:
| Field | Contract |
|---|---|
id | Immutable UUID. Send it back during declarative schema updates to preserve identity across a slug rename. |
slug | Mutable API and GraphQL field name matching ^[a-z][a-z0-9_]*$. |
type | Fixed semantic type. Replace the attribute when its meaning truly changes. |
name | Localized display label keyed by canonical language tag. |
description | Optional explanation surfaced in the generated GraphQL schema. |
config.is_required | Requires a write value. For link collections it requires at least one member. |
config.is_unique | Available only for supported single scalar values and immutable after creation. |
config.default | Applied when a directly stored value is omitted on create; unavailable for links and locations. A raw_json default is a JSON document. |
Configuration is strict. An unknown key, or a key that does not apply to the chosen type, returns
422 validation-failed with a JSON Pointer to the offending field. Tourfold does not silently discard
misspelled constraints.
Record write rules​
The record envelope is always the same:
{
"data": {
"attribute_slug": "typed value"
}
}
- On create, an omitted optional value remains unset or receives its declared default.
- On merge patch, an omitted key is unchanged and an explicit
nullclears an optional value. - Arrays are replacement sets, not append operations. Send
[]to clear a writable collection. - A
raw_jsondocument is one value: a supplied document replaces the stored one entirely, and{}or[]are documents rather than clears. - A
rich_textdocument without text content clears the attribute likenull. - A
full_nameorlinksobject replaces the stored object entirely; one without content clears the attribute likenull. - Required values cannot be cleared.
- System and managed reverse attributes are read-only even though they appear in the definition.
Read shape is canonical​
Several types accept a readable handle on write and return an immutable identity on read. For example, a select accepts the option value but returns the option UUID; tags accept labels but return resolved objects. Treat the response as the canonical form. Resolved link values can be round-tripped unless the attribute is a managed reverse projection.
REST and GraphQL roles​
REST owns definitions and every record write. Its structured query endpoint is best for paging a flat result set or synchronizing data. GraphQL is read-only and is best for connected reads. Both derive validation and query capabilities from the same attribute definition.
The generated GraphQL schema can change when a slug, choice, state, or relationship changes. Download it
from the workspace schema endpoint and cache it with its ETag; see
Schema and naming.
Schema checklist​
Before creating an attribute, decide:
- Is the value free-form, controlled, or a reference to another resource?
- Does the integration need a stable business-key lookup? If so, can this single-value type be unique?
- Is absence different from a default value?
- Can the value become multi-valued later? Cardinality changes affect record validation and generated GraphQL fields.
- Who owns writes? For a two-way relationship, only the declaring side owns the link set.
- Which slugs and choice values will generated clients compile into identifiers?
Use the schema evolution playbook before changing any of those answers for a live object.