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​
| Feature | Elements |
|---|---|
| Paragraphs and line breaks | p, br |
| Headings | h1, h2, h3 |
| Emphasis | strong, em, u, s |
| Code | code, pre (containing code) |
| Quotes | blockquote |
| Lists | ul, ol, li, including nested lists |
| Links | a 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​
| Limit | Value | Error type |
|---|---|---|
| Canonical UTF-8 size | 65,536 bytes | rich-text-too-large |
| Element nesting depth | 16 | rich-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&,<,>; 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>"
}
}
| Configuration | Behavior |
|---|---|
is_required | A document with text content must be present. |
default | Markup 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_unique | Not 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​
| Surface | Capability |
|---|---|
REST filter_operators | contains and is_null (is_null only for optional attributes) |
REST is_sortable | false |
| GraphQL output | RecordRichText { html: String!, text: String! } |
| GraphQL filter | RichTextOperators with _contains and _is_null |
GraphQL order_by | Not available |
| Search | Included 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.