Skip to content
Edit on GitHub

Document model

Blocks, text spans, raw text, attributes, IDs and marks, the JSON shape of a GoTipe document and how it is validated.

@gotipe/coreMIT

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

document.json
{
  "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.version 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<string, AttrValue> Attributes declared by the node type.
Block.content TextSpan[] | string | null 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<string, AttrValue> 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: true attributes must be present and not null. Others may be absent or null.
  • default is 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, delimiter and breaks (strings) and spread (boolean). The Markdown codec uses them to keep the source syntax, such as * bullets or 1) numbering; breaks is 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.

load.ts
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

Note:

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.

Note:

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.