Skip to main content

Raw JSON documents

raw_json stores a JSON document as JSON. Use it for structured integration payloads, vendor-specific settings, or any value that no semantic attribute type describes. Callers write the document directly in data and read it back as JSON; they never encode it as a string.

Prefer a semantic type whenever one fits. A raw_json value cannot be validated against a business rule, searched, filtered by content, sorted, or used as a label, and it does not become a typed GraphQL field. Choose it when the content is genuinely opaque to Tourfold.

Supported valuesโ€‹

A document is any JSON object, array, string, number, or Boolean, including nested objects and arrays. Nested null members are ordinary values and are preserved.

ValueMeaning
Object, array, string, number, BooleanA stored document
{} or []A stored document, not a request to clear
Top-level null on writeClears the attribute
Attribute absent on readNo document is stored

A top-level JSON null is therefore not a storable document: the API cannot distinguish it from a clear request. Wrap it in an object or array if the distinction matters.

Limitsโ€‹

Every document, including an attribute default, must stay within these limits:

LimitValueError type
Compact UTF-8 size65,536 bytesraw-json-too-large
Nesting depth32 levels of objects and arraysraw-json-too-deep
Items per object or array1,000 keys or elementsraw-json-too-many-items

Errors are field errors with a JSON Pointer into the document, for example #/data/payload/items. The record payload cap (413 payload-too-large, see Error types) applies before these limits, so a document inside a record is also bounded by the record size.

Normalizationโ€‹

Documents are stored in PostgreSQL jsonb. The stored document is semantically equal to what was written, but it is not preserved byte for byte:

  • Object key order is not preserved, and duplicate keys keep the last value.
  • Insignificant whitespace is dropped.
  • Numbers are stored as arbitrary-precision decimals, so integers of any size and decimal digits survive the database. Exponent notation is expanded (1e3 reads back as 1000) and -0 becomes 0. The request parser reads decimal fractions as IEEE 754 doubles, so decimals with more than about 15 significant digits may be rounded before storage. Send exact decimal identifiers as strings.
  • Strings, Booleans, and nested null values are unchanged.

Definitionโ€‹

{
"slug": "erp_payload",
"type": "raw_json",
"name": {"en": "ERP payload", "de": "ERP-Nutzdaten"},
"config": {
"is_required": false,
"default": {"source": "erp", "lines": []}
}
}
ConfigurationBehavior
is_requiredA document must be present; {} and [] satisfy it.
defaultAny document within the limits, applied when a record omits the attribute on create.
is_uniqueNot supported; returns 422 unique-unsupported-type.

Pattern, length, numeric, and item constraints are not available. Documents cannot be referenced from a display_template (422 unsupported-display-template-attribute).

Record writesโ€‹

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

Updates follow the record JSON Merge Patch contract at the attribute level: an omitted attribute is unchanged, a supplied document replaces the stored document entirely, and null clears it. The patch does not merge into the stored document; to remove one key of a stored object, send the complete object without that key.

Query capabilitiesโ€‹

SurfaceCapability
REST filter_operatorsis_null for optional documents; none for required documents
REST is_sortablefalse
GraphQL outputJSON scalar carrying the document
GraphQL filterJsonOperators with _is_null; a required document has no filter field
GraphQL order_byNot available
SearchNot included in free-text record search

Containment and path queries are deliberately not offered. Any other operator returns 422 filter-operator-not-applicable, and a sort returns 422 unsupported-sort-field. Model values that must be filtered as dedicated attributes instead.

Integration surfacesโ€‹

Webhook payloads, MCP record tools, and workflow record operations carry the document as JSON inside data, exactly as REST returns it. Multi-select attributes keep their own array-of-choices contract on every surface; a document is never treated as a choice list.