> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/vantage-api/rich-text.md).

# 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`](https://docs.tryterra.co/vantage-api/changelog.md), 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

```json
{
  "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`        | <p><code>level</code>: 1 to 6<br><code>children</code>: inline nodes</p>                                                                                                                   | 1 is the most prominent, as Markdown's `#` to `######`.                                                              |
| `blockquote`     | `children`: blocks                                                                                                                                                                         |                                                                                                                      |
| `list`           | <p><code>list\_type</code>: <code>ordered</code> or <code>unordered</code><br><code>start</code>: integer or <code>null</code><br><code>children</code>: <code>list\_item</code> nodes</p> | `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`      | <p><code>checked</code>: boolean or <code>null</code><br><code>children</code>: blocks</p>                                                                                                 | `checked` is set for a task list item, and `null` otherwise. A nested list is a `list` among the item's blocks.      |
| `code_block`     | <p><code>language</code>: string or <code>null</code><br><code>value</code>: string</p>                                                                                                    | `value` is the code verbatim.                                                                                        |
| `thematic_break` | none                                                                                                                                                                                       | A horizontal rule.                                                                                                   |
| `table`          | <p><code>align</code>: one entry per column: <code>left</code>, <code>center</code>, <code>right</code> or <code>null</code><br><code>children</code>: <code>table\_row</code> nodes</p>   | The first row is the header row. Every row has one cell per column.                                                  |
| `table_row`      | <p><code>header</code>: boolean<br><code>children</code>: <code>table\_cell</code> nodes</p>                                                                                               | `header` is `true` on the first row only.                                                                            |
| `table_cell`     | `children`: inline nodes                                                                                                                                                                   |                                                                                                                      |

### Inline nodes

| `type`       | Fields                                                                                                                               | Notes                                                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `text`       | <p><code>value</code>: string<br><code>bold</code>, <code>italic</code>, <code>strikethrough</code>, <code>code</code>: booleans</p> | 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`       | <p><code>url</code>: string<br><code>title</code>: string or <code>null</code><br><code>children</code>: inline nodes</p>            | `url` is an `https`, `http` or `mailto` URL. A link never contains another link.                                                      |
| `image`      | <p><code>url</code>: string<br><code>alt</code>: string<br><code>title</code>: string or <code>null</code></p>                       | `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](https://docs.tryterra.co/vantage-api/versioning.md).

This TypeScript example turns a description into plain text, skipping anything it doesn't recognise:

```typescript
type Node = { type: string; children?: Node[]; [field: string]: unknown };

function plainText(node: Node): string {
  switch (node.type) {
    case "text":
      return node.value as string;
    case "line_break":
      return "\n";
    case "image":
      return node.alt as string;
    case "code_block":
      return node.value as string;
    case "root":
    case "blockquote":
      return (node.children ?? []).map(plainText).join("\n\n");
    case "list":
    case "list_item":
    case "table":
    case "table_row":
      return (node.children ?? []).map(plainText).join("\n");
    default:
      return (node.children ?? []).map(plainText).join("");
  }
}
```

The full schema of every node is in the [API reference](https://docs.tryterra.co/reference/vantage-api).
