Zum Hauptinhalt springen

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.

hinweis

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 EigenschaftsnameGraphQL-Name
equipmentequipment
asset_tagasset_tag
maintenance_requestmaintenance_request

Anzeigenamen dürfen Leerzeichen und Satzzeichen enthalten; sie werden nie zu GraphQL-Bezeichnern.

Die erzeugten Typnamen folgen festen Mustern und sind damit vorhersagbar:

ArtMusterBeispiel
Objekttyp<slug>equipment
Connection<slug>ConnectionequipmentConnection
Edge<slug>EdgeequipmentEdge
Filter-Input<slug>FilterequipmentFilter
Order-by-Input<slug>OrderByequipmentOrderBy
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.

electric-bicycles.graphql
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 AttributGraphQLHinweise
text, email, phoneStringTelefonnummern sind normalisierte E.164-Strings.
dateDate2026-03-14
date_timeDateTimeRFC 3339, z. B. 2026-03-14T09:30:00Z
number, capacity, measure, currency, ratingFloatEine eigene Ganzzahlabbildung gibt es nicht.
booleanBoolean
einfacher select, stateerzeugtes EnumAusgabewerte verwenden den aktuellen value der Auswahl bzw. des Status.
Mehrfach-select[String]Ausgabewerte verwenden den aktuellen value der Auswahl.
raw_jsonJSONDas gespeicherte Dokument als JSON-Skalar; siehe Rohe JSON-Dokumente.
rich_textRecordRichTexthtml ist das kanonische Markup, text seine Nur-Text-Projektion; siehe Formatierter Text.
full_nameRecordFullNametitle, first_name, last_name plus das kombinierte display; siehe Vollständiger Name.
linksRecordLinksprimary: RecordLink! und alternatives: [RecordLink!]!, jeweils {url, label}; siehe Links.
locationRecordLocationGeschlossener strukturierter Wert; siehe unten.
tags, required_skills, provided_skillsListen von ZielobjektenAufgelöste Objekte statt roher UUID-Arrays.
relationshipZielobjekt oder ConnectionTo-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:

FeldTyp
idID!Die UUID des Datensatzes.
display_nameString!Kanonischer Name aus der Anzeigevorlage des Objekts, mit id als Rückfallwert.
created_atDateTime!
updated_atDateTime!
lock_versionLong!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:

equipment-with-open-requests.graphql
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​

open-tasks.graphql
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. :::