Zum Hauptinhalt springen

Rohe JSON-Dokumente

raw_json speichert ein JSON-Dokument als JSON. Verwenden Sie den Typ für strukturierte Integrationsnutzdaten, anbieterspezifische Einstellungen oder jeden Wert, den kein semantischer Attributtyp beschreibt. Clients schreiben das Dokument direkt in data und lesen es als JSON zurück; sie kodieren es nie als String.

Bevorzugen Sie immer einen semantischen Typ, wenn einer passt. Ein raw_json-Wert kann nicht gegen eine fachliche Regel geprüft, durchsucht, nach Inhalt gefiltert, sortiert oder als Beschriftung verwendet werden, und er wird kein typisiertes GraphQL-Feld. Wählen Sie den Typ, wenn der Inhalt für Tourfold tatsächlich undurchsichtig ist.

Unterstützte Werte​

Ein Dokument ist ein beliebiges JSON-Objekt, -Array, -String, -Zahl oder -Boolean, einschließlich verschachtelter Objekte und Arrays. Verschachtelte null-Elemente sind gewöhnliche Werte und bleiben erhalten.

WertBedeutung
Objekt, Array, String, Zahl, BooleanEin gespeichertes Dokument
{} oder []Ein gespeichertes Dokument, keine Löschung
null auf oberster Ebene beim SchreibenLeert das Attribut
Attribut fehlt beim LesenEs ist kein Dokument gespeichert

Ein JSON-null auf oberster Ebene ist daher kein speicherbares Dokument: Die API kann es nicht von einer Löschanfrage unterscheiden. Verpacken Sie es in ein Objekt oder Array, wenn die Unterscheidung wichtig ist.

Grenzen​

Jedes Dokument, einschließlich eines Attribut-default, muss innerhalb dieser Grenzen bleiben:

GrenzeWertFehlertyp
Kompakte UTF-8-Größe65.536 Bytesraw-json-too-large
Verschachtelungstiefe32 Ebenen aus Objekten und Arraysraw-json-too-deep
Elemente pro Objekt oder Array1.000 Schlüssel oder Elementeraw-json-too-many-items

Fehler sind Feldfehler mit einem JSON Pointer in das Dokument, zum Beispiel #/data/payload/items. Die Obergrenze für Datensatznutzdaten (413 payload-too-large, siehe Fehlertypen) greift vor diesen Grenzen, sodass ein Dokument innerhalb eines Datensatzes auch durch die Datensatzgröße begrenzt ist.

Normalisierung​

Dokumente werden in PostgreSQL jsonb gespeichert. Das gespeicherte Dokument ist semantisch gleich dem geschriebenen, bleibt aber nicht byteweise erhalten:

  • Die Reihenfolge der Objektschlüssel bleibt nicht erhalten, und bei doppelten Schlüsseln gilt der letzte Wert.
  • Unbedeutende Leerzeichen entfallen.
  • Zahlen werden als Dezimalzahlen mit beliebiger Genauigkeit gespeichert, sodass Ganzzahlen jeder Größe und Dezimalstellen die Datenbank überstehen. Exponentenschreibweise wird ausgeschrieben (1e3 wird als 1000 gelesen) und -0 wird zu 0. Der Request-Parser liest Dezimalbrüche als IEEE-754-Doubles, sodass Dezimalzahlen mit mehr als etwa 15 signifikanten Stellen vor dem Speichern gerundet werden können. Senden Sie exakte Dezimalkennungen als Strings.
  • Strings, Booleans und verschachtelte null-Werte bleiben unverändert.

Definition​

{
"slug": "erp_payload",
"type": "raw_json",
"name": {"en": "ERP payload", "de": "ERP-Nutzdaten"},
"config": {
"is_required": false,
"default": {"source": "erp", "lines": []}
}
}
KonfigurationVerhalten
is_requiredEin Dokument muss vorhanden sein; {} und [] erfüllen die Anforderung.
defaultEin beliebiges Dokument innerhalb der Grenzen, das beim Anlegen eingesetzt wird, wenn ein Datensatz das Attribut auslässt.
is_uniqueNicht unterstützt; liefert 422 unique-unsupported-type.

Muster-, Längen-, Zahlen- und Elementbeschränkungen sind nicht verfügbar. Dokumente können nicht aus einem display_template referenziert werden (422 unsupported-display-template-attribute).

Datensatzschreibvorgänge​

{
"data": {
"erp_payload": {"source": "erp", "lines": [{"sku": "A1", "qty": 2}]}
}
}

Änderungen folgen dem JSON-Merge-Patch-Vertrag der Datensätze auf Attributebene: Ein ausgelassenes Attribut bleibt unverändert, ein mitgesendetes Dokument ersetzt das gespeicherte Dokument vollständig, und null leert es. Der Patch führt keine Zusammenführung mit dem gespeicherten Dokument durch; um einen Schlüssel eines gespeicherten Objekts zu entfernen, senden Sie das vollständige Objekt ohne diesen Schlüssel.

Abfragefähigkeiten​

OberflächeFähigkeit
REST filter_operatorsis_null für optionale Dokumente; keine für Pflichtdokumente
REST is_sortablefalse
GraphQL-AusgabeJSON-Skalar mit dem Dokument
GraphQL-FilterJsonOperators mit _is_null; ein Pflichtdokument hat kein Filterfeld
GraphQL order_byNicht verfügbar
SucheNicht Teil der Volltextsuche über Datensätze

Enthaltens- und Pfadabfragen werden bewusst nicht angeboten. Jeder andere Operator liefert 422 filter-operator-not-applicable, eine Sortierung liefert 422 unsupported-sort-field. Modellieren Sie Werte, nach denen gefiltert werden muss, stattdessen als eigene Attribute.

Integrationsoberflächen​

Webhook-Nutzdaten, MCP-Datensatzwerkzeuge und Workflow-Datensatzoperationen übertragen das Dokument als JSON innerhalb von data, genau wie REST es zurückgibt. Mehrfachauswahl-Attribute behalten auf jeder Oberfläche ihren eigenen Array-aus-Auswahlwerten-Vertrag; ein Dokument wird nie als Auswahlliste behandelt.