Skip to content
Edytor
Esc
↑↓navigate↵open⌘Jpreview
On this page

Document model

The JSON shape of an Edytor document, with blocks, content, children, marks, inline blocks, ids and the rules the editor applies to them.

An Edytor document is a tree of blocks, stored as JSON. You pass it in as value, read it back from edytor.value or onChange, and store it wherever you like. This page describes that shape and what the editor guarantees about it.

The types

All four types are exported from edytor and edytor/crdt/edytor:

import type { SerializableContent } from 'edytor/crdt/edytor';

type JSONDoc = {
	data?: Record<string, SerializableContent>;
	children: JSONBlock[];
};

type JSONBlock = {
	type: string;
	id?: string;
	data?: Record<string, SerializableContent>;
	content?: (JSONText | JSONInlineBlock)[];
	children?: JSONBlock[];
};

type JSONText = {
	text: string;
	marks?: Record<string, SerializableContent>;
};

type JSONInlineBlock = {
	type: string;
	id?: string;
	data?: any;
};

SerializableContent is any JSON value: a string, number, boolean, null, or an array or object of them.

Blocks: content and children

A block has two separate slots:

  • content is the block’s own inline content: text runs and inline blocks, in order.
  • children are nested blocks. They render inside the parent (a toggle’s body, a list item’s sub-list) and can nest to any depth.
{
	"children": [
		{
			"type": "toggle",
			"content": [{ "text": "Details" }],
			"children": [
				{ "type": "paragraph", "content": [{ "text": "Hidden until opened." }] },
				{
					"type": "bulleted-list-item",
					"content": [{ "text": "Nested items work too" }],
					"children": [{ "type": "bulleted-list-item", "content": [{ "text": "Deeper" }] }]
				}
			]
		}
	]
}

type names a block kind registered by a plugin (paragraph, heading, …). data holds the kind’s settings: a heading’s { level: 'h2' }, a to-do’s { checked: true }. See Blocks for the kinds, nesting rules and default children, and Properties for reading, writing and syncing data.

The document itself (JSONDoc) is the root’s children, plus its own properties in data (absent when it has none). edytor.value and onChange give a JSONDoc too, the type the value prop takes, so a stored value opens as it is (the object also carries type: 'root').

Text and marks

Text is a list of runs. Each run carries the marks that apply to all of its characters:

{
	"type": "paragraph",
	"content": [
		{ "text": "Read the " },
		{ "text": "docs", "marks": { "bold": true, "link": { "href": "https://example.com" } } },
		{ "text": " first." }
	]
}

A mark is a key in marks. Simple marks use true. Valued marks carry their value: a link { href, target? }, a color or highlight a CSS color string. The rich text plugin defines bold, italic, underline, strike, code, link, superscript, subscript, color and highlight.

A mark renders only when a plugin defines it (otherwise its text shows unformatted). When several marks apply, they wrap each other in registration order, the first registered innermost.

Inline blocks

An inline block is a non-editable element inside the text: a mention, a footnote, an equation. It has a type, an optional id and optional data:

{
	"type": "paragraph",
	"content": [
		{ "text": "Ask " },
		{ "type": "mention", "data": { "userId": "u_42", "label": "Ada" } },
		{ "text": " about it." }
	]
}

The plugin that defines the inline block type renders it from data. In the editor it counts as one character of the block’s content: Backspace or Delete next to it removes it whole, and clicking it selects it.

Ids

Block and inline block ids are optional in the input:

  • Ids you provide are kept. Use them when something outside the document refers to a block (a link to #block-<id>, comments, analytics).
  • Missing ids are generated. For the initial value, they are derived from a hash of the value, so two clients that seed the same template get the same ids and merge into one document.
  • The output always has ids.
  • Ids must be unique. An insert that reuses a live block’s id is refused, and so is an id holding the character U+0000 (the document derives ids with it, below).
  • Two people can still create the same id at once, each in their own copy (two clients that add a block with id summary before they sync). When the copies meet, one block keeps the id: the one written by the larger client id, with its type, properties and place. The other one’s text is not lost: it shows at the end of the kept block’s text, where both can edit it. A block someone split off the other one keeps its text. Seeds are the exception: two different templates seeding one id keep one version (see deterministic seeds).
  • Pasted content always gets fresh ids, even when it was copied from the same document.

What you get back

The JSON the editor returns is normalized. Compare an input:

{ "type": "paragraph", "content": [{ "text": "Hel" }, { "text": "lo" }, { "text": "" }] }

with what edytor.value returns for it:

{ "type": "paragraph", "id": "b6si4c.0", "data": {}, "content": [{ "text": "Hello" }] }
  • id and data are always present (data is {} when empty). Inline blocks always carry id and data too.
  • Adjacent text runs with equal marks are merged into one run.
  • Empty text runs are dropped. An empty block has no content key.
  • children is omitted when a block has none.

Don’t compare stored JSON with edytor.value by deep equality right after loading it; compare after one round trip.

Invariants you can rely on

  • Unknown block types still render. A block whose type no plugin of the view defines (a peer running another plugin, a rolling deploy) renders as a plain block: its text and its children, with no roles and no custom markup. In development the view logs one warning per unknown type. Load documents with the same plugins that wrote them to render them as intended.
  • A block renders as text around inline blocks. However its content is stored, the editor shows it as a text segment first and last, and exactly one text segment between two inline blocks (possibly empty). That is where the caret goes before, between and after inline blocks.
  • An empty document shows one block. A new document with no children is seeded with one empty block of the default type (paragraph). A document that becomes empty later, for example when collaborators delete every block, shows a local empty paragraph that is only written once someone types in it.
  • Values are JSON. data and mark values cross the network and storage as JSON. Non-JSON values are coerced (a Date becomes a string, a Map becomes {}, undefined keys are dropped, NaN becomes null) and a warning is logged in development. Serialize richer values yourself.
  • Strings are well-formed. Unpaired UTF-16 surrogates in text, ids and data become U+FFFD, so every replica stores the same string.

Next

Was this page helpful?