Skip to main content

Rich text

rich_text stores formatted notes and descriptions: headings, emphasis, lists, quotes, code and links. The canonical representation is an HTML fragment restricted to a bounded element set. Writes are normalized to that form, reads return it unchanged, and every consumer that cannot render markup receives the same deterministic plain-text projection.

Use text for identifiers, names and single-line values. Use rich_text when the value is prose that people format. An existing text attribute cannot change type; migrate by creating a rich_text attribute and writing the old values, which become paragraphs (see Converting from text).

Supported markup​

FeatureElements
Paragraphs and line breaksp, br
Headingsh1, h2, h3
Emphasisstrong, em, u, s
Codecode, pre (containing code)
Quotesblockquote
Listsul, ol, li, including nested lists
Linksa with href using http, https, mailto or tel

href is the only attribute a document may carry. b, i, strike and del are accepted and normalized to strong, em and s. Anything else, including img, tables, style, class, event handlers and other URL schemes, is rejected rather than stripped so the caller learns exactly what an imported document contained.

Limits​

LimitValueError type
Canonical UTF-8 size65,536 bytesrich-text-too-large
Element nesting depth16rich-text-too-deep

Other validation errors: rich-text-unsupported-element, rich-text-unsupported-attribute, rich-text-unsafe-link and type-mismatch for a non-string value. All of them point at the attribute, for example #/data/notes. The record payload cap (413 payload-too-large) applies first.

Normalization​

The stored form is deterministic and idempotent:

  • Alias elements become their canonical element; comments are dropped.
  • Text or inline markup directly in the fragment is wrapped in a paragraph; newlines in such text become <br>.
  • Non-breaking spaces become spaces; &, <, > are escaped as &amp;, &lt;, &gt;; link targets are trimmed.
  • Whitespace between elements and attribute quoting are serialized compactly.

Formatting inside the supported set is preserved exactly. Byte-for-byte preservation of the submitted markup is not promised.

Empty documents​

A document whose plain-text projection is blank (for example <p></p>, <p><br></p> or an empty list) has no value. On write it clears the attribute exactly like null: an optional attribute is removed and a required one returns 422 required-field. Reads never return an empty document.

Definition​

{
"slug": "handover_notes",
"type": "rich_text",
"name": {"en": "Handover notes", "de": "Übergabenotizen"},
"config": {
"is_required": false,
"default": "<p>Check <strong>tyres</strong></p>"
}
}
ConfigurationBehavior
is_requiredA document with text content must be present.
defaultMarkup in the supported subset, normalized and limited like record values, applied when a record omits the attribute on create. Plain text becomes a paragraph.
is_uniqueNot supported; returns 422 unique-unsupported-type.

Rich text has no pattern or length constraints beyond the platform limits.

Record writes​

{
"data": {
"handover_notes": "<p>Fuel card in <em>glovebox</em></p><ul><li>Check tyres</li></ul>"
}
}

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 or an empty document clears it.

Plain-text projection​

Display templates, record search, the GraphQL text field and compact list previews use one projection: block elements end a line, <br> breaks a line, bullet items are prefixed with - and ordered items with their number, inline markup is dropped, entities are decoded and whitespace collapses except inside pre. Display templates and the global search additionally collapse the result to one line. Link targets are not part of the projection.

Query capabilities​

SurfaceCapability
REST filter_operatorscontains and is_null (is_null only for optional attributes)
REST is_sortablefalse
GraphQL outputRecordRichText { html: String!, text: String! }
GraphQL filterRichTextOperators with _contains and _is_null
GraphQL order_byNot available
SearchIncluded through the plain-text projection; markup and link targets are not indexed

contains matches the plain-text projection case-insensitively. Prefix, suffix, equality and ordering operators return 422 filter-operator-not-applicable; a sort returns 422 unsupported-sort-field.

Converting from text​

Attribute types are immutable. To move an existing text attribute to rich text, create a rich_text attribute, copy each value, then remove the old attribute once nothing reads it. Writing a plain string to a rich_text attribute is a deterministic conversion: it becomes a paragraph and each newline a line break, so nothing is lost. The reverse direction is lossy: use the plain-text projection and expect formatting to disappear.

Integration surfaces​

Webhook payloads, MCP record tools and workflow record operations carry the canonical HTML string inside data, exactly as REST returns it. Consumers that render it must sanitize again with the same allow-list; the Tourfold web app does.