Skip to main content

Objects and attributes

An object is the schema for one record type. It owns a stable identity, localized names, a display template, and a set of typed attributes. Records always validate against the current object definition.

Semantic identifiers and whole numbers​

The license_plate and vin attribute types hold free text. They preserve whitespace, case, and punctuation; there is no implicit registration format, VIN length, or checksum validation. They support the same declared length, pattern, default, requiredness, and uniqueness configuration as text. Custom objects may contain several attributes of either type. Their REST filter operators are string operators, and GraphQL exposes their values as String.

A number attribute can set config.is_integer to true (default false). It accepts whole numeric values, including 4.0, and rejects fractions and numeric strings without rounding. Minimum, maximum, default, nullability, and uniqueness retain their existing meanings. Changing an existing field to integer-only returns HTTP 422 if stored values contain fractions; the schema, record values, and definition version remain unchanged. Correct those values first, then retry the schema change. Setting the option back to false permits fractions again.

Object shape​

Object definitions use the common definition contract. This excerpt shows their metadata; the full response also contains effective attributes and timestamps.

{
"id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
"slug": "equipment",
"resource_type": "object",
"name": {
"en": { "singular": "Equipment item", "plural": "Equipment" },
"de": { "singular": "Anlage", "plural": "Anlagen" }
},
"display_template": "{{name}} ({{asset_tag}})",
"icon": "toolbox",
"color": "orange",
"map_marker_fields": ["asset_tag", "category"],
"managed_by": "tenant",
"schema_policy": "editable",
"is_readonly": false,
"lock_version": 0,
"is_relationship_target": true
}
FieldMeaning
idImmutable UUID assigned by Tourfold. Prefer it in durable integrations.
slugMutable API handle, unique across all definitions in the workspace, including Vehicle Definitions.
nameEntity noun by canonical language tag, with singular and plural forms.
display_templateOptional record label built from {{attribute_slug}} placeholders. Unset custom-object templates use automatic naming; an explicit template takes precedence.
iconOptional icon key from the Tourfold icon catalog, for example truck: lowercase letters, digits and single hyphens, at most 64 characters. Omitted when unset; clients then show a default icon, as they do for keys they do not know.
colorOptional icon color from the palette gray, red, orange, amber, green, teal, blue, indigo, violet, pink. Omitted when unset.
map_marker_fieldsAttribute slugs shown, in order, when a record's map marker is opened. See Map markers. Empty when none.
managed_byServer-assigned owner: tenant, system, or plugin.
managed_by_pluginPlugin ID, for example bw; present only for managed_by: "plugin".
schema_policyeditable for tenant-owned schemas; locked for system- and plugin-owned schemas. Locked schemas cannot be deleted or edited, including names, fields, choices and display templates; only icon, color and map_marker_fields stay editable.
is_readonlyWhether record writes through the custom-object API are prohibited.
lock_versionObject schema version used for optional optimistic locking.
attributesUser-owned attributes plus system and managed attributes.

The same managed_by, optional managed_by_plugin, and schema_policy shapes appear on Vehicle Definitions, Task Definitions, and /api/v2/definitions/all discovery responses. They govern schema authoring only: record values remain editable when is_readonly and the caller's permissions allow it. Ownership and locking are assigned by the server. Sending either field in Object definition creation or updates returns a field-specific 422 error, as do other unknown request fields.

An attribute also has an immutable id, mutable slug, localized name map, fixed type, and optional config. Attribute names are labels, so each language maps directly to a string rather than a singular/plural noun.

Object, Vehicle, and Task definitions expose their effective fields in one attributes array, including id, created_at, updated_at, and lock_version. Tasks include their native fields here too; there is no separate native_fields array. is_system_managed protects schema authoring, while is_readonly describes value writes. A native Task title, for example, is system-managed but writable through the typed Task request. Native Task values remain top-level and custom Task values remain in data; merging their metadata does not change record paths.

Structured native Task fields (linked_records, visit, or interaction) use the response-only type: "json". Their value structure is specified by the owning Task request/response schema. They have no config, options, or states and cannot be created as custom attributes.

Settings tables group system attributes first, plugin attributes second, and custom attributes last. They preserve definition order within each group and hide the technical lock_version row. These display groups do not change query sorting or record permissions.

Every attribute response also carries two query-discovery fields:

FieldMeaning
is_sortableWhether the attribute can be sorted directly on this object.
filter_operatorsExact REST operator names accepted for a scalar filter. An empty list means to use a nested reference filter or that the field is not filterable.

