Links and locations
Link-backed attributes connect a record to another governed Tourfold resource. Locations store a typed place or follow another record's position. Their write shapes are deliberately explicit because they participate in validation, access control, traversal, cleanup, and webhook behavior.
Type matrixβ
| Type | Write accepts | Read returns | GraphQL output |
|---|---|---|---|
tags | Array of IDs, labels, or tag reference objects | Resolved {id, label, color} objects | List of tag objects |
required_skills | Array of IDs, labels, or skill reference objects | Resolved {id, label} objects | List of skill objects |
provided_skills | Array of IDs, labels, or skill reference objects | Resolved {id, label} objects | List of skill objects |
relationship | One target UUID/reference for to-one; arrays for to-many | One compact reference or null for to-one; {items, page} for to-many | Target object or connection |
location | Address, coordinates, tracking reference, or a combination | Typed stored and resolved location | RecordLocation |
These types do not accept config.default or config.is_unique. is_required: true on tags, skills,
or a relationship means the collection must contain at least one link.
Tagsβ
Use tags for workspace-curated labels that may be shared across otherwise unrelated record types.
{
"slug": "tags",
"type": "tags",
"name": {"en": "Tags", "de": "Tags"}
}
All of these members are valid write values:
{
"data": {
"tags": [
"00000000-0000-4000-8000-000000000801",
"urgent",
{"id": "00000000-0000-4000-8000-000000000802"},
{"label": "safety-relevant"}
]
}
}
A UUID-looking string is always treated as an ID. When one reference object contains both id and
label, the ID wins. Reads resolve the links to objects containing id, label, and color; that
resolved shape can be sent back unchanged.
Tags themselves are curated through the Tags API. Deleting a record removes its links but does not delete the shared tag.
Required and provided skillsβ
Use required_skills for capabilities needed to work with a record and provided_skills for
capabilities the record supplies. Both target the workspace skill catalog.
{
"slug": "required_skills",
"type": "required_skills",
"name": {"en": "Required skills", "de": "Erforderliche FΓ€higkeiten"},
"config": {"is_required": true}
}
Writes accept skill UUIDs, labels, {"id":"..."}, or {"label":"..."}. Reads return resolved
{"id","label"} objects. Use a relationship to a custom object instead when the target needs its own
record fields, lifecycle, or per-type permissions.
Relationshipsβ
A relationship links records to exactly one target object. It is never polymorphic: one singular
config.target identifies the target by slug or UUID.
{
"slug": "equipment",
"type": "relationship",
"name": {"en": "Equipment", "de": "Anlage"},
"config": {
"target": "equipment",
"is_multiselect": false,
"is_required": true,
"reverse": {
"slug": "maintenance_requests",
"name": {
"en": "Maintenance requests",
"de": "Wartungsanfragen"
},
"is_multiselect": true
}
}
}
For is_multiselect: false, write one UUID or reference object. For true, write an array:
{
"data": {
"equipment": {"record_id": "6f3d2a10-0000-4000-8000-000000000117"}
}
}
The response adds the object slug and display value. If you send that resolved object back, the server
uses record_id, validates it against the declared target, and treats display data as non-authoritative.
Ownership is part of the typeβ
When reverse is present, Tourfold materializes a read-only attribute on the target object. The
declaring attribute remains the sole owner of schema and link writes. This has practical consequences:
- merge patch on the owner replaces or clears that owner's complete link set;
- writing the reverse returns
422 relationship-reverse-managed; - declarative
PUTon the target does not delete an omitted managed reverse; and - renaming, changing cardinality, or deleting the relationship starts at the declaring attribute.
That asymmetry prevents an ordinary replacement of the target object from erasing links owned by another object. See Relationships for cardinality, reverse-side reads, related record paging, filtering, and deletion behavior.
Inside an atomic batch create, {"ref":"request-local-key"} may link to a sibling item before either
record has a persistent UUID.
Workspace usersβ
To record people, such as an owner or team members, target the system user object:
{"slug": "owner", "type": "relationship", "name": {"en": "Owner"}, "config": {"target": "user"}}
Use is_multiselect: true for a team. Prefer this to text or email attributes: names stay current,
deactivated and deleted people are marked by status, and {"owner": {"id": {"eq": "me"}}} filters
"my records" for whoever is asking. Anyone who can read the record sees the names without users:read.
reverse is not available for user targets. See
Workspace users as targets.
Locationβ
A location can hold an address, coordinates, an observation timestamp, or all of them:
{
"data": {
"position": {
"address_label": "Loading bay",
"street": "Karlsplatz 1",
"city": "Wien",
"postal_code": "1010",
"country_code": "AT",
"lat": 48.2004,
"lon": 16.3696,
"located_at": "2026-08-27T13:45:00Z"
}
}
}
address_label is an optional human-readable label, preserved independently of the structured
address. A label alone does not make a complete location. Fixed locations share these fields with
visit Tasks and Tour Stops, including address-only values.
Geocoding is client-driven: Tourfold stores the accepted values; it does not silently replace an address with coordinates or the reverse.
Coordinates must be finite numbers: latitude is between -90 and 90, longitude between -180 and
180, including the endpoints. Both coordinates are required when either is supplied; 0, 0 is
valid. Invalid coordinates return field-level validation errors and are not stored.
Map markersβ
Each location attribute is one layer on Tourfold maps. Its markers use the object's icon and color
unless the optional config.marker_icon and config.marker_color choose another look for that
layer:
{
"slug": "position",
"type": "location",
"name": {"en": "Position"},
"config": {"marker_icon": "truck", "marker_color": "blue"}
}
Opening a marker shows the record's name, the location under its attribute's name, and the
fields the object lists in map_marker_fields. See
Map markers.
Track another recordβ
A location may follow a location attribute on another record:
{
"data": {
"position": {
"tracking": {
"record_id": "6f3d2a10-0000-4000-8000-000000000201",
"object": "device",
"attribute": "location"
}
}
}
}
Devices expose a read-only location attribute in the object catalog. It returns the latest device
fix and its observation time; it is absent until a fix is available. Existing references to gps
remain supported as an alias, including live updates. New references should use location.
Reads can include the currently resolved address and coordinates alongside tracking. To keep that
position fixed, read the record, remove tracking from the returned location, and write the concrete
address/coordinates back as the replacement value. Include the record's lock_version to guard
against concurrent edits. The client chooses the snapshot; later source updates do not change it.
For example, {"data":{"position":{"lat":48.2082,"lon":16.3738}}} sets a fixed position, while
{"data":{"position":null}} clears the complete value. Sending only {"tracking":null} is an
incomplete location and returns 422 location-incomplete; it is not a snapshot command.
A required location cannot be cleared. A valid tracking reference may be saved before its source
has a fix. If the read contains no resolved address/coordinates, a client can clear an optional
location or supply a new fixed location.
GraphQL exposes a RecordLocation object with address, coordinate, timestamp, and optional tracking
fields. Location values are selectable but not directly filterable or sortable.
Replacement, access, and deletionβ
Arrays on writable link attributes are complete replacement sets: omit to preserve, send the desired
complete array to replace, and send [] or null to clear when optional. The caller must be allowed to
access the relevant object records; a syntactically valid UUID does not bypass tenant or per-type ACLs.
Deleting a linked record removes relationship edges. Deleting a record that carries tags or skills removes its links without deleting shared catalog entries. Deleting an owner relationship attribute removes its managed reverse and all edges owned by that relationship.
For synchronization strategies around these replacement rules, continue with Synchronizing records.