Schema und Benennung
Das GraphQL-Schema Ihres Workspace wird aus seinem Schemakatalog erzeugt: aus Objekt-, Fahrzeug- und Aufgabendefinitionen sowie unterstützten integrierten Ressourcen. Die zuständige Funktion bestimmt Felder und Leseberechtigungen. Ein Eintrag im Katalog allein macht eine Ressource nicht abfragbar. Fahrzeugstandorte bleiben Felder eines Fahrzeugs und bilden keine eigene Sammlung.
Weil es pro Workspace gilt, wird kein statisches Schemadokument veröffentlicht. Laden Sie das aktuelle herunter:
curl "https://api.tourfold.com/api/v2/graphql/schema" \
-H "Authorization: Bearer YOUR_TOKEN"
Die Antwort ist SDL als text/plain und eignet sich für eine GraphQL-IDE, Insomnia, GraphiQL oder ein
Codegen-Werkzeug, das auf eine Datei zeigt. Typen, Felder, Argumente, Filteroperatoren und
Paginierungshilfen enthalten Beschreibungen. Eine IDE mit Introspection-Unterstützung kann das erzeugte
Schema dadurch ohne separate statische Referenz erklären.
Die Antwort trägt außerdem einen privaten ETag. Validieren Sie ein gespeichertes Schema erneut, statt
es jedes Mal vollständig zu laden:
curl "https://api.tourfold.com/api/v2/graphql/schema" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H 'If-None-Match: "SCHEMA_ETAG"'
Bei unverändertem Schema antwortet die API mit 304 Not Modified ohne Body. Eine Änderung an Definition,
Attribut oder Relation erzeugt einen neuen ETag und liefert die neue SDL mit 200 OK.
Da das Schema pro Workspace gilt und zur Laufzeit erzeugt wird, ist Codegenerierung zur Buildzeit gegen ein gemeinsames Schema nicht möglich. Generieren Sie gegen Ihre eigene heruntergeladene SDL und wiederholen Sie das, wenn sich Ihre Definitionen ändern.
Ressourcenmetadaten entdecken
Die REST-Definitionsabfrage liefert effektive Felder und Berechtigungen
unter GET /api/v2/definitions/all und /{definition_ref}. Konkrete Fahrzeug- und
Aufgabendefinitionen sind standardmäßig enthalten; interne Familienwurzeln sind ausgeschlossen.
Der erweiterbare resource_type bezeichnet die Ressource. Physische Datenbankzuordnungen und
öffentliche Basis-IDs werden nicht veröffentlicht.
GraphQL behält familienweite Wurzelfelder und seine bestehende Connection-Paginierung. Die Feldauswahl bestimmt, ob eine kompakte oder ausführliche Darstellung zurückgegeben wird. Die REST-Listenzugehörigkeit ändert das GraphQL-Wurzelschema nicht. Sichtbare Metadaten gewähren weder Datensatzzugriff noch Bearbeitungsrechte. Native Abfrageprojektionen werden durch ihre Auflistung nicht automatisch zu Beziehungszielen.
Wurzelfelder
Jede unterstützte benutzerdefinierte oder integrierte Definition steuert genau ein Wurzelfeld bei, benannt nach dem Slug der Definition, das eine Connection zurückgibt:
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!
}
Der Feldname ist der Singular-Slug — also equipment, nicht equipments —, weil er der
Definitions-Slug unverändert ist und keine Pluralbildung stattfindet.
Ein Workspace ohne unterstützte Definitionen erhält ein Platzhalterschema mit _empty: String.
Typ- und Feldnamen
Slugs von Definitionen und Attributen folgen bereits dem GraphQL-sicheren Muster
^[a-z][a-z0-9_]*$: Sie beginnen mit einem Kleinbuchstaben und enthalten danach nur Kleinbuchstaben,
Ziffern und Unterstriche. Bindestriche sind nicht zulässig. Das erzeugte GraphQL-Feld übernimmt den Slug
unverändert.
| Definitions-Slug oder Eigenschaftsname | GraphQL-Name |
|---|---|
equipment | equipment |
asset_tag | asset_tag |
maintenance_request | maintenance_request |
Anzeigenamen dürfen Leerzeichen und Satzzeichen enthalten; sie werden nie zu GraphQL-Bezeichnern.
Die erzeugten Typnamen folgen festen Mustern und sind damit vorhersagbar:
| Art | Muster | Beispiel |
|---|---|---|
| Objekttyp | <slug> | equipment |
| Connection | <slug>Connection | equipmentConnection |
| Edge | <slug>Edge | equipmentEdge |
| Filter-Input | <slug>Filter | equipmentFilter |
| Order-by-Input | <slug>OrderBy | equipmentOrderBy |
| Enum | <slug>_<feld> | equipment_category |
Fahrzeugkollektionen
Jede Fahrzeugdefinition ergänzt einen eigenen Top-Level-Typ, eine Connection, eine Edge und ein
Wurzelfeld unter ihrem Slug, etwa bicycle (bicycleConnection). Felder, Filter und Sortierung
verwenden dort dieselben flachen Attributnamen wie eine Objektkollektion. Die gemeinsame Kollektion
vehicle fragt definitionsübergreifend ab, liefert vehicleConnection mit den gemeinsamen
Fahrzeugfeldern (id, definition_id, natural_id, display_name, location, created_at,
updated_at, lock_version) und akzeptiert nur Filter und Sortierung nach id, definition_id,
natural_id, created_at und updated_at. Ein Filter auf definition_id schaltet auf vehicle
keine benutzerdefinierten Filter frei.
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 hat den Typ ID!, natural_id ist wie bei REST eine formatierte Zeichenfolge.
Es gibt keine implizite Standarddefinition: Fahrzeuge gehören zu ausdrücklich angelegten oder
von einem Plugin installierten Definitionen.
Beziehungen zu einer konkreten Fahrzeugdefinition liefern deren Top-Level-Typ (bicycle bzw.
bicycleConnection) und verwenden deren Filter. Beziehungen zur Fahrzeugfamilie liefern vehicle
bzw. vehicleConnection und erlauben nur gemeinsame Filter. Rückbeziehungen zur Fahrzeugfamilie
stehen sowohl auf vehicle als auch auf jedem konkreten Fahrzeugtyp bereit. Der aktuelle Standort
ist das nullable Feld location.
Tourkollektionen
system_tour stellt Kern-Touren über dieselbe Relay-Connection (system_tourConnection), where: system_tourFilter und order_by: [system_tourOrderBy!] bereit wie andere Wurzelkollektionen:
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 liefert die description der Tour, sofern vorhanden, und fällt sonst auf #<natural_id> zurück.
vehicles enthält die aktuellen Fahrzeugzuordnungen (TourVehicle); ohne vehicles:read werden vehicle_definition_id,
vehicle_natural_id, vehicle_display_name, vehicle_eligibility und vehicle ausgeblendet (vehicle_details_restricted: true).
Das Selektieren von stops auf einer Tour mit task_visit-Stopps sowie von stops { task_ids }, tasks oder task_assignments erfordert tasks:read.
Abbildung der Attributtypen
Der semantische Attributtyp aus der typisierten REST API bestimmt die GraphQL-Form:
| Typisiertes Attribut | GraphQL | Hinweise |
|---|---|---|
text, email, phone | String | Telefonnummern sind normalisierte E.164-Strings. |
date | Date | 2026-03-14 |
date_time | DateTime | RFC 3339, z. B. 2026-03-14T09:30:00Z |
number, capacity, measure, currency, rating | Float | Eine eigene Ganzzahlabbildung gibt es nicht. |
boolean | Boolean | |
einfacher select, state | erzeugtes Enum | Ausgabewerte verwenden den aktuellen value der Auswahl bzw. des Status. |
Mehrfach-select | [String] | Ausgabewerte verwenden den aktuellen value der Auswahl. |
raw_json | JSON | Das gespeicherte Dokument als JSON-Skalar; siehe Rohe JSON-Dokumente. |
rich_text | RecordRichText | html ist das kanonische Markup, text seine Nur-Text-Projektion; siehe Formatierter Text. |
full_name | RecordFullName | title, first_name, last_name plus das kombinierte display; siehe Vollständiger Name. |
links | RecordLinks | primary: RecordLink! und alternatives: [RecordLink!]!, jeweils {url, label}; siehe Links. |
location | RecordLocation | Geschlossener strukturierter Wert; siehe unten. |
tags, required_skills, provided_skills | Listen von Zielobjekten | Aufgelöste Objekte statt roher UUID-Arrays. |
relationship | Zielobjekt oder Connection | To-one bzw. To-many folgt der Kardinalität. |
totalCount ist ein Long, kein Int — eine Sammlung kann mehr als 2³¹ Datensätze enthalten.
Enums
Ein einfaches Select- oder Statusattribut mit Auswahlwerten wird zu einem GraphQL-Enum namens
<slug>_<feld>; jeder Wert wird wie ein Feldname bereinigt:
enum equipment_category {
hvac
elevator
lighting
}
Auswahlwerte dürfen Satzzeichen enthalten. Werden zwei Werte zum selben Enum-Symbol bereinigt — etwa
in-progress und in progress jeweils zu in_progress —, hängt Tourfold eine stabile Endung aus der
unveränderlichen ID der jeweiligen Option an. Beide Werte bleiben damit abfragbar. Prüfen Sie ihre genauen
Symbole in der heruntergeladenen SDL. Werte ohne Kollision behalten ihren gewöhnlichen Namen ohne Endung.
Beim Filtern sind Enum-Operanden Strings (_eq: "hvac" oder _in: ["hvac"]) und keine nackten
Enum-Literale — der Enum-Typ gilt für das Ausgabefeld, nicht für den Filter-Input.
Standortwerte
Standorte sind typisierte Objekte und keine undurchsichtigen JSON-Strings:
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!
}
Verfolgte Standorte können zusätzlich die aktuell aufgelösten Koordinaten und Adressfelder enthalten. Standortattribute können selektiert, aber nicht direkt gefiltert oder sortiert werden.
Pflichtfelder
Vom Server gepflegte Systemfelder sind non-null. Benutzerdefinierte Attributfelder bleiben in GraphQL
nullable, auch wenn config.is_required wahr ist: Die Pflichtangabe beschränkt REST-Schreibvorgänge;
GraphQL ist eine Leseoberfläche und kann Datensätze sehen, die vor einer Schemaänderung entstanden sind.
Systemfelder
Jeder Typ trägt fünf Felder, die Tourfold selbst pflegt. Sie deklarieren sie nicht und können sie nicht ändern:
| Feld | Typ | |
|---|---|---|
id | ID! | Die UUID des Datensatzes. |
display_name | String! | Kanonischer Name aus der Anzeigevorlage des Objekts, mit id als Rückfallwert. |
created_at | DateTime! | |
updated_at | DateTime! | |
lock_version | Long! | Zähler für optimistisches Locking, genutzt beim Schreiben über REST. |
lock_version ist selektierbar, kann aber nicht gefiltert oder sortiert werden — es ist
schreibseitige Buchführung ohne sinnvolle Vergleichssemantik. Die anderen drei filtern und sortieren wie
jedes Feld ihres Typs.
display_name verwendet denselben Renderer und dieselben Rückfallregeln wie REST-Datensätze und
Relationsreferenzen. Selektieren Sie das Feld direkt, statt die Anzeigevorlage im Client nachzubauen.
Relationen
Jede Relation, die Sie definieren, steuert beiden beteiligten Typen ein Feld bei, benannt nach dem Slug dieser Seite in Richtung der anderen. Die Form richtet sich nach der Kardinalität des Ziels:
To-one — ein einfaches, nullable Objektfeld ohne Argumente:
type maintenance_request {
equipment: equipment
}
To-many — eine Connection mit denselben Argumenten für Filtern, Sortieren und Paginieren wie ein Wurzelfeld:
type equipment {
maintenance_requests(
where: maintenance_requestFilter
order_by: [maintenance_requestOrderBy!]
first: Int
after: String
last: Int
before: String
offset: Int
): maintenance_requestConnection
}
Eine Abfrage kann damit in beide Richtungen laufen:
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
}
}
}
}
}
}
}
Aus den Erzeugungsregeln folgt einiges unmittelbar:
- Selbstreferenzierende Relationen funktionieren. Eine Definition, die mit sich selbst verknüpft ist, erhält beide Felder auf demselben Typ.
- Verwaltete Rückseiten sind abfragbar. Eine beidseitige Beziehung kann von beiden Objekten aus durchlaufen werden, obwohl REST-Schreibvorgänge nur über ihre deklarierende Eigentümerseite erfolgen.
- Plattforminterne verborgene Connector-Seiten werden weggelassen. Sie steuern weder Ausgabe- noch Filterfelder bei.
- Verschachtelte Connections haben eine eigene, kleinere Standard-Seitengröße — 10 statt 20 —, weil sie einmal pro übergeordnetem Datensatz aufgelöst werden. Siehe Paginierung.
- Die Traversierungstiefe ist begrenzt. Eine Connection kostet mehrere Ebenen gegen das Tiefenlimit, siehe Fehler und Limits.
Wann das Schema aktualisiert wird
Das kompilierte Schema wird pro Workspace zwischengespeichert, mit einem Token als Schlüssel, das sich bei jeder Änderung einer Definition oder Relation ändert. Eine Definitionsänderung ist deshalb bei der nächsten Abfrage sichtbar, auf jeder API-Instanz — Sie müssen kein Cache-Fenster abwarten und treffen nicht sporadisch auf ein veraltetes Schema, je nachdem welche Instanz Sie bedient hat.
Zwischengespeicherte Schemata werden außerdem nach zehn Minuten ohne Änderung verworfen. Beobachtbar ist davon nichts, außer dass die erste Abfrage danach geringfügig langsamer ist.
Der ETag des Schema-Endpoints verwendet dasselbe Revisionstoken wie der Cache des kompilierten Schemas. Body und ETag bezeichnen deshalb immer genau dieselbe Katalogrevision — auch wenn sich eine Definition während der Anfrage ändert.
Sichtbarkeit von Typen und Zugriff auf Datensätze
Objektmetadaten sind für den Tenant sichtbar: Auch zugriffsbeschränkte Objekttypen bleiben im
Workspace-Schema, sodass die Schema-Ermittlung für alle Rollen stabil ist. Die ACL je Typ schützt
stattdessen die Datensätze. Eine Abfrage eines verweigerten Wurzel- oder Relationsfelds liefert einen
ausdrücklichen GraphQL-Feldfehler mit
extensions.code = "https://problems.tourfold.com/access-denied" und
extensions.data.reason = "not_member"; gemäß den normalen GraphQL-Regeln zur Nullweitergabe wird das
verweigerte Feld null. Typen, die nur als Kind eines anderen Datensatzes existieren, erscheinen nie auf
der Wurzelebene und bleiben ausschließlich über ihren Elterndatensatz erreichbar.
Aufgabensammlungen
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 liest alle Aufgaben definitionsübergreifend und liefert system_taskConnection. Jede
konkrete Aufgabendefinition ergänzt außerdem einen eigenen Top-Level-Typ (<slug>), eine Connection
(<slug>Connection) und ein Wurzelfeld unter ihrem Slug, einschließlich der vier Systemdefinitionen
wie system_task_simple. Gemeinsame Felder auf system_task und jedem konkreten Aufgabentyp sind
definition_id, natural_id: String!, type, execution_type, title, status, assignee_user_id,
Zeitstempel und lock_version. natural_id enthält das aktuelle Präfix der Definition, sofern eines
gesetzt ist (zum Beispiel INS-42). Ohne Präfix bleibt der Wert eine Zeichenfolge ("42"). Die UUID
bleibt die dauerhafte Identität. type ist der Name des eingebauten Typs (simple, visit oder ein
Workflow-Fragetyp) beziehungsweise der Slug einer eigenen Definition (inspection).
execution_type bezeichnet das zugrunde liegende Ausführungsverhalten. Eine eigene Prüfung kann
also type: "inspection" und execution_type: "visit" zurückgeben.
display_name entspricht dem Titel. visit.location, interaction und linked_records enthalten
die nativen Aufgabeninhalte sowohl auf system_task als auch auf konkreten Aufgabentypen; nicht
zutreffende Besuchs- oder Interaktionsdaten sind null.
Konkrete Aufgabentypen stellen ihre eigenen skalaren Attribute, Beziehungen sowie deklarierte tags-,
required_skills- und provided_skills-Attribute direkt auf dem Top-Level-Knoten bereit, genau wie
benutzerdefinierte Objekte und konkrete Fahrzeugtypen. Die Familiensammlung system_task filtert und
sortiert gemeinsame skalare Felder; konkrete Sammlungen unterstützen zusätzlich eigene skalare Felder,
Beziehungen sowie Tag- und Skill-Referenzfilter. Jede Beziehung prüft die Leseberechtigung des Ziels.
Auch Zählungen und leere Ergebnisse benötigen tasks:read.
Filter verwenden dieselben Werte wie die ausgewählten Felder: type: { _eq: "inspection" } wählt
eine Definition, während execution_type: { _eq: "visit" } eingebaute und eigene Besuchsaufgaben
liefert. natural_id erwartet Zeichenfolgen, zum Beispiel { _eq: "INS-42" } oder
{ _starts_with: "INS-" }. Eine Änderung des Definitionspräfixes ändert nachfolgende Ausgaben und
Filtertreffer; das alte Präfix bleibt kein Alias. Die Sortierung nach natural_id folgt weiterhin
der gemeinsamen numerischen Aufgabensequenz über Definitionen und Präfixe hinweg, wie bei
REST-Aufgabenlisten. Dadurch steht 2 vor 10. type sortiert nach dem öffentlichen
Definitionsbezeichner, execution_type nach dem Ausführungsverhalten.
Für Objekte, Fahrzeuge und Aufgaben liefert eine Zu-eins-Beziehung ein Zielobjekt oder null;
eine Zu-viele-Beziehung liefert eine Connection mit edges { node }, pageInfo und totalCount.
Wählen Sie für eine kompakte Ansicht nur id und display_name, für mehr Details weitere Felder.
GraphQL verwendet weder den REST-Parameter include noch dessen Struktur { items, page }.
:::note Anpassung bestehender Clients
Diese Korrektur vor der allgemeinen Verfügbarkeit ändert natural_id bei Aufgaben von Long! zu
String!, einschließlich der Filteroperanden, und hebt konkrete Fahrzeug- und Aufgabendefinitionen
auf flache Top-Level-GraphQL-Typen ohne verschachtelte data-Union an. Generieren Sie
GraphQL-Clienttypen neu und selektieren Sie benutzerdefinierte Felder direkt auf der konkreten
Fahrzeug- oder Aufgabenwurzel. Clients, die mit type das Ausführungsverhalten abfragen oder
filtern, müssen dafür execution_type verwenden; type bezeichnet jetzt die Definition.
Veröffentlichen Sie die Clientanpassungen gemeinsam mit dem Backend; alte Feldnamen werden nicht als
zusätzliche Aliase angeboten.
:::