GraphQL generates its filter and order inputs from the same capability catalog. GraphQL spells each operator with a leading underscore; the semantics and type restrictions are otherwise identical.

Object and attribute slugs start with a lowercase letter and contain only lowercase letters, numbers, and underscores (^[a-z][a-z0-9_]*$). Definition slugs have at most 63 characters; attribute and relationship-side slugs have at most 200. The exact words self and this are reserved. Names beginning with _ are reserved for platform and GraphQL fields. The plugin_ prefix is reserved for plugin-managed definitions, even before the plugin is enabled; it is allowed on attributes. The former so_ restriction no longer applies. The name all is reserved only for Vehicle definitions, so an Object definition or attribute may use it. Attribute and relationship-side slugs also cannot use the platform fields id, display_name, created_at, updated_at, lock_version, is_system_managed, or is_readonly.

Attribute types​

Tourfold exposes a closed set of types instead of raw JSON Schema. This keeps validation predictable and generated clients usable.

The table below is the compact contract. For schema-design guidance, per-type configuration, canonical read/write shapes, GraphQL mappings, and integration consequences, use the attribute field guide.

TypeRecord write valueImportant configuration
textStringpattern, min_length, max_length
license_plate, vinFree-text stringpattern, min_length, max_length; no implicit format
numberNumberminimum, maximum, is_integer
dateRFC 3339 full date, such as 2026-08-26β€”
date_timeRFC 3339 timestampβ€”
booleanBooleanβ€”
selectOption UUID/current value; array when multi-selectis_multiselect, min_items, max_items
stateState UUID/current valueβ€”
capacityNumberunit_kind and unit_ref
measureNumberunit_ref
currencyNumbercurrency_code, for example EUR
ratingNumberPositive max
emailStringβ€”
phoneE.164 phone numberβ€”
tagsArray of tag IDs, labels, or reference objectsCurated through the Tags API
required_skillsArray of skill IDs, labels, or reference objectsCurated through the Skills API
provided_skillsArray of skill IDs, labels, or reference objectsCurated through the Skills API
relationshipOne target UUID/reference for to-one; arrays for to-manytarget, is_multiselect, optional reverse; target: "user" records workspace users
locationAddress, coordinates, or tracking objectFixed structured shape; optional marker_icon, marker_color
raw_jsonAny JSON object, array, string, number, or Boolean, stored and returned as JSONPlatform size, depth, and item limits; see Raw JSON documents
rich_textHTML fragment in the supported formatting subset; plain text becomes a paragraphNormalized on write; see Rich text
full_nameObject with optional title, first_name, last_nameAt least one name component; see Full name
linksObject with a primary link and ordered alternatives, each {url, label}Safe schemes only, 10 alternatives; see Links

Common configuration​

config describes behavior; it never exposes storage or indexing internals.

PropertyApplies toBehavior
is_requiredEvery typeRequires a value; reference collections require at least one member.
is_uniqueSupported single-value string/number-backed typesDeclares uniqueness and enables business-key lookup. Immutable after creation. Never available for raw_json, rich_text, full_name or links.
defaultTypes where a default is meaningfulUsed when a record omits the attribute. A raw_json default is any JSON document within the platform limits.
is_multiselectselect, relationshipAllows more than one selected value or linked record.

There is deliberately no is_indexed property. Tourfold derives indexes from declared intentβ€”such as uniqueness, choices, states, relationships, and display fieldsβ€”and manages them as the workload changes.

Unknown configuration fields, configuration that does not apply to the chosen type, and unsafe regular expressions return 422 with a pointer to the invalid field.

Select options and states​

Choice resources have stable identities:

ResourceImmutable identityMutable handleDisplay fields
Select optionidvaluetitle
Stateidvaluetitle, required color

Writes and filters accept either the UUID or current value. Record reads and choice defaults in object responses return the canonical UUID, so changing a value, title, or color does not rewrite stored data.

Seed choices inline when creating an object:

{
"slug": "priority",
"type": "select",
"name": { "en": "Priority" },
"options": [
{ "value": "normal", "title": "Normal" },
{ "value": "urgent", "title": "Urgent" }
]
}

For incremental editing, use createObjectSelectOption, updateObjectSelectOption, and deleteObjectSelectOption, or the corresponding state operations.

Reference values​

References accept ergonomic handles on write and return canonical, resolved objects on read:

