Document model
Blocks, text spans, raw text, attributes, IDs and marks, the JSON shape of a GoTipe document and how it is validated.
A GoTipe document is a tree of blocks. Each block has a type, a stable ID, attributes, content and child blocks. Text inside a block is a list of spans with marks; there are no inline nodes. The same JSON goes into createEditor, comes out of editor.getJSON() and is read by both engines, the Markdown codec and the exporters.
A document
{
"version": 1,
"blocks": [
{
"id": "title",
"type": "heading",
"attrs": { "level": 1 },
"content": [{ "text": "Launch plan", "marks": [] }],
"children": []
},
{
"id": "intro",
"type": "paragraph",
"attrs": {},
"content": [
{ "text": "Ship ", "marks": [] },
{ "text": "on Friday", "marks": [{ "type": "bold", "attrs": {} }] },
{ "text": ". Notes are in the ", "marks": [] },
{
"text": "tracker",
"marks": [{ "type": "link", "attrs": { "href": "https://example.com/tracker" } }]
},
{ "text": ".\nOne more line.", "marks": [] }
],
"children": []
},
{
"id": "tasks",
"type": "todoList",
"attrs": {},
"content": null,
"children": [
{
"id": "task-1",
"type": "todoItem",
"attrs": { "checked": true },
"content": [{ "text": "Write the docs", "marks": [] }],
"children": []
}
]
},
{
"id": "snippet",
"type": "codeBlock",
"attrs": { "language": "ts" },
"content": "await editor.focus();",
"children": []
},
{ "id": "rule", "type": "divider", "attrs": {}, "content": null, "children": [] }
]
}The \n in the paragraph is a hard line break. The code block holds a plain string; the list and the divider have no text of their own.
Shape
| Field | Type | Description |
|---|---|---|
Document. |
number |
Non-negative integer, 1 when omitted. Grows by one with every applied step on both engines; see engines. |
Document.blocks |
Block[] |
Top-level blocks in order. |
Block.id |
string |
Non-empty and unique in the document. |
Block.type |
string |
A node type of the schema, such as paragraph. |
Block.attrs |
Record< |
Attributes declared by the node type. |
Block.content |
Text |
Rich text, raw text or nothing, depending on the type. |
Block.children |
Block[] |
Nested blocks: list items, table rows, a toggle's body. |
TextSpan.text |
string |
Text; \n is a hard line break. |
TextSpan.marks |
Mark[] |
Formatting of the whole span. |
Mark.type |
string |
Mark name, such as bold or link. |
Mark.attrs |
Record< |
Mark attributes, such as { href }. |
On input you may omit attrs, children and mark attrs (they become {} and []), content (it becomes null) and version. getJSON() always returns every field. The types Document, Block, TextSpan, Mark and AttrValue are exported from @gotipe/core.
Content kinds
The node type decides what content holds:
| Kind | content |
Built-in types |
|---|---|---|
richText |
TextSpan[] |
paragraph, heading, blockquote, callout, toggle, listItem, todoItem, tableCell, tableHeader |
rawText |
string |
codeBlock, math |
empty |
null |
divider, image, file, embed, and the containers bulletList, orderedList, todoList, table, tableRow, columns, column |
Rich and raw text blocks also accept null for empty text; it becomes [] or "" on the first edit. Raw text has no marks, and \n separates its lines.
IDs
Every block has an ID, including list items and table cells. Comments, suggestions, selections and collaboration refer to blocks by ID, so keep them stable. Commands keep a block's ID when they change its type or move it into a list. New blocks get IDs from createId() of @gotipe/core, a UUID v4; the Markdown parser creates UUID v7 IDs and can reuse the IDs of a previous version of the file.
createId() takes crypto.randomUUID() where the page has it and makes the same UUID from crypto.getRandomValues() where it does not: randomUUID exists only in a secure context (HTTPS or localhost), and every package of the library uses createId(), so editors, comments, suggestions, versions and AI work on a page served over plain HTTP too. Use it for the IDs of blocks you build.
When you build a document yourself, choose the IDs. Duplicate or empty IDs are rejected, and an insertBlock step can't reuse an ID that is already in the document.
Attributes
Attribute values are JSON: strings, finite numbers, booleans, null, arrays and plain objects, nested up to 64 levels. Every attribute must be declared by the node or mark type with an AttrSpec. Undeclared attributes are rejected, never dropped silently.
required: trueattributes must be present and notnull. Others may be absent ornull.defaultis not written into the document. A block inserted without an attribute doesn't have it, and each renderer uses its own fallback. Pass the values you rely on.- Every node type also accepts five attributes that the core adds:
style,marker,delimiterandbreaks(strings) andspread(boolean). The Markdown codec uses them to keep the source syntax, such as*bullets or1)numbering;breaksis only kept for older documents and no longer read or written.
Marks
A mark formats a span: bold, italic, link with { href }, highlight with { color }. A mark type must be declared by an extension, and the block type must allow it (marksAllowed). Code blocks allow none.
When the engine edits a block, it merges neighbouring spans with equal marks and removes empty spans. Adding a mark keeps text that already has a mark of that type unchanged; to change a link target, remove the link and add it again in the same transaction.
Nesting
Only node types with topLevel: true may appear in Document.blocks; a listItem lives only inside a list. A block may have children only if its type allows them, and childTypes limits which types:
| Parent | Allowed children |
|---|---|
bulletList, orderedList |
listItem |
todoList |
todoItem |
listItem, todoItem, callout |
any block, such as a nested list |
blockquote |
paragraph, heading |
toggle |
paragraph, heading, bulletList, orderedList, codeBlock |
table → tableRow |
tableRow → tableCell, tableHeader |
columns → column |
column → paragraph, heading, bulletList, orderedList, codeBlock, image |
Each type is described in extensions.
Validation
createEditor, setContent and every transaction check the whole result against the schema and throw VALIDATION_ERROR when it doesn't fit; nothing is changed. To test a document first, call editor.validate() with the document object: a string is not read and returns false, so parse JSON yourself. For a message that names the problem in the document's shape, use decodeDocument(); it checks shape and IDs, not the schema.
import { createEditor, decodeDocument, GoTipeError } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
const editor = await createEditor({ extensions: [DefaultPreset], engine: "js" });
const saved: object | null = JSON.parse(localStorage.getItem("doc") ?? "null");
if (saved && editor.validate(saved)) {
editor.setContent(saved);
} else {
try {
decodeDocument(saved);
console.warn("The document uses types or attributes this editor doesn't have");
} catch (error) {
if (error instanceof GoTipeError) console.warn(error.message); // e.g. "Duplicate block ID: intro"
}
}An editor created with extensions: [] has no schema: it checks only the shape, IDs and JSON values, and accepts any block type and attribute. Documents nested deeper than 64 levels or with more than 100,000 blocks are rejected.
Limitations
There are no inline nodes. Everything inside a block is text with marks, so a mention chip, an inline image or an inline formula can't be an object inside a paragraph. Use a block (image, math, embed) or a mark with attributes, as links do. The Markdown codec keeps inline syntax it can't edit, such as inline HTML, as text with an mdRaw mark.
Marks keep the order in which they were added; a mark that replaces one of its type takes that mark's place. A mark type's rank is stored in the schema but not used yet. Its exclusiveGroup is applied: adding superscript removes subscript from that text.
Related
- Transactions: how a document changes.
- Content formats: JSON, HTML, Markdown and text.
- Extensions: declare your own block and mark types.