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.
| Value | Meaning |
|---|---|
| Object, array, string, number, Boolean | A stored document |
{} or [] | A stored document, not a request to clear |
Top-level null on write | Clears the attribute |
| Attribute absent on read | No 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:
| Limit | Value | Error type |
|---|---|---|
| Compact UTF-8 size | 65,536 bytes | raw-json-too-large |
| Nesting depth | 32 levels of objects and arrays | raw-json-too-deep |
| Items per object or array | 1,000 keys or elements | raw-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 (
1e3reads back as1000) and-0becomes0. 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
nullvalues are unchanged.
Definitionโ
{
"slug": "erp_payload",
"type": "raw_json",
"name": {"en": "ERP payload", "de": "ERP-Nutzdaten"},
"config": {
"is_required": false,
"default": {"source": "erp", "lines": []}
}
}
| Configuration | Behavior |
|---|---|
is_required | A document must be present; {} and [] satisfy it. |
default | Any document within the limits, applied when a record omits the attribute on create. |
is_unique | Not 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โ
| Surface | Capability |
|---|---|
REST filter_operators | is_null for optional documents; none for required documents |
REST is_sortable | false |
| GraphQL output | JSON scalar carrying the document |
| GraphQL filter | JsonOperators with _is_null; a required document has no filter field |
GraphQL order_by | Not available |
| Search | Not 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.