Formatierter Text
rich_text speichert formatierte Notizen und Beschreibungen: Überschriften, Hervorhebungen,
Listen, Zitate, Code und Links. Die kanonische Darstellung ist ein HTML-Fragment, das auf eine
begrenzte Menge an Elementen beschränkt ist. Schreibvorgänge werden in diese Form normalisiert,
Lesevorgänge geben sie unverändert zurück, und jeder Konsument, der kein Markup darstellen kann,
erhält dieselbe deterministische Nur-Text-Projektion.
Verwenden Sie text für Kennungen, Namen und einzeilige Werte. Verwenden Sie rich_text, wenn
der Wert Fließtext ist, den Personen formatieren. Ein bestehendes text-Attribut kann seinen Typ
nicht ändern; migrieren Sie, indem Sie ein rich_text-Attribut anlegen und die alten Werte
schreiben, die zu Absätzen werden (siehe Umstellung von Text).
Unterstütztes Markup
| Funktion | Elemente |
|---|---|
| Absätze und Zeilenumbrüche | p, br |
| Überschriften | h1, h2, h3 |
| Hervorhebung | strong, em, u, s |
| Code | code, pre (mit code) |
| Zitate | blockquote |
| Listen | ul, ol, li, auch verschachtelt |
| Links | a mit href und den Schemata http, https, mailto oder tel |
href ist das einzige Attribut, das ein Dokument tragen darf. b, i, strike und del werden
akzeptiert und zu strong, em und s normalisiert. Alles andere, einschließlich img,
Tabellen, style, class, Event-Handlern und anderen URL-Schemata, wird abgelehnt statt entfernt,
damit der Aufrufer genau erfährt, was ein importiertes Dokument enthielt.
Grenzen
| Grenze | Wert | Fehlertyp |
|---|---|---|
| Kanonische UTF-8-Größe | 65.536 Bytes | rich-text-too-large |
| Verschachtelungstiefe der Elemente | 16 | rich-text-too-deep |
Weitere Validierungsfehler: rich-text-unsupported-element, rich-text-unsupported-attribute,
rich-text-unsafe-link sowie type-mismatch für einen Wert, der kein String ist. Alle zeigen auf
das Attribut, zum Beispiel #/data/notes. Die Obergrenze für Datensatznutzdaten
(413 payload-too-large) greift zuerst.
Normalisierung
Die gespeicherte Form ist deterministisch und idempotent:
- Alias-Elemente werden zu ihrem kanonischen Element; Kommentare entfallen.
- Text oder Inline-Markup direkt im Fragment wird in einen Absatz gepackt; Zeilenumbrüche in
solchem Text werden zu
<br>. - Geschützte Leerzeichen werden zu Leerzeichen;
&,<,>werden als&,<,>maskiert; Linkziele werden getrimmt. - Leerraum zwischen Elementen und die Attributquotierung werden kompakt serialisiert.
Formatierungen innerhalb der unterstützten Menge bleiben exakt erhalten. Eine byteweise Erhaltung des übermittelten Markups wird nicht zugesichert.
Leere Dokumente
Ein Dokument, dessen Nur-Text-Projektion leer ist (zum Beispiel <p></p>, <p><br></p> oder
eine leere Liste), hat keinen Wert. Beim Schreiben leert es das Attribut genau wie null: Ein
optionales Attribut wird entfernt, ein Pflichtattribut liefert 422 required-field. Lesevorgänge
geben nie ein leeres Dokument zurück.
Definition
{
"slug": "handover_notes",
"type": "rich_text",
"name": {"en": "Handover notes", "de": "Übergabenotizen"},
"config": {
"is_required": false,
"default": "<p>Check <strong>tyres</strong></p>"
}
}
| Konfiguration | Verhalten |
|---|---|
is_required | Ein Dokument mit Textinhalt muss vorhanden sein. |
default | Markup aus der unterstützten Teilmenge, normalisiert und begrenzt wie Datensatzwerte, beim Anlegen eingesetzt, wenn ein Datensatz das Attribut auslässt. Reiner Text wird zu einem Absatz. |
is_unique | Nicht unterstützt; liefert 422 unique-unsupported-type. |
Formatierter Text hat außer den Plattformgrenzen keine Muster- oder Längenbeschränkungen.
Datensatzschreibvorgänge
{
"data": {
"handover_notes": "<p>Fuel card in <em>glovebox</em></p><ul><li>Check tyres</li></ul>"
}
}
Ä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 oder ein leeres Dokument leert es.
Nur-Text-Projektion
Anzeigevorlagen, die Datensatzsuche, das GraphQL-Feld text und kompakte Listenvorschauen
verwenden eine gemeinsame Projektion: Blockelemente beenden eine Zeile, <br> bricht eine Zeile
um, Aufzählungspunkte erhalten das Präfix - und nummerierte Punkte ihre Nummer, Inline-Markup
entfällt, Entities werden dekodiert und Leerraum wird außer in pre zusammengefasst.
Anzeigevorlagen und die globale Suche fassen das Ergebnis zusätzlich auf eine Zeile zusammen.
Linkziele sind nicht Teil der Projektion.
Abfragefähigkeiten
| Oberfläche | Fähigkeit |
|---|---|
REST filter_operators | contains und is_null (is_null nur bei optionalen Attributen) |
REST is_sortable | false |
| GraphQL-Ausgabe | RecordRichText { html: String!, text: String! } |
| GraphQL-Filter | RichTextOperators mit _contains und _is_null |
GraphQL order_by | Nicht verfügbar |
| Suche | Über die Nur-Text-Projektion enthalten; Markup und Linkziele werden nicht indexiert |
contains vergleicht die Nur-Text-Projektion ohne Beachtung der Groß-/Kleinschreibung. Präfix-,
Suffix-, Gleichheits- und Ordnungsoperatoren liefern 422 filter-operator-not-applicable, eine
Sortierung liefert 422 unsupported-sort-field.
Umstellung von Text
Attributtypen sind unveränderlich. Um ein bestehendes text-Attribut auf formatierten Text
umzustellen, legen Sie ein rich_text-Attribut an, kopieren jeden Wert und entfernen das alte
Attribut, sobald nichts mehr darauf zugreift. Das Schreiben eines reinen Strings in ein
rich_text-Attribut ist eine deterministische Umwandlung: Er wird zu einem Absatz und jeder
Zeilenumbruch zu einem <br>, es geht also nichts verloren. Die umgekehrte Richtung ist
verlustbehaftet: Verwenden Sie die Nur-Text-Projektion und rechnen Sie damit, dass Formatierungen
verschwinden.
Integrationsoberflächen
Webhook-Nutzdaten, MCP-Datensatzwerkzeuge und Workflow-Datensatzoperationen übertragen den
kanonischen HTML-String innerhalb von data, genau wie REST ihn zurückgibt. Konsumenten, die ihn
darstellen, müssen ihn mit derselben Positivliste erneut bereinigen; die Tourfold-Web-App tut das.