Skip to main content

Relationships

A relationship attribute links records from one object to records of exactly one target object. Relationships are not polymorphic: the object definition uses one singular config.target, supplied as an object slug or UUID.

Declare a relationshipโ€‹

This attribute belongs to maintenance_request and points to equipment:

{
"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
}
}
}

Add it inline in createObject or incrementally with addAttribute.

On write, target accepts the target object's slug or immutable UUID. On read it is resolved:

{
"target": {
"id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
"slug": "equipment"
},
"is_multiselect": false,
"is_required": true,
"reverse": {
"slug": "maintenance_requests",
"name": { "en": "Maintenance requests", "de": "Wartungsanfragen" },
"is_multiselect": true
}
}

Cardinalityโ€‹

Each side declares independently whether it can hold multiple links:

Declaring sideReverse sideRelationship
SingleSingleOne-to-one
SingleMultipleMany maintenance requests can point to one equipment item
MultipleSingleOne source can link many targets; each target accepts one source
MultipleMultipleMany-to-many
SingleNo reverseMany sources can point to the same target
MultipleNo reverseMany-to-many

Without a reverse declaration the target side places no limit on how many records link to the same target. A one-sided target limit (one-to-one, or one source per target) needs a declared reverse with is_multiselect: false.

A to-one field accepts one UUID/reference or null; a to-many field accepts an array. Existing to-one array writes remain accepted with at most one element. is_required: true on the declaring attribute requires at least one link; the reverse declaration has no separate required flag. Both sides' cardinality and the owner's required constraint are enforced whenever the owner side changes an edge.

One writable owner, one read-only projectionโ€‹

A two-way relationship has deliberately asymmetric schema ownership:

  1. The attribute that declares config.reverse owns the relationship schema.
  2. Tourfold materializes the named reverse attribute on the target object.
  3. The reverse has is_system_managed: true, is_readonly: true, and points back to the owner object.
  4. The reverse does not contain another reverse declaration.

The owner attribute is the only write authority for the edge. Updating maintenance_request.equipment changes the relationship; attempting to write equipment.maintenance_requests returns 422 relationship-reverse-managed. The reverse remains available for record reads, related-record paging, GraphQL traversal, filtering, and sorting where supported.

This prevents a replacement sent to the target side from deleting links declared by another object and makes repeated writes deterministic.

Write one record UUID or reference object for a to-one relationship; use arrays of these values for to-many relationships. These two to-one forms are equivalent:

{
"data": {
"equipment": "6f3d2a10-0000-4000-8000-000000000117"
}
}
{
"data": {
"equipment": {
"record_id": "6f3d2a10-0000-4000-8000-000000000117"
}
}
}

The configured target object is implied. If a round-tripped object also contains object and display_name, the server validates the record ID against config.target and ignores display data as input.

For PATCH on the object that owns the relationship attribute:

  • A to-one value replaces its single link; a to-many array replaces the complete link set.
  • null clears to-one and [] clears to-many, subject to is_required.
  • Existing clients may still send arrays for to-one, with at most one target. [] for to-one and null for to-many remain accepted clearing forms.
  • Omitting the relationship key preserves the current links.

Inside atomic batch create, {"ref": "request-local-key"} can point to a sibling record in the same request.

Writing a relationship value (on create, batch create, or PATCH, including clearing a relationship with null or []) requires read access to the target definition in addition to write access on the owning definition. If the caller cannot read the target definition, the write returns 403 access-denied; omit the relationship key on PATCH to update other fields while preserving existing links.

The managed reverse attribute is read-only. To add or remove an edge while starting from a target-side workflow, update the corresponding owner record's declaring attribute.

Embedded relationship values return resolved compact references:

{
"data": {
"equipment": {
"record_id": "6f3d2a10-0000-4000-8000-000000000117",
"object": "equipment",
"display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)"
}
}
}

To-one relationships return a single reference object, or explicit null when unlinked. Unreadable relationships are omitted. To-many relationships use {items, page} with at most 50 compact record views and the full readable total. This example shows a complete one-item collection. Use the related-record endpoint for larger collections. Writes still accept arrays of IDs or references; the read envelope is not a write input.

{
"data": {
"maintenance_requests": {
"items": [
{
"record_id": "7a4e2b10-0000-4000-8000-000000000201",
"object": "maintenance_request",
"display_name": "Temperature too high"
}
],
"page": {
"size": 50,
"total_elements": 1,
"total_pages": 1,
"number": 0
}
}
}
}
GET /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests?page=0&size=20

Related pages return {items, page}. Each item wraps its owner's canonical response:

{
"kind": "vehicle",
"definition_id": "11111111-9999-4444-8888-111111111111",
"record": {
"id": "aaaaaaaa-cccc-4ccc-8ccc-dddddddddddd",
"definition_id": "11111111-9999-4444-8888-111111111111",
"natural_id": "BIKE-7",
"name": "Cargo bike 7",
"display_name": "Cargo bike 7",
"is_active": true,
"capacity": 0,
"seats_total": 1,
"created_at": "2023-02-14T10:00:00Z",
"updated_at": "2023-02-14T10:00:00Z",
"lock_version": 0,
"data": {"battery_wh": 750}
}
}

