Skip to main content

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​

TypeWrite acceptsRead returnsGraphQL output
tagsArray of IDs, labels, or tag reference objectsResolved {id, label, color} objectsList of tag objects
required_skillsArray of IDs, labels, or skill reference objectsResolved {id, label} objectsList of skill objects
provided_skillsArray of IDs, labels, or skill reference objectsResolved {id, label} objectsList of skill objects
relationshipOne target UUID/reference for to-one; arrays for to-manyOne compact reference or null for to-one; {items, page} for to-manyTarget object or connection
locationAddress, coordinates, tracking reference, or a combinationTyped stored and resolved locationRecordLocation

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 PUT on 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.