Rich text
The rich text document Vantage uses for product descriptions: its node types, fields and the rules for parsing it so new node types never break you.
From API version 2026-10-29, a product's description is a rich text document rather than a string. It is a JSON tree with a node for every Markdown construct: CommonMark (without raw HTML), plus GitHub Flavored Markdown tables, strikethrough and task lists. You get structure you can walk, rather than Markdown or HTML to parse.
Versions before 2026-10-29 serve the same description as plain text.
Example
{
"type": "root",
"children": [
{
"type": "heading",
"level": 2,
"children": [
{ "type": "text", "value": "What it measures", "bold": false, "italic": false, "strikethrough": false, "code": false }
]
},
{
"type": "paragraph",
"children": [
{ "type": "text", "value": "17 biomarkers", "bold": true, "italic": false, "strikethrough": false, "code": false },
{ "type": "text", "value": " from one finger-prick. ", "bold": false, "italic": false, "strikethrough": false, "code": false },
{
"type": "link",
"url": "https://example.com/biomarkers",
"title": null,
"children": [
{ "type": "text", "value": "See the list", "bold": false, "italic": false, "strikethrough": false, "code": false }
]
}
]
},
{
"type": "list",
"list_type": "unordered",
"start": null,
"children": [
{
"type": "list_item",
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{ "type": "text", "value": "Cholesterol", "bold": false, "italic": false, "strikethrough": false, "code": false }
]
}
]
}
]
}
]
}A product with no description has { "type": "root", "children": [] }.
The model
Every node has a type. Every field a node type lists below is always present. A field with no value is null, never omitted.
The document is a root node whose children are blocks. Blocks hold either more blocks or inline nodes.
Blocks
type
Fields
Notes
paragraph
children: inline nodes
Empty children is an empty paragraph.
heading
level: 1 to 6
children: inline nodes
1 is the most prominent, as Markdown's # to ######.
blockquote
children: blocks
list
list_type: ordered or unordered
start: integer or null
children: list_item nodes
start is the first item's number in an ordered list, and null in an unordered one. A list has at least one item.
list_item
checked: boolean or null
children: blocks
checked is set for a task list item, and null otherwise. A nested list is a list among the item's blocks.
code_block
language: string or null
value: string
value is the code verbatim.
thematic_break
none
A horizontal rule.
table
align: one entry per column: left, center, right or null
children: table_row nodes
The first row is the header row. Every row has one cell per column.
table_row
header: boolean
children: table_cell nodes
header is true on the first row only.
table_cell
children: inline nodes
Inline nodes
type
Fields
Notes
text
value: string
bold, italic, strikethrough, code: booleans
A run of characters sharing one set of styles. code is inline code. A \n in value is a soft line break. value is never empty.
link
url: string
title: string or null
children: inline nodes
url is an https, http or mailto URL. A link never contains another link.
image
url: string
alt: string
title: string or null
url is an https URL. alt is empty for a decorative image.
line_break
none
A hard line break.
Handling future additions
We'll add to this format over time, for example new node types such as block-level images, or new text styles. These additions don't come with a new API version, so make sure your code copes with things it hasn't seen before:
If a node has a field you don't know, ignore it.
If you come across a node
typeyou don't know, skip it. If it haschildren, you can show those instead.If
list_typehas a value you don't know, treat the list as unordered. If analignvalue is unknown, use the default alignment.
Changes that could break existing code, such as removing or renaming a field or node type, only happen in a new API version. See Versioning.
This TypeScript example turns a description into plain text, skipping anything it doesn't recognise:
The full schema of every node is in the API reference.
Last updated
Was this helpful?