Working with Structured Text > Structured Text and Dast format

Structured Text content is stored as a JSON object consisting of two mandatory keys:

• document: the content, expressed as a unist tree;

• schema: a string that specifies the unist dialect used inside the document itself.

{
  "schema": "dast",
  "document": {
    "type": "root",
    "children": [...]
  }
}

Generally speaking, you want to set the schema key to the dast dialect (which stands for DatoCMS Abstract Syntax Tree), so that:

• you can take advantage of the default Structured Text editor that DatoCMS offers;

• you can reinforce a number of additional validations to ensure consistency within the document.

If you would like to to use a custom unist format rather than dast, please let us know!

DatoCMS Abstract Syntax Tree (dast) specification

The dast specification adheres to the Unified collective, which offers a large ecosystem of utilities to parse, transform, manipulate, convert, and serialize content of any kind.

Unified is implemented and used as foundation by several popular libraries, such as rehype (HTML parser), remark (Markdown parser) and the MDX project. All these different projects are able to integrate with each other due to the fact that, to describe the content they treat, they all use the same common JSON format called unist.

Just like HTML, a dast document is composed of nodes within nodes:

• Each node has a type attributed called type

• The top-level node in the dast specification must be of type root

• Most nodes have a children attribute to specify the nodes it contains

• The leaves of the tree are nodes of type span, which do not offer a children attribute but store the final text as a string in their value attribute

• The specs define exactly which attributes and children each node permits.

Let's look at an example:

1
{
2
  "type": "root",
3
  "children": [
4
    {
5
      "type": "heading",
6
      "level": 1,
7
      "children": [
8
        {
9
          "type": "span",
10
          "marks": [],
11
          "value": "This is a title!"
12
        }
13
      ]
14
    },
15
    {
16
      "type": "paragraph",
17
      "children": [
18
        {
19
          "type": "span",
20
          "value": "This is a "
21
        }
22
        {
23
          "type": "span",
24
          "marks": ["strong"],
25
          "value": "paragraph!"
26
        }
27
      ]
28
    },
29
    {
30
      "type": "list",
31
      "style": "bulleted",
32
      "children": [
33
        {
34
          "type": "listItem",
35
          {
36
            "type": "paragraph",
37
            "children": [
38
              {
39
                "type": "span",
40
                "value": "And this is a list!"
41
              }
42
            ]
43
          },
44
        }
45
      ]
46
    }
47
  ]
48
}

Working with dast documents

You can take advantage of several utilities to work with nodes in a dast document. For example, you can:

• compose and assemble a document with unist-builder;

• select nodes with a CSS-like syntax using unist-util-select;

• have a compact representation of the document via unist-util-inspect;

1
import u from 'unist-builder';
2
import inspect from 'unist-util-inspect';
3

4
const document =
5
  u('root', [
6
    u('heading', { level: 1}, [
7
      u('span', 'This is the title!')
8
    ]),
9
    u('paragraph', [
10
      u('span', 'And '),
11
      u('span', { marks: ['strong'] }, 'this'),
12
      u('span', ' is a paragraph!')
13
    ])
14
  ]);
15

16
console.log(inspect(document));
17

18
root[2]
19
├─0 heading[1]
20
│   │ level: 1
21
│   └─0 span "This is the title!"
22
└─1 paragraph[3]
23
    ├─0 span "And "
24
    ├─1 span "this"
25
    │     marks: ["strong"]
26
    └─2 span " is a paragraph!"

In addition to that, we built a set of specific tools to work with Structured Text and dast documents:

• datocms-html-to-structured-text to convert HTML/Markdown into Structured Text;

• datocms-structured-text-utils to validate a document for dast-compliance before submitting to the API, and to have JavaScript nodes definitions and Typescript types and type guards;

• datocms-structured-text-to-plain-text to render Structured Text as plain text;

• datocms-structured-text-to-html-string to render Structured Text as an HTML string;

• datocms-structured-text-to-dom-nodes to transform Structured Text into a list of DOM nodes;

• <StructuredText /> component if you need to render Structured Text in React;

• <datocms-structured-text /> component if you need to render Structured Text in Vue.

JSON Schema for dast

The latest dast format specification is always available at the following url:

https://site-api.datocms.com/docs/dast-schema.json

root

Every dast document MUST start with a root node.

It allows the following children nodes: paragraph, heading, list, code, blockquote, block and thematicBreak.

1
{
2
  "type": "root",
3
  "children": [
4
    {
5
      "type": "heading",
6
      "level": 1,
7
      "children": [
8
        {
9
          "type": "span",
10
          "value": "Title"
11
        }
12
      ]
13
    },
14
    {
15
      "type": "paragraph",
16
      "children": [
17
        {
18
          "type": "span",
19
          "value": "A simple paragraph!"
20
        }
21
      ]
22
    }
23
  ]
24
}

