For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 type you don't know, skip it. If it has children, you can show those instead.

  • If list_type has a value you don't know, treat the list as unordered. If an align value 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?