Attributtyp auswählen
Ein Attributtyp ist mehr als eine JSON-Form. Er bestimmt Validierung, kanonische Lesewerte, verfügbare Filter, GraphQL-Felder, Eindeutigkeit und die Darstellung in Webhook-Payloads. Wählen Sie den Typ, dessen Verhalten zum fachlichen Sachverhalt passt – nicht nur zum Wert, den Sie heute vorliegen haben.
Die passende Familie finden
| Sie möchten Folgendes abbilden | Einstieg |
|---|---|
| Text, Kennungen, E-Mail, Telefon, Datum, Zeitstempel, Zahlen oder Schalter | Skalare und formatierte Werte |
| Kontrollierte Liste, Workflow-Status, Geld, Messwert, Kapazität oder Bewertung | Auswahlwerte, Größen und Bewertungen |
| Tags, Fähigkeiten, einen anderen Datensatz, Adresse, Koordinaten oder Live-Tracking | Verknüpfungen und Standorte |
| Strukturierte Integrationsnutzdaten oder einen anderen JSON-Wert, zu dem kein semantischer Typ passt | Rohe JSON-Dokumente |
| Formatierte Notizen oder Beschreibungen mit Überschriften, Hervorhebungen, Listen und Links | Formatierter Text |
| Den Namen einer Person mit optionalem Titel, nach Bestandteilen bearbeitet und sortiert | Vollständiger Name |
| Einen Hauptlink auf Webseite, Mail oder Telefon mit beschrifteten Alternativen | Links |
Die öffentliche API bietet ein geschlossenes Typvokabular. Clients senden weder JSON Schema noch Datenbankspalten oder Indexdetails.
Gemeinsames Verhalten aller Attribute
Jedes benutzerverwaltete Attribut besitzt:
| Feld | Vertrag |
|---|---|
id | Unveränderliche UUID. Bei deklarativen Schemaänderungen mitsenden, damit die Identität bei einer Slug-Umbenennung erhalten bleibt. |
slug | Veränderlicher API- und GraphQL-Feldname nach ^[a-z][a-z0-9_]*$. |
type | Fester semantischer Typ. Ersetzen Sie das Attribut nur, wenn sich seine Bedeutung tatsächlich ändert. |
name | Lokalisierte Beschriftung mit ISO-639-1-Sprachcodes als Schlüssel. |
description | Optionale Erklärung, die im generierten GraphQL-Schema erscheint. |
config.is_required | Verlangt einen Wert; bei Verknüpfungsmengen mindestens ein Element. |
config.is_unique | Nur für unterstützte einzelne Skalarwerte verfügbar und nach Erstellung unveränderlich. |
config.default | Wird bei ausgelassenen direkt gespeicherten Werten beim Anlegen eingesetzt; nicht für Verknüpfungen und Standorte. Ein raw_json-Standardwert ist ein JSON-Dokument. |
Die Konfiguration ist strikt. Ein unbekannter Schlüssel oder ein Schlüssel, der nicht zum Typ passt,
liefert 422 validation-failed mit einem JSON Pointer auf das fehlerhafte Feld. Tourfold verwirft
falsch geschriebene Einschränkungen nicht stillschweigend.
Schreibregeln für Datensätze
Der Datensatz-Envelope bleibt immer gleich:
{
"data": {
"attribute_slug": "typisierter Wert"
}
}
- Beim Anlegen bleibt ein ausgelassener optionaler Wert ungesetzt oder erhält seinen Standardwert.
- Beim Merge Patch bleibt ein ausgelassener Schlüssel unverändert;
nulllöscht einen optionalen Wert. - Arrays sind Ersatzmengen, keine Anhängeoperationen.
[]leert eine beschreibbare Menge. - Ein
raw_json-Dokument ist ein einzelner Wert: Ein mitgesendetes Dokument ersetzt das gespeicherte vollständig, und{}oder[]sind Dokumente, keine Löschungen. - Ein
rich_text-Dokument ohne Textinhalt leert das Attribut wienull. - Ein
full_name- oderlinks-Objekt ersetzt das gespeicherte Objekt vollständig; eines ohne Inhalt leert das Attribut wienull. - Pflichtwerte können nicht gelöscht werden.
- Systemattribute und verwaltete Rückbeziehungen sind trotz ihrer Anzeige in der Definition nur lesbar.
Leseformen sind kanonisch
Mehrere Typen akzeptieren beim Schreiben einen lesbaren Bezeichner und liefern beim Lesen eine unveränderliche Identität. Ein Select akzeptiert etwa den Optionswert, liefert aber die Options-UUID; Tags akzeptieren Labels und liefern aufgelöste Objekte. Behandeln Sie die Antwort als kanonische Form. Aufgelöste Verknüpfungen können zurückgeschrieben werden, außer das Attribut ist eine verwaltete Rückprojektion.
Aufgaben von REST und GraphQL
REST verwaltet Definitionen und sämtliche Datensatzänderungen. Der strukturierte Query-Endpoint eignet sich für flache, paginierte Ergebnismengen und Synchronisierung. GraphQL ist nur lesend und eignet sich für verbundene Abfragen. Beide Oberflächen leiten Validierung und Abfragefähigkeiten aus derselben Attributdefinition ab.
Das generierte GraphQL-Schema kann sich ändern, wenn sich Slug, Auswahl, Status oder Beziehung ändern.
Laden Sie es vom Schema-Endpoint des Workspaces und cachen Sie es mit seinem ETag; siehe
Schema und Benennung.
Checkliste für das Schema
Klären Sie vor dem Anlegen eines Attributs:
- Ist der Wert frei, kontrolliert oder eine Referenz auf eine andere Ressource?
- Benötigt die Integration einen stabilen fachlichen Lookup? Falls ja: Kann dieser Einzelwert eindeutig sein?
- Unterscheidet sich ein fehlender Wert fachlich von einem Standardwert?
- Könnte der Wert später mehrwertig werden? Kardinalitätsänderungen wirken auf Datensatzvalidierung und generierte GraphQL-Felder.
- Wer besitzt das Schreibrecht? Bei einer zweiseitigen Beziehung verwaltet nur die deklarierende Seite die Verknüpfungsmenge.
- Welche Slugs und Auswahlwerte werden generierte Clients als Bezeichner kompilieren?
Nutzen Sie den Leitfaden zur Schemaentwicklung, bevor Sie eine dieser Antworten bei einem produktiven Objekt ändern.