Author Ricos Rich Content

Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON. The same structure is embedded by many products: a Blog post's draftPost.richContent, a Store product's rich description, an Events description, and CMS rich-text fields all expect a Ricos document. This recipe is the authoring reference for that node tree: the valid shape of each node, how nodes nest, and how to format text. It is intentionally product-agnostic — the consuming API decides where the document goes; this recipe governs what a valid document looks like.

Universal rules for every node

• type is always a bare string — "type": "PARAGRAPH", never an object like "type": { "type": "PARAGRAPH" }. An object-valued type may pass a shallow validation but renders as a broken/uneditable block.
• Every node carries a type, an optional id, and (for container nodes) a nodes array of children. Node ids are optional when authoring for a create request — the API generates them; the examples below omit id for brevity.
• TEXT is a leaf. A TEXT node only ever lives inside a PARAGRAPH, HEADING, or CODE_BLOCK. It must never sit directly in the root nodes array or inside a LIST_ITEM, BLOCKQUOTE, or TABLE_CELL — those must contain a PARAGRAPH (or HEADING) that then contains the TEXT. See Nesting rules.
• Failing to wrap TEXT correctly produces the parse error "Expected a paragraph node but found TEXT".
• Block nodes do not get automatic vertical gap when rendered — insert empty PARAGRAPH spacer nodes between sibling blocks when you need breathing room. See Vertical spacing between blocks.

Required plugin shape checklist

Use this checklist while composing and again before returning JSON. Treat every path below as required for the described request:

• Button CTA: emit a root-level BUTTON, never a PARAGRAPH with an inline LINK. Include buttonData.type: "LINK", buttonData.text, buttonData.link.url, buttonData.link.target, and buttonData.containerData.
• Hosted audio: emit { "type": "AUDIO", "nodes": [], "audioData": { ... } }. The empty nodes array is on the AUDIO node beside audioData — never inside audioData. Include audioData.containerData.alignment, width, and textWrap, plus audioData.audio.src.id.
• Video with thumbnail: place videoData.video.src and videoData.video.duration inside video; place videoData.thumbnail beside video, with src.id, width, and height.
• Gallery: emit one root-level GALLERY. Put images in galleryData.items, not as child IMAGE nodes. Every item uses image.media with src, width, and height; include galleryData.options.layout.type and numberOfColumns.
• Collapsible FAQ: use COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT. Every PARAGRAPH includes paragraphData, and every item includes both title and body.
• HTML embed: emit a root-level HTML with htmlData.source, either url or html, and htmlData.containerData.width, height, and alignment.

Vertical spacing between blocks

The renderer does not add margin between stacked block nodes. Adjacent paragraphs, headings, images, videos, tables, collapsible lists, buttons, galleries, and other blocks will sit flush against each other unless you separate them explicitly.

Use an empty PARAGRAPH as a spacer — a paragraph with no nodes (no TEXT children):

Place spacer paragraphs at the root nodes level (or inside a CARD page) wherever layout needs vertical rhythm:

• After headings — before the following body copy or media block.
• Between paragraphs — when two text blocks should not run together visually.
• After block plugins — images, videos, audio, galleries, tables, collapsible lists, HTML embeds, buttons, dividers, and lists often need a spacer before the next distinct section (not between every adjacent block in a minimal snippet the user enumerated).
• After blockquotes — only when the following block is a separate section; skip the spacer when the user asked for a blockquote immediately followed by a specific paragraph in one compact output.
• Before major sections — optional extra spacer when transitioning from one content group to another.

When the user requests only specific nodes in one JSON output (e.g. "a blockquote and then a paragraph"), include exactly those nodes — do not add spacer paragraphs they did not ask for.

Do not rely on \n inside textData.text for spacing — that does not create a real line break between blocks. Do not expect paragraphData margins or containerData alone to separate unrelated sibling nodes; the empty paragraph is the supported spacing mechanism.

Example — spacer after an image and before a table:

Block node shapes

PARAGRAPH — the base text container. An empty paragraph — { "type": "PARAGRAPH" } — is the vertical spacer between block nodes (the renderer adds no gap on its own). See Vertical spacing between blocks. paragraphData.textStyle.textAlignment accepts AUTO·LEFT·CENTER·RIGHT·JUSTIFY:

HEADING — same TEXT-in-container shape as PARAGRAPH, with the level (1–6) in headingData:

BULLETED_LIST / ORDERED_LIST — nesting is LIST → LIST_ITEM → PARAGRAPH → TEXT. Ordered lists use orderedListData in place of bulletedListData:

BLOCKQUOTE — wraps a PARAGRAPH (never a bare TEXT):

DIVIDER — a standalone horizontal rule (no children). lineStyle: SINGLE·DOUBLE·DASHED·DOTTED; width: LARGE·MEDIUM·SMALL:

TABLE — nesting is TABLE → TABLE_ROW → TABLE_CELL → PARAGRAPH → TEXT. tableData.dimensions.colsWidthRatio sets relative column widths. Fill a header row or zebra-stripe body rows with tableCellData.cellStyle.backgroundColor (a hex string):

