Zum Hauptinhalt springen

Skalare und formatierte Werte

Skalare Attribute speichern einen einzelnen Wert direkt am Datensatz. Sie eignen sich für Sachverhalte, die weder einen kontrollierten Katalog noch eine Verknüpfung zu einer anderen Tourfold-Ressource benötigen.

Typmatrix​

TypDatensatzwertTypspezifische KonfigurationGraphQL-Ausgabe
textJSON-Stringpattern, min_length, max_lengthString
numberJSON-Zahlminimum, maximumFloat
dateVollständiges RFC-3339-Datum—Date
date_timeRFC-3339-Zeitstempel mit Offset—DateTime
booleanJSON-Boolean—Boolean
emailE-Mail-Adresse als String—String
phoneVon Tourfold akzeptierte und normalisierte Telefonnummer—String

is_required und default gelten für alle Typen dieser Tabelle. is_unique steht für unterstützte einzelne String- und Zahlenwerte zur Verfügung, nicht jedoch für Boolean. Eindeutigkeit ist nach dem Anlegen unveränderlich, da sie Teil des gespeicherten fachlichen Schlüsselvertrags ist.

Text​

Verwenden Sie text für Namen, externe Kennungen, Notizen und Codes, die nicht besser durch eine kontrollierte Option oder ein typisiertes Format dargestellt werden.

{
"slug": "asset_tag",
"type": "text",
"name": {"en": "Asset tag", "de": "Anlagenkennzeichen"},
"description": "Stabile Kennung auf dem Anlagenschild.",
"config": {
"is_required": true,
"is_unique": true,
"pattern": "[A-Z]{3}-[A-Z0-9-]+",
"min_length": 5,
"max_length": 40
}
}

pattern ist ein regulärer Ausdruck mit linearer Laufzeit. Lookaheads und Rückverweise werden abgelehnt, damit ein Schema keine problematische Laufzeit beim Matching einführt. Längengrenzen sind einschließlich und zählen den gespeicherten String.

Ein leerer String ist ein Wert und keine Löschanweisung. Verletzt er Länge, Muster oder Pflichtregeln, liefert der Schreibzugriff 422; ein optionaler Textwert wird im Merge Patch mit null gelöscht.

Typische Filter sind Gleichheit, Mengenmitgliedschaft, Enthaltensein, Präfix, Suffix und Nullprüfung. Für fachliche Schlüssel verwenden Sie ein eindeutiges Textattribut mit dem Endpoint GET /api/v2/objects/{object_ref}/records/by/{attribute_ref}?attribute_value=.... Kodieren Sie den Wert im Query-Parameter attribute_value URL-gerecht.

Zahl​

Verwenden Sie number für eine dimensionslose Größe mit optionaler Unter- oder Obergrenze.

{
"slug": "service_interval_days",
"type": "number",
"name": {"en": "Service interval (days)", "de": "Wartungsintervall (Tage)"},
"config": {
"minimum": 1,
"maximum": 3650,
"default": 365
}
}

Die REST API akzeptiert eine JSON-Zahl und validiert die einschließlich geltenden Grenzen minimum und maximum. Ist die Einheit Teil der Bedeutung, verwenden Sie nicht number, sondern measure, capacity oder currency. So liegt die Einheit im Schema und kann nicht je Datensatz wechseln.

GraphQL stellt alle Zahlenfamilien als Float dar; es gibt keinen gesonderten generierten Integer-Typ. Wenn exakte Dezimalarithmetik wichtig ist, behalten Sie für Berechnungen die REST-JSON-Darstellung bei, statt Finanzwerte über GraphQL-Gleitkommazahlen zu führen.

Datum und Zeitstempel​

Verwenden Sie date für einen Kalendertag, dessen Bedeutung nicht von einer Zeitzone abhängt:

{"data":{"commissioned_on":"2026-08-27"}}

Verwenden Sie date_time für einen Zeitpunkt. Senden Sie RFC 3339 mit ausdrücklichem Offset:

{"data":{"last_inspected_at":"2026-08-27T13:45:00+02:00"}}

Wandeln Sie ein lokales Datum nicht nur deshalb in Mitternacht UTC um, um ein Zeitstempelfeld zu befüllen; das verändert das Modell. Datum und Zeitstempel unterstützen Gleichheit, Sortierung, Bereiche und Nullprüfung. GraphQL stellt sie über die generierten Skalare Date und DateTime dar.

Boolean​

Verwenden Sie boolean nur, wenn true und false die vollständigen fachlichen Zustände sind. Wenn „unbekannt“, „nicht geprüft“ oder ein Workflow-Übergang wichtig ist, lassen Sie das Attribut optional oder verwenden Sie state.

{
"slug": "operational",
"type": "boolean",
"name": {"en": "Operational", "de": "Betriebsbereit"},
"config": {"default": true}
}

Ein ausgelassener optionaler Boolean, false und null sind drei verschiedene Fälle. JSON muss die Boolean-Literale true oder false enthalten, niemals deren Stringformen.

E-Mail​

Verwenden Sie email, wenn der Wert eine E-Mail-Adresse sein soll und Verbraucher von Formatvalidierung profitieren. Für beliebige Zustellsyntax oder eine kommaseparierte Liste ist gewöhnlicher text passender.

{
"slug": "service_contact_email",
"type": "email",
"name": {"en": "Service contact email", "de": "E-Mail des Servicekontakts"}
}

Ein Attribut enthält eine Adresse. Mehrere Kontakte sollten als verknüpfte Datensätze modelliert werden, nicht als versteckte Liste in einem String.

Telefon​

Verwenden Sie phone für wählbare Telefonnummern. Tourfold parst akzeptierte Eingaben und liefert einen normalisierten E.164-Wert wie +43123456789.

{
"slug": "service_phone",
"type": "phone",
"name": {"en": "Service phone", "de": "Servicetelefon"}
}

Durchwahlen oder frei formulierte Hinweise gehören in ein getrenntes Textattribut. Integrationen sollten den normalisierten Lesewert vergleichen, nicht die vom Benutzer eingegebene Formatierung.

Fehler und Änderungsereignisse​

Ein falscher JSON-Typ, ungültiges Format, verletzte Grenze oder nicht eindeutiger Wert liefert 422 mit einem Pointer wie #/data/asset_tag. Siehe Fehlervertrag.

Webhook-Payloads für Objektdatensätze haben ein offenes Schema. Bei einer Änderung enthält data.previous_attributes den alten Wert nur für tatsächlich geänderte Schlüssel. Ignorieren Sie unbekannte Payload-Schlüssel und verwenden Sie Objekt- und Attributidentitäten, wenn dauerhaftes Routing wichtig ist.