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
}
| Field | Meaning |
|---|---|
id | Immutable UUID assigned by Tourfold. Prefer it in durable integrations. |
slug | Mutable API handle, unique across all definitions in the workspace, including Vehicle Definitions. |
name | Entity noun by canonical language tag, with singular and plural forms. |
display_template | Optional record label built from {{attribute_slug}} placeholders. Unset custom-object templates use automatic naming; an explicit template takes precedence. |
icon | Optional 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. |
color | Optional icon color from the palette gray, red, orange, amber, green, teal, blue, indigo, violet, pink. Omitted when unset. |
map_marker_fields | Attribute slugs shown, in order, when a record's map marker is opened. See Map markers. Empty when none. |
managed_by | Server-assigned owner: tenant, system, or plugin. |
managed_by_plugin | Plugin ID, for example bw; present only for managed_by: "plugin". |
schema_policy | editable 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_readonly | Whether record writes through the custom-object API are prohibited. |
lock_version | Object schema version used for optional optimistic locking. |
attributes | User-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:
| Field | Meaning |
|---|---|
is_sortable | Whether the attribute can be sorted directly on this object. |
filter_operators | Exact 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.
| Type | Record write value | Important configuration |
|---|---|---|
text | String | pattern, min_length, max_length |
license_plate, vin | Free-text string | pattern, min_length, max_length; no implicit format |
number | Number | minimum, maximum, is_integer |
date | RFC 3339 full date, such as 2026-08-26 | β |
date_time | RFC 3339 timestamp | β |
boolean | Boolean | β |
select | Option UUID/current value; array when multi-select | is_multiselect, min_items, max_items |
state | State UUID/current value | β |
capacity | Number | unit_kind and unit_ref |
measure | Number | unit_ref |
currency | Number | currency_code, for example EUR |
rating | Number | Positive max |
email | String | β |
phone | E.164 phone number | β |
tags | Array of tag IDs, labels, or reference objects | Curated through the Tags API |
required_skills | Array of skill IDs, labels, or reference objects | Curated through the Skills API |
provided_skills | Array of skill IDs, labels, or reference objects | Curated through the Skills API |
relationship | One target UUID/reference for to-one; arrays for to-many | target, is_multiselect, optional reverse; target: "user" records workspace users |
location | Address, coordinates, or tracking object | Fixed structured shape; optional marker_icon, marker_color |
raw_json | Any JSON object, array, string, number, or Boolean, stored and returned as JSON | Platform size, depth, and item limits; see Raw JSON documents |
rich_text | HTML fragment in the supported formatting subset; plain text becomes a paragraph | Normalized on write; see Rich text |
full_name | Object with optional title, first_name, last_name | At least one name component; see Full name |
links | Object 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.
| Property | Applies to | Behavior |
|---|---|---|
is_required | Every type | Requires a value; reference collections require at least one member. |
is_unique | Supported single-value string/number-backed types | Declares uniqueness and enables business-key lookup. Immutable after creation. Never available for raw_json, rich_text, full_name or links. |
default | Types where a default is meaningful | Used when a record omits the attribute. A raw_json default is any JSON document within the platform limits. |
is_multiselect | select, relationship | Allows 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:
| Resource | Immutable identity | Mutable handle | Display fields |
|---|---|---|---|
| Select option | id | value | title |
| State | id | value | title, 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:
| Reference | Write accepts | Read returns |
|---|---|---|
| Tags | UUID, label, {"id": "..."}, or {"label": "..."} | {"id", "label", "color"} |
| Skills | UUID, label, {"id": "..."}, or {"label": "..."} | {"id", "label"} |
| Relationship target object | Object UUID or slug | {"id", "slug"} |
| Relationship record | Record 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:
| Property | Behavior |
|---|---|
marker_icon | Icon 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_color | Palette 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_atandupdated_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:
| Style | When to use | Operations |
|---|---|---|
| Bulk | Provision or synchronize an entire object | createObjectDefinition, replaceObjectDefinition |
| Incremental | Edit one existing field or choice | addObjectAttribute, 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
idto preserve its identity across a slug change. - If
idis 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,nameandattributesset. Missingattributesis rejected with 422;[]explicitly removes the owned set. - Omit an owned attribute to delete it.
display_template,iconandcolordescribe 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_idand 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:
- Current UI language
- Workspace default language
- English (
en) - 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.