Skip to main content

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 representStart here
Text, identifiers, email, phone, dates, timestamps, numbers, or flagsScalar and formatted values
A controlled list, workflow state, money, a measurement, capacity, or scoreChoices, quantities, and ratings
Tags, skills, another record, an address, coordinates, or live trackingLinks and locations
A structured integration payload or another JSON value that no semantic type fitsRaw JSON documents
Formatted notes or descriptions with headings, emphasis, lists and linksRich text
A person's name with an optional title, edited and sorted by its partsFull name
A primary website, mail or phone link with labelled alternativesLinks

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:

FieldContract
idImmutable UUID. Send it back during declarative schema updates to preserve identity across a slug rename.
slugMutable API and GraphQL field name matching ^[a-z][a-z0-9_]*$.
typeFixed semantic type. Replace the attribute when its meaning truly changes.
nameLocalized display label keyed by canonical language tag.
descriptionOptional explanation surfaced in the generated GraphQL schema.
config.is_requiredRequires a write value. For link collections it requires at least one member.
config.is_uniqueAvailable only for supported single scalar values and immutable after creation.
config.defaultApplied 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 null clears an optional value.
  • Arrays are replacement sets, not append operations. Send [] to clear a writable collection.
  • A raw_json document is one value: a supplied document replaces the stored one entirely, and {} or [] are documents rather than clears.
  • A rich_text document without text content clears the attribute like null.
  • A full_name or links object replaces the stored object entirely; one without content clears the attribute like null.
  • 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:

  1. Is the value free-form, controlled, or a reference to another resource?
  2. Does the integration need a stable business-key lookup? If so, can this single-value type be unique?
  3. Is absence different from a default value?
  4. Can the value become multi-valued later? Cardinality changes affect record validation and generated GraphQL fields.
  5. Who owns writes? For a two-way relationship, only the declaring side owns the link set.
  6. 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.