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 side | Reverse side | Relationship |
|---|---|---|
| Single | Single | One-to-one |
| Single | Multiple | Many maintenance requests can point to one equipment item |
| Multiple | Single | One source can link many targets; each target accepts one source |
| Multiple | Multiple | Many-to-many |
| Single | No reverse | Many sources can point to the same target |
| Multiple | No reverse | Many-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:
- The attribute that declares
config.reverseowns the relationship schema. - Tourfold materializes the named reverse attribute on the target object.
- The reverse has
is_system_managed: true,is_readonly: true, and points back to the owner object. - The reverse does not contain another
reversedeclaration.
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 linksโ
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.
nullclears to-one and[]clears to-many, subject tois_required.- Existing clients may still send arrays for to-one, with at most one target.
[]for to-one andnullfor 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.
Read linksโ
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 }
}
}
}
| User | Read | New link |
|---|---|---|
| Active | Name, no status | Accepted |
| Deactivated | Name with status: "inactive" | Accepted, so historical records can keep former employees |
| Deleted | Name with status: "deleted"; without display_name when the deletion anonymized the person | 422 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
PUTpreserves 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.