paragraph

A paragraph node represents a unit of textual content.

It allows the following children nodes: span, link, itemLink and inlineItem.

1
{
2
  "type": "paragraph",
3
  "children": [
4
    {
5
      "type": "span",
6
      "value": "A simple paragraph!"
7
    }
8
  ]
9
}

span

A span node represents a text node. It might optionally contain decorators called marks. It is worth mentioning that you can use the \n newline character to express line breaks.

It does not allow children nodes.

1
{
2
  "type": "span",
3
  "marks": ["highlight", "emphasis"],
4
  "value": "Some random text here, move on!"
5
}

link

A link node represents a normal hyperlink. It might optionally contain a number of additional custom information under the meta key. You can also link to DatoCMS records using the itemLink node.

It allows the following children nodes: span.

1
{
2
  "type": "link",
3
  "url": "https://www.datocms.com/",
4
  "meta": [
5
    { "id": "rel", "value": "nofollow" },
6
    { "id": "target", "value": "_blank" }
7
  ],
8
  "children": [
9
    {
10
      "type": "span",
11
      "value": "The best CMS in town"
12
    }
13
  ]
14
}

itemLink

An itemLink node is similar to a link node node, but instead of linking a portion of text to a URL, it links the document to another record present in the same DatoCMS project.

It might optionally contain a number of additional custom information under the meta key.

If you want to link to a DatoCMS record without having to specify some inner content, then please use the inlineItem node.

It allows the following children nodes: span.

1
{
2
  "type": "itemLink",
3
  "item": "38945648",
4
  "meta": [
5
    { "id": "rel", "value": "nofollow" },
6
    { "id": "target", "value": "_blank" }
7
  ],
8
  "children": [
9
    {
10
      "type": "span",
11
      "value": "Matteo Giaccone"
12
    }
13
  ]
14
}

inlineItem

An inlineItem, similarly to itemLink, links the document to another record but does not specify any inner content (children).

It can be used in situations where it is up to the frontend to decide how to present the record (ie. a widget, or an <a> tag pointing to the URL of the record with a text that is the title of the linked record).

It does not allow children nodes.

1
{
2
  "type": "inlineItem",
3
  "item": "74619345"
4
}

heading

An heading node represents a heading of a section. Using the level attribute you can control the rank of the heading.

It allows the following children nodes: span, link, itemLink and inlineItem.

1
{
2
  "type": "heading",
3
  "level": 2,
4
  "children": [
5
    {
6
      "type": "span",
7
      "value": "An h2 heading!"
8
    }
9
  ]
10
}

list

A list node represents a list of items. Unordered lists must have its style field set to bulleted, while ordered lists, instead, have its style field set to numbered.

It allows the following children nodes: listItem.

1
{
2
  "type": "list",
3
  "style": "bulleted",
4
  "children": [
5
    {
6
      "type": "listItem",
7
      "children": [
8
        {
9
          "type": "paragraph",
10
          "children": [
11
            {
12
              "type": "span",
13
              "value": "This is a list item!"
14
            }
15
          ]
16
        }
17
      ]
18
    }
19
  ]
20
}

listItem

A listItem node represents an item in a list.

It allows the following children nodes: paragraph and list.

1
{
2
  "type": "listItem",
3
  "children": [
4
    {
5
      "type": "paragraph",
6
      "children": [
7
        {
8
          "type": "span",
9
          "value": "This is a list item!"
10
        }
11
      ]
12
    }
13
  ]
14
}

code

A code node represents a block of preformatted text, such as computer code.

It does not allow children nodes.

1
{
2
  "type": "code",
3
  "language": "javascript",
4
  "highlight": [1],
5
  "code": "function greetings() {\n  console.log('Hi!');\n}"
6
}

blockquote

A blockquote node is a containter that represents text which is an extended quotation.

It allows the following children nodes: paragraph.

1
{
2
  "type": "blockquote",
3
  "attribution": "Oscar Wilde",
4
  "children": [
5
    {
6
      "type": "paragraph",
7
      "children": [
8
        {
9
          "type": "span",
10
          "value": "Be yourself; everyone else is taken."
11
        }
12
      ]
13
    }
14
  ]
15
}

block

Similarly to Modular Content fields, you can also embed block records into Structured Text. A block node stores a reference to a DatoCMS block record embedded inside the dast document.

This type of node can only be put as a direct child of the root node.

It does not allow children nodes.

1
{
2
  "type": "block",
3
  "item": "1238455312"
4
}

thematicBreak

A thematicBreak node represents a thematic break between paragraph-level elements: for example, a change of scene in a story, or a shift of topic within a section.

It does not allow children nodes.

1
{
2
  "type": "thematicBreak"
3
}