kind: "object" carries the canonical Object record instead. The registered native device target uses kind: "device" and the canonical Device response inside record; devices:read is required for its references, related pages and expansions. Device creation and updates stay on /api/v2/devices; Object record routes never accept Device identities. Vehicle targets span definitions; the wrapper identifies each record's actual definition. Vehicle sources offer the same collection at GET /vehicles/{definition_ref}/records/{vehicle_id}/related/{attribute_ref}. Both source and target read permissions apply; target denial returns 403 before a count is exposed. Inline previews omit unreadable target references and their pagination metadata.

Structured related queries currently support Object targets. Vehicle and Device targets use paginated GET; a related query against either target returns 422 unsupported-relationship-query.

REST structured queries can filter through the relationship:

{
"filter": {
"maintenance_requests": {
"priority": { "eq": "urgent" }
}
}
}

Filters can continue through further relationships up to the shared four-level filter limit. Scalar sorting supports exactly one to-one relationship hop, for example "sort": ["manufacturer.name:asc"]; to-many and chained relationship ordering are rejected.

To filter and sort only the linked target collection, use:

POST /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests/query

The request body has the same filter, sort, page, and size fields as the top-level record query.

GraphQL can traverse the same edge and select fields from both objects in one request. See Filtering by a related record.

Workspace users as targetsโ€‹

Use the system user object as config.target to record people on a record, such as a project owner and its team:

[
{ "slug": "owner", "type": "relationship", "name": { "en": "Owner" },
"config": { "target": "user" } },
{ "slug": "team", "type": "relationship", "name": { "en": "Team" },
"config": { "target": "user", "is_multiselect": true } }
]

Write user IDs exactly like other relationship values. Reads return the same compact reference, with an optional status for people who are no longer current members:

{
"data": {
"owner": { "record_id": "5f000000-0000-4000-8000-000000000002", "object": "user", "display_name": "Ada Lovelace" },
"team": {
"items": [
{ "record_id": "5f000000-0000-4000-8000-000000000003", "object": "user", "display_name": "Grace Hopper", "status": "inactive" },
{ "record_id": "5f000000-0000-4000-8000-000000000004", "object": "user", "display_name": "Margaret Hamilton", "status": "deleted" }
],
"page": { "size": 50, "total_elements": 2, "total_pages": 1, "number": 0 }
}
}
}
UserReadNew link
ActiveName, no statusAccepted
DeactivatedName with status: "inactive"Accepted, so historical records can keep former employees
DeletedName with status: "deleted"; without display_name when the deletion anonymized the person422 object-not-found
Service accountโ€”422 object-not-found

Links that a record already holds remain valid. Sending an unchanged team that contains a deleted or deactivated member therefore succeeds, so clients can edit the rest of the set.

Seeing people on a record does not require users:read. Anyone who can read the record sees the references and can link users; pick candidates with listUserDirectoryEntries (GET /api/v2/users/directory), which returns names and status only. Without users:read, nested filters and sorts through a user field can use only id, firstname, lastname, active, and deleted_at; other user fields return 422 unknown-filter-attribute. Full user records โ€” include expansion, related-record pages, and contact fields โ€” still require users:read. Without it, include leaves the compact reference unexpanded and related pages return 403 access-denied.

Filter by the calling user with the id alias me, which is resolved separately for every request. It is accepted by eq, ne, and in (GraphQL _eq, _ne, _in) on the user object's id, so a shared saved view such as "My projects" shows each viewer their own records:

{
"filter": { "or": [ { "owner": { "id": { "eq": "me" } } }, { "team": { "id": { "eq": "me" } } } ] },
"sort": ["owner.lastname:asc", "owner.firstname:asc"]
}

A caller that is not a user, such as a device token, matches no user for me. Relationships to user cannot declare reverse (422 relationship-reverse-unsupported); the system User schema stays unchanged. Record webhooks carry the written relationship value unresolved, as for every relationship.

Change the relationship schemaโ€‹

Make structural changes only through the owner attribute:

  • Rename or relabel the reverse by updating the owner's config.reverse.
  • Change cardinality through the owner declaration.
  • Remove the two-way relationship by deleting the owner attribute or omitting it from the owner's bulk PUT.

The reverse side cannot update or delete its managed attribute directly. Such a request returns 422 relationship-reverse-managed with the owner identity.

Why reverse-side PUT does not delete itโ€‹

PUT /definitions/objects/{definition_ref} replaces only attributes owned by the target object. A managed reverse is a projection of a schema owned elsewhere, so:

  • Omitting the reverse from the target's PUT preserves it.
  • Including it in the target's replacement document returns 422.

Otherwise, resending an unchanged target-object document could unexpectedly delete a relationship declared by another object. This boundary makes declarative PUT safe and repeatable on both sides.

Deletion behaviorโ€‹

  • Deleting a linked record removes its relationship edges; other records remain.
  • Deleting the owner relationship attribute removes the relation and its managed reverse.
  • Deleting the owner object removes its relationship definitions, managed reverse attributes on targets, and stored edges. Target objects and their records remain.

Use destructive schema operations carefully: removing an owning relationship attribute removes all links stored for that relationship.

Conflicts and validationโ€‹

The reverse slug must be free in the target object's attribute namespace. A collision with a target-owned attribute, another relationship, or another managed reverse returns 422 relationship-reverse-slug-conflict with a pointer to the reverse slug.

An unknown target, record from the wrong object, cardinality violation, or attempt to clear a required relationship also returns 422 with a field-level pointer. See Errors.

Endpoint referenceโ€‹