CODE_BLOCK — children are TEXT nodes (one per line, or \n-joined):

IMAGE — references a Wix Media id (upload/import the image first via Media Manager; a raw external URL will not render). Requires width and height. An optional CAPTION child holds a TEXT node:

BUTTON — a standalone call-to-action block. Not the same as an inline LINK decoration on TEXT (that is hyperlinked body copy; this is a labeled button control). buttonData.type is required on every BUTTON node — use "LINK" for URL navigation or "ACTION" for viewer click handlers (never omit type even when link is present). Two buttonData.type values:

• LINK — navigates to a URL when clicked (link.url, link.target: BLANK·SELF, optional link.rel).
• ACTION — triggers a viewer onClick handler (store the node in JSON; behavior is configured in the Ricos viewer, not in the document body).

AUDIO — uploaded audio via Wix Media src.id, or an embed variant whose audioData.html holds an iframe (SoundCloud, Spotify). Include audioData.containerData with alignment and width settings, and use an empty nodes: [] array because AUDIO has no child nodes. Optional fields include coverImage (src.id, width, height), name, authorName, and disableDownload:

VIDEO — Wix Media video.src.id, duration (seconds), and a thumbnail (src.id, width, height). YouTube and other embeds use the same VIDEO node shape with the appropriate media id:

GALLERY — multiple images in one block. Each items[] entry wraps image.media with src (id or url), width, and height. galleryData.options controls layout (layout.type: GRID, numberOfColumns, orientation; item.ratio, item.crop; thumbnails.placement):

COLLAPSIBLE_LIST — FAQ-style expandable items. Nesting is COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT (body cells may also contain other supported block plugins such as IMAGE or VIDEO). The item wrapper type is COLLAPSIBLE_ITEM — not COLLAPSIBLE_LIST_ITEM or other variants:

initialExpandedItems: NONE·FIRST·ALL. Set isQapageData: true in list metadata when the list should render as FAQ structured data in search results.

HTML — embeds external content in an iframe. Provide either url (page URL) or inline html markup; source is typically "HTML". Size via containerData.width / height (custom pixel strings or size):

Inline text formatting (decorations)

Apply formatting with the decorations array on a TEXT node. Each decoration is an object with a type and (for some types) a data field:

• Mixed formatting in one paragraph → split into multiple TEXT nodes (one per style run) inside the same PARAGRAPH. A single TEXT node carries one consistent set of decorations.
• Use a plain hex string in foreground for colors.
• No \n inside textData.text — one visual line is one node. Emit separate sibling PARAGRAPH/HEADING nodes for separate lines.

A complete worked example

Assemble the shapes above into one valid richContent document. This example exercises every common node type — heading, bulleted list, ordered list, blockquote, filled-header table, divider, code block, and a paragraph with mixed bold + link runs — all correctly nested. Copy its structure; replace the placeholder text with real content.

Note the mixed-run paragraph at the end: the linked words are their own TEXT node carrying BOLD + LINK, while the surrounding words are separate plain TEXT runs — that is how you apply formatting to part of a sentence.

Nesting rules

Self-audit before returning the document

All decidable from the JSON itself — check before handing the document to a consuming API:

1. Every type is a bare string — search for "type": {; there should be zero hits.
2. TEXT wrapping — no TEXT node sits directly in the root array, a LIST_ITEM, a BLOCKQUOTE, or a TABLE_CELL.
3. Container nesting is complete — LIST → LIST_ITEM → PARAGRAPH → TEXT and TABLE → TABLE_ROW → TABLE_CELL → PARAGRAPH → TEXT, no level skipped.
4. Headings carry a level (1–6) and nest logically (don't jump H2 → H4).
5. No \n inside textData.text — split into sibling nodes; mixed inline formatting → split into multiple TEXT runs.
6. Images use a Wix Media id (not a raw URL), with width, height, and meaningful altText.
7. Links — every LINK decoration has a valid url and target. Use a BUTTON block with buttonData.type: "LINK" for CTAs — not an inline LINK decoration styled to look like a button.
8. Buttons — every BUTTON includes buttonData.type (LINK requires link.url; ACTION has no URL). Omitting type is invalid even when link is set. LINK buttons and inline LINK decorations serve different purposes.
9. Media blocks — AUDIO has root-level nodes: [] and audioData.containerData; VIDEO keeps thumbnail beside video under videoData; every GALLERY item is under galleryData.items and carries image.media.src, width, and height.
10. Collapsible lists — every item has both _TITLE and _BODY, each wrapping content through PARAGRAPH → TEXT, and every PARAGRAPH has paragraphData.
11. HTML embeds — htmlData includes source, containerData.width, containerData.height, and either url or html (not both empty).
12. Spoiler — SPOILER is a decoration on TEXT (or containerData.spoiler on some block plugins in editor output); preserve it verbatim on edit.
13. Vertical spacing — stacked block nodes that should not appear cramped are separated by empty { "type": "PARAGRAPH" } spacers — especially after images, videos, tables, collapsible lists, galleries, buttons, and between consecutive paragraphs. Missing spacers produce a wall-of-blocks layout with no renderer-added margin.