Schema and naming
Your workspace's GraphQL schema is generated from its schema catalog: Object, Vehicle and Task Definitions you created over REST plus the native and plugin resources with registered GraphQL read support. Catalog membership alone does not expose a resource. Vehicle location is a field of Vehicle, not a separate collection. The supported fields and arguments come from each owner's projection. Change a tenant-created definition and the schema changes with it.
Because it is per-workspace, no static schema document is published. Download the current one:
curl "https://api.tourfold.com/api/v2/graphql/schema" \
-H "Authorization: Bearer YOUR_TOKEN"
The response is text/plain SDL, suitable for a GraphQL IDE, Insomnia, GraphiQL, or a codegen tool
pointed at a file. Types, fields, arguments, filter operators and pagination helpers include descriptions,
so introspection-aware IDEs can explain the generated schema without a separate static reference.
The response also carries a private ETag. Revalidate a saved schema instead of downloading it blindly:
curl "https://api.tourfold.com/api/v2/graphql/schema" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H 'If-None-Match: "SCHEMA_ETAG"'
An unchanged schema returns 304 Not Modified with no body. A definition, attribute or relation change
produces a new ETag and returns the new SDL with 200 OK.
Because the schema is per-workspace and generated at runtime, build-time code generation against a shared schema is not possible. Generate against your own downloaded SDL, and regenerate when your definitions change.
Discovering resource metadataโ
The REST definition discovery API exposes effective fields and owner
capabilities through GET /api/v2/definitions/all and /{definition_ref}. Concrete Vehicle and Task
definitions are included by default; internal family roots are excluded. Definitions identify their
owner with extensible resource_type and contain no physical database bindings or public base ID.
GraphQL retains family-wide query roots and its existing connection pagination. Its selection sets choose compact or complete views; REST discovery membership does not change GraphQL's root schema. Metadata visibility never grants record access or authoring rights. Query-only native projections cannot become relationship targets merely because they appear in discovery.
Root fieldsโ
Each supported tenant-created or native definition contributes one root query field, named after the definition's slug and returning a connection:
type Query {
equipment(where: equipmentFilter, order_by: [equipmentOrderBy!], first: Int, after: String, last: Int, before: String, offset: Int): equipmentConnection!
maintenance_request(where: maintenance_requestFilter, ...): maintenance_requestConnection!
}
The field name is the singular slug โ equipment, not equipments โ because it is the definition
slug verbatim, not a pluralisation.
A workspace with no supported definitions gets a placeholder root whose only field is
_empty: String.
Type and field namesโ
Definition and attribute slugs already follow the GraphQL-safe pattern
^[a-z][a-z0-9_]*$: start with a lowercase letter, then use lowercase letters, numbers, and
underscores. Hyphens are not accepted. The complete _ prefix is reserved for platform and GraphQL
fields, including GraphQL's own __ introspection namespace. Attribute and relationship-side slugs
also reserve id, display_name, created_at, updated_at, lock_version, is_system_managed, and
is_readonly. The generated GraphQL field uses an accepted slug unchanged.
| Definition or attribute slug | GraphQL name |
|---|---|
equipment | equipment |
asset_tag | asset_tag |
maintenance_request | maintenance_request |
Display names may contain spaces and punctuation, but display names never become GraphQL identifiers.
The generated type names follow fixed patterns, so you can predict them:
| Kind | Pattern | Example |
|---|---|---|
| Object type | <slug> | equipment |
| Connection | <slug>Connection | equipmentConnection |
| Edge | <slug>Edge | equipmentEdge |
| Filter input | <slug>Filter | equipmentFilter |
| Order-by input | <slug>OrderBy | equipmentOrderBy |
| Relationship order-by leaf | <slug>RelationshipOrderBy | equipmentRelationshipOrderBy |
| Enum | <slug>_<field> | equipment_category |
Vehicle collectionsโ
Each Vehicle Definition adds its own top-level type, connection, edge and root named after its slug,
such as bicycle (bicycleConnection). Its fields, where filter and order_by inputs use the same
flat common and custom attribute names as an Object collection. The vehicle root queries across all
definitions, returns vehicleConnection with common Vehicle fields (id, definition_id,
natural_id, display_name, location, created_at, updated_at, lock_version), and accepts
only id, definition_id, natural_id, created_at and updated_at filters/sorts. Selecting a
definition_id on vehicle does not enable custom-field filters.
query ElectricBicycles {
bicycle(search: "frame", where: { battery_wh: { _gte: 500 } }, order_by: [{ battery_wh: desc }], first: 20) {
totalCount
edges {
node {
id
definition_id
natural_id
display_name
battery_wh
frame_number
}
}
}
}
definition_id is ID!; natural_id is a formatted String!, like REST.
There is no synthetic default Vehicle Definition: the family collection reads only actual records
belonging to created or plugin-installed definitions.
A relationship to a concrete Vehicle Definition returns that definition's top-level type (bicycle or
bicycleConnection) with its full filter inputs. A relationship to the Vehicle family returns vehicle
or vehicleConnection and exposes common-field filters only. Reverse relationships targeting the
Vehicle family appear both on vehicle and on every concrete Vehicle type. The selected position is the
nullable location field. Concrete Vehicle roots support nested filters on declared tags,
provided_skills and required_skills attributes. The aggregate vehicle root keeps common-field
filters only.
Task collectionsโ
query OpenTasks {
system_task(where: { status: { _eq: "open" } }, order_by: [{ natural_id: asc }], first: 20) {
totalCount
edges {
node {
id
definition_id
natural_id
type
execution_type
title
}
}
}
}
system_task reads all Tasks across definitions and returns system_taskConnection. Every concrete Task
definition also contributes its own top-level type (<slug>), connection (<slug>Connection), and root
named after its slug, including the four built-in definitions such as system_task_simple. Common fields on
both system_task and every concrete Task type include definition_id, natural_id: String!, type,
execution_type, title, status, assignee_user_id, timestamps and lock_version. natural_id
includes the definition's current prefix when configured (for example, INS-42); without a prefix it is
still a string ("42"). The UUID remains the permanent identity. type is the built-in name (simple,
visit, or a workflow question name) or the custom definition slug (inspection). execution_type is
the underlying execution kind, so a custom Inspection can return type: "inspection" and
execution_type: "visit". display_name is the Task title. The native visit.location, interaction
and linked_records fields preserve Task content on both system_task and concrete Task types; an
inapplicable Visit or interaction is null.
Concrete Task types expose their custom scalar attributes, relationships and declared tags,
required_skills and provided_skills attributes directly on the top-level node, just like Custom
Objects and concrete Vehicle types. The family root system_task filters/sorts common scalar fields;
concrete roots also support their custom scalar, relationship and declared tag/skill reference filters.
Each reference filter checks the target's read permission, including for empty results. Task collections
require tasks:read, including counts and empty results.
Filters use the same values as the selected fields: type: { _eq: "inspection" } selects one
definition, while execution_type: { _eq: "visit" } selects built-in and custom Visit Tasks.
natural_id takes string operands, such as { _eq: "INS-42" } or { _starts_with: "INS-" }.
Changing a definition's prefix changes subsequent output and matching filters; the old prefix does
not remain an alias. Sorting by natural_id keeps the shared numeric Task sequence order across
definitions and prefixes, just like Task REST lists, so 2 precedes 10. Sorting by type sorts the
public definition selector; sorting by execution_type sorts the execution kind.
For all three record owners, a to-one relationship selects a target object or null; a to-many
relationship selects a connection with edges { node }, pageInfo, and totalCount. Select only
id and display_name for a compact view, or add fields for more detail. GraphQL does not use REST's
include parameter or { items, page } envelope.
:::note Client migration
This pre-GA correction changes Task natural_id from Long! to String!, including its filter
operands, and promotes concrete Vehicle and Task definitions to flat top-level GraphQL types without a
nested data union wrapper. Regenerate GraphQL client types and select custom fields directly on the
concrete Vehicle or Task root. Clients that used type to identify or filter execution behavior must
select/filter execution_type instead; type now identifies the definition. Deploy these client
updates with the backend; no legacy aliases are exposed.
:::
Tour collectionsโ
system_tour exposes core Tours through the same Relay connection (system_tourConnection), where: system_tourFilter, and order_by: [system_tourOrderBy!] arguments as other root collections:
type system_tour {
id: ID!
display_name: String!
natural_id: Long!
description: String
origin: String
publication_status: String
execution_status: String
planned_start_at: DateTime
planned_end_at: DateTime
published_at: DateTime
started_at: DateTime
finished_at: DateTime
created_by_user_id: String
participant_user_ids: [ID!]!
task_count: Long!
stop_count: Long!
required_skill_ids: [ID!]!
source_tour_template_id: String
source_tour_template_name: String
source_tour_template_revision: Long
source_tour_template_date: Date
vehicles: [TourVehicle!]!
stops: [TourStop!]!
tasks: [system_task!]!
task_assignments: [TourTaskAssignment!]!
requirement_coverage: TourRequirementCoverage!
start_blockers: [String!]!
created_at: DateTime!
updated_at: DateTime!
lock_version: Long!
}
display_name returns the Tour description when non-blank and falls back to #<natural_id>.
vehicles returns the current Vehicle assignments (TourVehicle), masking vehicle_definition_id,
vehicle_natural_id, vehicle_display_name, vehicle_eligibility, and vehicle (vehicle_details_restricted: true)
when the caller lacks vehicles:read. Selecting stops on a Tour that contains task_visit stops,
or selecting stops { task_ids }, tasks, or task_assignments, requires tasks:read.
Attribute mappingโ
The semantic attribute type declared through the typed REST API decides the GraphQL shape:
| Typed attribute | GraphQL | Notes |
|---|---|---|
text, email, phone | String | Phone values are normalized E.164 strings. |
date | Date | 2026-03-14 |
date_time | DateTime | RFC 3339, e.g. 2026-03-14T09:30:00Z |
number, capacity, measure, currency, rating | Float | There is no separate integer mapping. |
boolean | Boolean | |
single select, state | generated enum | Output values use the current choice/state value. |
multi select | [String] | Output values use the current choice value. |
raw_json | JSON | The stored document as a JSON scalar; see Raw JSON documents. |
rich_text | RecordRichText | html is the canonical markup, text its plain-text projection; see Rich text. |
full_name | RecordFullName | title, first_name, last_name plus the combined display; see Full name. |
links | RecordLinks | primary: RecordLink! and alternatives: [RecordLink!]!, each {url, label}; see Links. |
location | RecordLocation | Closed structured value; see below. |
tags, required_skills, provided_skills | lists of target objects | Resolved objects, not raw UUID arrays. |
relationship | target object or connection | To-one/to-many follows relationship cardinality. |
totalCount is a Long, not an Int โ a collection can exceed 2ยณยน rows.
Enumsโ
A single-select or state attribute with choices becomes a GraphQL enum named <slug>_<field>, with each
value sanitized the same way as a field name:
enum equipment_category {
hvac
elevator
lighting
}
Choice values may contain punctuation. If two values sanitize to the same enum symbol โ for example,
in-progress and in progress both become in_progress โ Tourfold appends a stable suffix derived
from each option's immutable ID. Both choices therefore remain queryable; inspect the downloaded SDL
for their exact symbols. Values without a collision keep their ordinary unsuffixed name.
When filtering, enum operands are strings (_eq: "hvac" or _in: ["hvac"]) rather than bare enum
literals โ the enum type applies to the output field, not to the filter input.
Location valuesโ
Locations are a typed object rather than an opaque JSON string:
type RecordLocation {
street: String
street_additional: String
city: String
region: String
postal_code: String
country_code: String
lat: Float
lon: Float
located_at: DateTime
tracking: RecordLocationTracking
}
type RecordLocationTracking {
record_id: ID!
object: String!
attribute: String!
}
Tracking locations can also contain the currently resolved coordinates and address fields. Location attributes are selectable but are not directly filterable or sortable.
Required fieldsโ
Server-maintained system fields are non-null. User-defined attribute fields remain nullable in GraphQL,
including attributes whose config.is_required is true: requiredness constrains REST writes, while
GraphQL is a read surface and may encounter records created before a schema change.
System fieldsโ
Every type carries five fields Tourfold maintains itself. You never declare them and cannot change them:
| Field | Type | |
|---|---|---|
id | ID! | The record's UUID. |
display_name | String! | Canonical name rendered from the definition's display template, falling back to its natural ID when available. |
created_at | DateTime! | |
updated_at | DateTime! | |
lock_version | Long! | Optimistic-locking counter, used when writing over REST. |
lock_version is selectable but cannot be filtered or sorted on โ it is write-side bookkeeping with
no meaningful comparison semantics. The other three filter and sort like any field of their type.
display_name uses the same renderer and fallback rules as REST records and relationship references.
Select it directly instead of duplicating display-template evaluation in a client.
Relationsโ
Each relation you define contributes a field to both types involved, named after that side's slug towards the other side. The shape depends on the target's cardinality:
To-one โ a plain nullable object field, with no arguments:
type maintenance_request {
equipment: equipment
}
To-many โ a connection, with the same filtering, ordering and pagination arguments as a root field:
type equipment {
maintenance_requests(
where: maintenance_requestFilter
order_by: [maintenance_requestOrderBy!]
first: Int
after: String
last: Int
before: String
offset: Int
): maintenance_requestConnection
}
So one query can walk both directions:
query EquipmentWithOpenRequests {
equipment(first: 5, order_by: [{ name: asc }]) {
edges {
node {
name
maintenance_requests(where: { resolved: { _eq: false } }, first: 3, order_by: [{ reported_at: desc }]) {
totalCount
edges {
node {
title
priority
}
}
}
}
}
}
}
A few things follow from the generation rules:
- Self-referencing relations work. A definition related to itself gets both fields on the same type.
- Managed reverse attributes are queryable. A two-way relationship can be traversed from either object even though only its declaring owner side is writable over REST.
- Platform-internal hidden connector sides are omitted. They contribute no output or filter field.
- Nested connections have their own, smaller default page size โ 10 rather than 20 โ because they resolve once per parent row. See Pagination.
- Traversal depth is bounded. A connection costs several levels against the query-depth limit; see Errors and limits.
When the schema updatesโ
The compiled schema is cached per workspace, keyed by a token that changes whenever a definition or relation changes. A definition change is therefore visible to the next query, on every API instance โ you do not have to wait out a cache window, and you will not intermittently hit a stale schema depending on which instance served you.
Cached schemas are also discarded after ten minutes of no change, which has no effect you can observe beyond the first query afterwards being marginally slower.
The schema endpoint's ETag uses the same revision token as the compiled-schema cache. The body and ETag therefore always identify one atomic catalog revision, even if a definition changes while the request is being served.
Type visibility and record accessโ
Object metadata is tenant-visible: access-restricted object types still appear in the workspace
schema, so schema discovery is stable across roles. Per-type ACLs protect record data instead. Querying
a denied root or relationship field returns an explicit GraphQL field error with
extensions.code = "https://problems.tourfold.com/access-denied" and
extensions.data.reason = "not_member"; the denied field becomes null according to GraphQL's normal
null propagation rules. Types that exist only as children of another record are never listed at the
root and remain reachable only through their parent.