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.
| Wert | Bedeutung |
|---|---|
| Objekt, Array, String, Zahl, Boolean | Ein gespeichertes Dokument |
{} oder [] | Ein gespeichertes Dokument, keine Löschung |
null auf oberster Ebene beim Schreiben | Leert das Attribut |
| Attribut fehlt beim Lesen | Es 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:
| Grenze | Wert | Fehlertyp |
|---|---|---|
| Kompakte UTF-8-Größe | 65.536 Bytes | raw-json-too-large |
| Verschachtelungstiefe | 32 Ebenen aus Objekten und Arrays | raw-json-too-deep |
| Elemente pro Objekt oder Array | 1.000 Schlüssel oder Elemente | raw-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 (
1e3wird als1000gelesen) und-0wird zu0. 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": []}
}
}
| Konfiguration | Verhalten |
|---|---|
is_required | Ein Dokument muss vorhanden sein; {} und [] erfüllen die Anforderung. |
default | Ein beliebiges Dokument innerhalb der Grenzen, das beim Anlegen eingesetzt wird, wenn ein Datensatz das Attribut auslässt. |
is_unique | Nicht 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äche | Fähigkeit |
|---|---|
REST filter_operators | is_null für optionale Dokumente; keine für Pflichtdokumente |
REST is_sortable | false |
| GraphQL-Ausgabe | JSON-Skalar mit dem Dokument |
| GraphQL-Filter | JsonOperators mit _is_null; ein Pflichtdokument hat kein Filterfeld |
GraphQL order_by | Nicht verfügbar |
| Suche | Nicht 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.