Zum Hauptinhalt springen

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 abbildenEinstieg
Text, Kennungen, E-Mail, Telefon, Datum, Zeitstempel, Zahlen oder SchalterSkalare und formatierte Werte
Kontrollierte Liste, Workflow-Status, Geld, Messwert, Kapazität oder BewertungAuswahlwerte, Größen und Bewertungen
Tags, Fähigkeiten, einen anderen Datensatz, Adresse, Koordinaten oder Live-TrackingVerknüpfungen und Standorte
Strukturierte Integrationsnutzdaten oder einen anderen JSON-Wert, zu dem kein semantischer Typ passtRohe JSON-Dokumente
Formatierte Notizen oder Beschreibungen mit Überschriften, Hervorhebungen, Listen und LinksFormatierter Text
Den Namen einer Person mit optionalem Titel, nach Bestandteilen bearbeitet und sortiertVollständiger Name
Einen Hauptlink auf Webseite, Mail oder Telefon mit beschrifteten AlternativenLinks

Die öffentliche API bietet ein geschlossenes Typvokabular. Clients senden weder JSON Schema noch Datenbankspalten oder Indexdetails.

Gemeinsames Verhalten aller Attribute​

Jedes benutzerverwaltete Attribut besitzt:

FeldVertrag
idUnveränderliche UUID. Bei deklarativen Schemaänderungen mitsenden, damit die Identität bei einer Slug-Umbenennung erhalten bleibt.
slugVeränderlicher API- und GraphQL-Feldname nach ^[a-z][a-z0-9_]*$.
typeFester semantischer Typ. Ersetzen Sie das Attribut nur, wenn sich seine Bedeutung tatsächlich ändert.
nameLokalisierte Beschriftung mit ISO-639-1-Sprachcodes als Schlüssel.
descriptionOptionale Erklärung, die im generierten GraphQL-Schema erscheint.
config.is_requiredVerlangt einen Wert; bei Verknüpfungsmengen mindestens ein Element.
config.is_uniqueNur für unterstützte einzelne Skalarwerte verfügbar und nach Erstellung unveränderlich.
config.defaultWird 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; null lö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 wie null.
  • Ein full_name- oder links-Objekt ersetzt das gespeicherte Objekt vollständig; eines ohne Inhalt leert das Attribut wie null.
  • 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:

  1. Ist der Wert frei, kontrolliert oder eine Referenz auf eine andere Ressource?
  2. Benötigt die Integration einen stabilen fachlichen Lookup? Falls ja: Kann dieser Einzelwert eindeutig sein?
  3. Unterscheidet sich ein fehlender Wert fachlich von einem Standardwert?
  4. Könnte der Wert später mehrwertig werden? Kardinalitätsänderungen wirken auf Datensatzvalidierung und generierte GraphQL-Felder.
  5. Wer besitzt das Schreibrecht? Bei einer zweiseitigen Beziehung verwaltet nur die deklarierende Seite die Verknüpfungsmenge.
  6. 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.