ReferenceWrite acceptsRead returns
TagsUUID, label, {"id": "..."}, or {"label": "..."}{"id", "label", "color"}
SkillsUUID, label, {"id": "..."}, or {"label": "..."}{"id", "label"}
Relationship target objectObject UUID or slug{"id", "slug"}
Relationship recordRecord UUID or {"record_id": "..."}{"record_id", "object", "display_name"}
Workspace user (relationship to user)User UUID or {"record_id": "..."}{"record_id", "object": "user", "display_name"}, plus status for deactivated or deleted users

A syntactically valid UUID string is always treated as an ID. When an object contains both an ID and a handle, the ID wins. Resolved reference objects returned by reads can be sent back unchanged.

Location values​

A location stores an international address, coordinates, or a live tracking reference:

{
"street": "Karlsplatz 1",
"street_additional": null,
"city": "Wien",
"region": null,
"postal_code": "1010",
"country_code": "AT",
"lat": 48.2004,
"lon": 16.3696,
"located_at": "2026-08-26T09:30:00Z"
}

A tracking object points to another record's location attribute:

{
"tracking": {
"record_id": "6f3d2a10-0000-4000-8000-000000000117",
"object": "device",
"attribute": "gps"
}
}

The server stores the values supplied by the client; geocoding is client-driven. To stop tracking, read the resolved location and write its concrete address/coordinates back without tracking. The fixed value is the client-selected snapshot. Sending the entire location attribute as null removes the location; sending only {"tracking":null} is an incomplete location and is rejected.

Map markers​

Tourfold maps draw one layer per location attribute. A record's marker shows its object's icon and color. Opening it shows the record's display_name, which pin was clicked (the location attribute's name, for example "Parked at", with its address when it has one), and the object's map_marker_fields, each under its attribute's name. These settings change presentation only, never the stored values.

map_marker_fields lists attribute slugs, in order, for example ["plate_number", "color"]. Each attribute may appear once, so the list is at most as long as the object's attributes; a request takes at most 100 entries (422 field-size-invalid). List-valued attributes β€” tags, skills and multi-value relationships β€” cannot be shown and return 422 invalid-marker-field, as do unknown and repeated slugs. Renaming an attribute renames it in the list, and deleting one removes it. {"map_marker_fields":null} or [] clears the list.

A location attribute can give its own layer a different look with two optional config properties, for example when an object has both a loading dock and an office:

PropertyBehavior
marker_iconIcon key from the Tourfold icon catalog, for example warehouse, with the same rules as an object's icon. Omission uses the object's icon; clients draw a plain marker for keys they do not know.
marker_colorPalette color, with the same values as an object's color. Omission uses the object's color.
{
"slug": "dock",
"type": "location",
"name": { "en": "Loading dock" },
"config": { "marker_icon": "warehouse", "marker_color": "teal" }
}

{"config":{"marker_icon":null}} on the attribute clears its own icon; omitted properties are kept.

System and managed attributes​

Every object contains four server-managed attributes:

  • id (text)
  • created_at and updated_at (date_time)
  • lock_version (number)

Every attribute response carries explicit is_system_managed and is_readonly booleans. The four system attributes have both set to true; ordinary tenant attributes have both set to false. Their values also appear as top-level fields on record responses and must not be included in record data writes. System attributes are virtual platform fields and therefore omit the optional attribute id; persisted user and relationship attributes carry stable UUID ids.

A relationship's materialized reverse attribute has both is_system_managed: true and is_readonly: true. It projects links for reads and traversal, but schema and record links are changed only through the declaring attribute on the owner side. See Relationships.

Create and change schemas​

There are two equivalent authoring styles:

StyleWhen to useOperations
BulkProvision or synchronize an entire objectcreateObjectDefinition, replaceObjectDefinition
IncrementalEdit one existing field or choiceaddObjectAttribute, updateObjectAttribute, deleteObjectAttribute

Incremental attribute, option, and state writes return the complete updated object, including its new lock_version.

An object defines at most 50 attributes of its own. System attributes and managed reverse relationships don't count. A write that would exceed the limit returns 422 with a too-many-attributes error at #/attributes.

Incremental schema editing​

Definition metadata lives at /api/v2/definitions/objects/{definition_ref}. UUIDs and slugs are accepted. Use PATCH to change only slug, name, display_template, icon, color, or map_marker_fields; attributes is not accepted in metadata patches. Name changes merge by language and noun form. An explicit null clears the template, the icon, the color or an individual translation; omission preserves it. A name map must retain at least one localized name.

PATCH /api/v2/definitions/objects/equipment
Content-Type: application/merge-patch+json

{"name":{"en":{"singular":"Asset"}},"display_template":null,"lock_version":3}

