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
| Typ | Datensatzwert | Typspezifische Konfiguration | GraphQL-Ausgabe |
|---|---|---|---|
text | JSON-String | pattern, min_length, max_length | String |
number | JSON-Zahl | minimum, maximum | Float |
date | Vollständiges RFC-3339-Datum | — | Date |
date_time | RFC-3339-Zeitstempel mit Offset | — | DateTime |
boolean | JSON-Boolean | — | Boolean |
email | E-Mail-Adresse als String | — | String |
phone | Von 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.