Add fields with POST …/attributes, edit them with PATCH …/attributes/{attribute_ref}, and remove them with DELETE …/attributes/{attribute_ref}. Object and Vehicle attribute patches use the shared UpdateAttribute contract. Omitted fields are preserved; supplied option/state arrays replace their set. The response contains the complete updated definition.

System-managed attributes such as natural_id cannot be deleted. Deleting one by slug or UUID returns 422 with a read-only validation error and leaves the definition unchanged.

Bulk PUT is declarative replacement​

PUT /definitions/objects/{definition_ref} replaces the complete set of attributes owned by that object:

  • Include an existing attribute id to preserve its identity across a slug change.
  • If id is omitted and the slug already exists, Tourfold preserves that attribute's identity. If neither the id nor slug matches, Tourfold creates a new attribute.
  • Supply the complete slug, name and attributes set. Missing attributes is rejected with 422; [] explicitly removes the owned set.
  • Omit an owned attribute to delete it.
  • display_template, icon and color describe the final schema; omitting one clears it. Bulk renames, including swaps, preserve values by attribute ID. A failed replacement rolls back metadata, schema and values together.
  • Include existing option/state IDs to preserve them across value changes. An id-less choice with the same value keeps its identity; omitted choices are deleted.
  • Omit managed reverse attributes. They are outside the target object's owned replacement set and remain present.

Including or directly editing a managed reverse returns 422 relationship-reverse-managed and identifies the owning object and attribute. Change it through the relationship declaration on the owner.

  • The order of the supplied attributes becomes their display order. When an attribute order has been saved (see below), the system attributes, natural_id and managed reverse attributes keep their places and the owned attributes fill the remaining places in the supplied order.

Schema writes accept optional top-level lock_version. When supplied, a stale version returns 409. When omitted, the server applies the write to the current version.

Attribute order​

The attributes array of an object is returned in display order. The same order drives record forms and the columns of the generated default list view. Until an order is saved, id comes first, followed by the platform-managed attributes (such as natural_id and managed reverse relationships), then the object's own attributes, and created_at, updated_at and lock_version come last.

updateObjectAttributeOrder replaces the complete order, including the system attributes, natural_id and managed reverse attributes. List every slug of the object's attributes exactly once:

PUT /api/v2/definitions/objects/equipment/attribute-order
Content-Type: application/json

{"attribute_slugs":["name","created_at","updated_at","asset_tag","category","id","natural_id","lock_version"],"lock_version":3}

A missing, unknown or repeated slug returns 422 with one error per problem under #/attribute_slugs. Only the order changes; attribute values and records are untouched. Attributes added later are appended at the end. Managed objects reject the request with 409 schema-locked.

Localization​

Supply one or more language-tag keys in name. A tag contains a two- or three-letter language and may include a four-letter script and a two-letter or three-digit region. Tourfold canonicalizes the key on write, for example SR-latn becomes sr-Latn and pt-br becomes pt-BR. Malformed keys, or multiple keys that canonicalize to the same tag, return 422 validation-failed instead of being silently discarded.

Clients resolve a label with this fallback order:

  1. Current UI language
  2. Workspace default language
  3. English (en)
  4. Any available translation

Create and update use the same map, so another language can be added later without a special translation operation. The API does not duplicate a pre-resolved label.

Managed objects​

System objects such as user and tour, and plugin-managed objects, may appear in the same catalog. Their authored schemas are fixed, including labels and display templates. Schema edits and deletion return 409 with https://problems.tourfold.com/definitions/schema-locked. Their icon and color are presentation, not schema: a metadata PATCH that changes only those fields succeeds, and managed objects ship with a default icon and color.

PATCH /api/v2/definitions/objects/device
Content-Type: application/merge-patch+json

{"icon":"tablet-screen-button","color":"teal"}

Use schema_policy (editable or locked) to gate schema editing and deletion, and managed_by to identify ownership. Use is_readonly for definition-level record writability; caller grants, object-type ACLs, and record-specific restrictions still apply. A managed definition can allow record creation and editing. Do not hardcode a list of managed slugs. Automatically generated reverse relationship fields follow their source attribute and do not grant permission to edit the target's authored schema.

The object catalog is paginated in ascending slug order, with the immutable object id as its stable tiebreaker. Paging the same unchanged catalog therefore produces the same boundaries on every request.

Deleting an object also deletes its record table, owned relationships, and saved list and detail views rooted on it in the same transaction. If another object owns a relationship attribute targeting it, deletion returns 409 with https://problems.tourfold.com/objects/relationship-target-in-use; remove the named owning attribute first. This prevents deletion of a target from silently rewriting another object's schema.

Endpoint reference​