Block Editor JSON Schema

Last Updated: Jun 17, 2024
documentation for the dotCMS Content Management System

The Block Editor field, and all the content created within it, is stored as JSON data. For example, if your Block Editor content consisted of the message “Hello World” in a single paragraph block, its field object would look like this:

{
  "type": "doc",
  "attrs":
    {
      "charCount": 11,
      "wordCount": 2,
      "readingTime": 1
    },
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "marks": [
            {
              "type": "bold"
            }
          ],
          "text": "Hello"
        },
        {
          "type": "text",
          "text": " World"
        }
      ]
    }
  ]
}

Understanding the JSON schema that yielded this example can be useful for validation, headless operation, and still other applications.

Block Editor Objects

Block objects have a few core properties. Each block possesses a type, at the very least, but also usually one or more of the others on this table:

PropertyValue
typeA string consisting of the name of the block (all blocks possess this property)
attrsAn object containing properties that define the block's presentation
contentAn array of objects expressing the block's user-defined content
marksAn array of objects containing formatting instructions for text content (only text objects possess this property)
textA content string (only text objects possess this property)

Most blocks, for example, have both attrs (attributes) and content.

The content property may contain in its array additional nested block objects, objects of the special text type, or countless possible combinations thereof.

Any property without a distinct value may be safely omitted. For example, a paragraph block left blank will not possess a content property, and unformatted text will not have marks.

Document

A Block Editor Field always begins with an object whose type is doc, representing the whole field's content.

The associated attrs consist of an object with three properties. All three correspond to the field's count bar feature, and all three take integers for their value:

PropertyValue
charCountThe number of characters in the field's text content
wordCountThe number of words in the field's text content
readingTimeAn estimate of the time needed to read the content

The content property of the document object holds all of the field's block objects in sequence.

Text

An object with type equal to text specifies a section of user-composed text. Instead of attrs or content, Text objects possess two unique properties called marks and text, which function in an analogous fashion — the first contains objects that define formatting, and the second contains a string of text content.

The marks property accepts an array of one or more simple objects, each containing only a type property with one of the following values:

TypeResult
boldsample text
italicsample text
underlinesample text
strikesample text
superscriptsamplesuperscripttext
subscriptsamplesubscripttext

A text object using several of these might appear as follows:

{
    "type": "text",
    "marks": [
        {"type":"underline"},
        {"type":"bold"},
        {"type":"italic"},
        {"type":"strike"}
    ],
    "text":"Hello World!"
}

And would render as:

Hello World!

Paragraph

Blocks with the type paragraph are the simplest block, and also the Block Editor's default.

A paragraph block's only attrs property is textAlign, which corresponds to the CSS property of the same name. The paragraph block uses text objects in its content array.

{
    "type": "paragraph",
    "attrs": {
        "textAlign": "left"
    },
    "content": [
        {
            "type": "text",
            "text": "this is a paragraph block"
        }
    ]
}

Headings

The heading type uses text content, as the paragraph block, but exposes two attrs properties: textAlign and level. The integer value of level specifies the corresponding HTML heading — e.g., 2 is the equivalent of <h2>.

{
    "type": "heading",
    "attrs": {
        "textAlign": "left",
        "level": 2
    },
    "content": [
        {
            "type": "text",
            "text": "this is a heading 2 block"
        }
    ]
}

Lists

There are three type values associated with list blocks.

TypeDescription
orderedListAn ordered list, similar to <ol>
bulletListAn unordered list, similar to <ul>
listItemAn individual entry in either type of list, similar to <li>

All three block types have access to the textAlign property in the attributes object; the ordered list also has the start property, which takes as its value an integer indicating the first listed value.

Ordered and bullet lists use an array of list items as content, while list items may use other kinds of blocks, in turn, for its own content — including paragraphs, or even ordered or bullet list blocks, allowing nested lists.

{
    "type": "orderedList",
    "attrs": {
        "start": 1,
        "textAlign": "left"
    },
    "content": [
        {
            "type": "listItem",
            "attrs": {
                "textAlign": "left"
            },
            "content": [
                {
                    "type": "paragraph",
                    "attrs": {
                        "textAlign": "left"
                    },
                    "content": [
                        {
                            "type": "text",
                            "text": "behold! an ordered list!"
                        }
                    ]
                }
            ]
        }
    ]
|

Block Quotes

The blockquote-type object functions similarly to the HTML tag of the same name. It can use the textAlign attribute property, and typically contains a paragraph block as content.

{
    "type": "blockquote",
    "attrs": {
        "textAlign": "left"
    },
    "content": [
        {
            "type": "paragraph",
            "attrs": {
                "textAlign": "left"
            },
            "content": [
                {
                    "type": "text",
                    "text": "This is the line we have chosen as our quote."
                }
            ]
        }
    ]
}

Code

The codeBlock object exposes the attribute property language, which takes as value an integer corresponding to a dotCMS language ID. Its value is typically a plain and unformatted text object. Because of the difference in the interface's handling, special characters like newlines can be added more easily; in a code block, use Shift+Enter to proceed to the next block, as you would with just Enter on a paragraph block.

{
    "type": "codeBlock",
    "attrs": {
        "language": null
    },
    "content": [
        {
            "type": "text",
            "text": "code block here\n"
        }
    ]
}

Table Blocks

Tables encompass four distinct type values.

TypeDescription
tableThe parent object, as with <table>
tableRowA table row, similar to <tr>
tableHeaderA table heading cell, as with <th>, generally within the first row
tableCellAn individual cell within a row, similar to <td>

Tables and table rows can invoke no attribute properties. However, both headers and cells have three attr properties of note:

PropertyDescription
colspanThe number of columns the element is intended to span
rowspanThe number of rows the element is intended to span
colwidthDefines the width of the column in pixels, percent, etc.

Similar to the HTML table structure, a table takes as its content an array of table rows, and a table row uses an array of either table headers or table cells.

{
    "type": "table",
    "content": [
        {
            "type": "tableRow",
            "content": [
                {
                    "type": "tableHeader",
                    "attrs": {
                        "colspan": 1,
                        "rowspan": 1,
                        "colwidth": null
                    },
                    "content": [
                        {
                            "type": "paragraph",
                            "attrs": {
                                "textAlign": "left"
                            },
                            "content": [
                                {
                                    "type": "text",
                                    "text": "table heading cell 1"
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "type": "tableRow",
            "content": [
                {
                    "type": "tableCell",
                    "attrs": {
                        "colspan": 1,
                        "rowspan": 1,
                        "colwidth": null
                    },
                    "content": [
                        {
                            "type": "paragraph",
                            "attrs": {
                                "textAlign": "left"
                            },
                            "content": [
                                {
                                    "type": "text",
                                    "text": "row 1 cell 1"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Images

Image blocks have a type property with the value dotImage, and the following attribute properties.

AttributeData TypeDescription
textAlignstringText-align CSS property assigned by default to an enclosing div around the image
srcstringThe address of the image
altstringAlt text for the image
titlestringImage tag's title attribute
hrefstringAddress the image should link to, if activated
dataobjectContains the full set of metadata associated with the image's dotAsset, as though accessed via the content object

Image blocks — along with video blocks and contentlet blocks — distinguish themselves by having no content property; the content in this case is a file referenced through its attributes.

{
    "type": "dotImage",
    "attrs": {
        "textAlign": "left",
        "src": "/dA/1acf2998-b36d-4dd7-bb73-06ce2531ee09/asset/shark-feeding.jpeg",
        "alt": "shark-feeding.jpeg",
        "title": "shark-feeding.jpeg",
        "href": null,
        "data": {
            "hostName": "demo.dotcms.com",
            "modDate": "2022-04-12 20:18:32.787",
            "extension": "jpeg",
            "publishDate": "2022-04-12 20:18:32.787",
            "assetContentAsset": "1acf2998-b36d-4dd7-bb73-06ce2531ee09/asset",
            "mimeType": "image/jpeg",
            "title": "shark-feeding.jpeg",
            "type": "dotasset",
            "baseType": "DOTASSET",
            "inode": "7f71124d-8dd8-4081-b6a0-eb036464e940",
            "archived": false,
            "path": "/content.7f71124d-8dd8-4081-b6a0-eb036464e940",
            "host": "48190c8c-42c4-46af-8d1a-0cd5db894797",
            "working": true,
            "variantId": "DEFAULT",
            "locked": false,
            "stInode": "657897dfb36ef211ebfb4128de818787",
            "contentType": "PDF",
            "live": true,
            "owner": "dotcms.org.1",
            "identifier": "1acf2998-b36d-4dd7-bb73-06ce2531ee09",
            "isContentlet": true,
            "languageId": 1,
            "__icon__": "jpegIcon",
            "statusIcons": "<span class='greyDotIcon' style='opacity:.4'><\/span><span class='liveIcon'><\/span>",
            "url": "/content.7f71124d-8dd8-4081-b6a0-eb036464e940",
            "titleImage": "asset",
            "modUserName": "Admin User",
            "hasLiveVersion": true,
            "folder": "SYSTEM_FOLDER",
            "size": 98885,
            "hasTitleImage": true,
            "sortOrder": 0,
            "modUser": "dotcms.org.1",
            "assetVersion": "/dA/7f71124d-8dd8-4081-b6a0-eb036464e940/asset/shark-feeding.jpeg",
            "name": "shark-feeding.jpeg",
            "assetMetaData": {
                "modDate": 1685620932314,
                "sha256": "03fc29afd486f484b22d5b19408d61bde01314d5164f36f02bacb0d140780065",
                "length": 98885,
                "title": "shark-feeding.jpeg",
                "version": 20220201,
                "isImage": true,
                "fileSize": 98885,
                "name": "shark-feeding.jpeg",
                "width": 780,
                "contentType": "image/jpeg",
                "height": 413
            },
            "asset": "/dA/1acf2998-b36d-4dd7-bb73-06ce2531ee09/asset/shark-feeding.jpeg",
            "contentTypeIcon": "picture_as_pdf",
            "language": "en-US"
        }
    }
}

Videos

There are two block types that support video: dotVideo and youtube.

As with image blocks, above, neither of these two block types has a content property; both refer to file content via their attributes.

dotVideo Block

The dotVideo Block has six attribute properties of note.

AttributeData TypeDescription
srcstringThe address of the video
mimeTypestringThe MIME type of the file
widthintegerVideo width in pixels
heightintegerVideo height in pixels
orientationstringSpecify horizontal or vertical
dataobjectContains the full set of metadata associated with the video's dotAsset, as though accessed via the content object

This block is ideal for uploading videos to your site, or making use of videos already stored as dotAssets.

{
    "type": "dotVideo",
    "attrs": {
        "src": "/dA/3f6ba3f29edc30313a922179fa43acd5/asset/sample.mp4",
        "mimeType": "application/mp4",
        "width": 3840,
        "height": 2160,
        "orientation": "horizontal",
        "data": {
            "AUTO_ASSIGN_WORKFLOW": false,
            "__icon__": "mp4Icon",
            "archived": false,
            "asset": "/dA/3f6ba3f29edc30313a922179fa43acd5/asset/sample.mp4",
            "assetContentAsset": "3f6ba3f29edc30313a922179fa43acd5/asset",
            "assetMetaData": {
                "contentType": "application/mp4",
                "fileSize": 158490586,
                "height": 2160,
                "isImage": false,
                "length": 158490586,
                "modDate": 1680287148719,
                "name": "sample.mp4",
                "sha256": "52572f71395b62a12dd1527f3fea2ae183ce5f67fdb0bcaf7d09b354a14dbd00",
                "title": "sample.mp4",
                "version": 20220201,
                "width": 3840
            },
            "assetVersion": "/dA/412ba697-e4cf-4ec7-90ac-2cbdd878a1ea/asset/sample.mp4",
            "baseType": "DOTASSET",
            "contentType": "dotAsset",
            "extension": "mp4",
            "folder": "SYSTEM_FOLDER",
            "hasLiveVersion": true,
            "hasTitleImage": false,
            "host": "SYSTEM_HOST",
            "hostName": "System Host",
            "identifier": "3f6ba3f29edc30313a922179fa43acd5",
            "inode": "412ba697-e4cf-4ec7-90ac-2cbdd878a1ea",
            "isContentlet": true,
            "languageId": 1,
            "live": true,
            "locked": false,
            "mimeType": "video/mp4",
            "modDate": 1680287148926,
            "modUser": "dotcms.org.1",
            "modUserName": "Admin User",
            "name": "sample.mp4",
            "owner": "dotcms.org.1",
            "path": "/content.412ba697-e4cf-4ec7-90ac-2cbdd878a1ea",
            "publishDate": 1680287148926,
            "size": 158490586,
            "sortOrder": 0,
            "stInode": "f2d8a1c7-2b77-2081-bcf1-b5348988c08d",
            "statusIcons": "<span class='greyDotIcon' style='opacity:.4'></span><span class='liveIcon'></span>",
            "title": "sample.mp4",
            "titleImage": "TITLE_IMAGE_NOT_FOUND",
            "type": "dotasset",
            "url": "/content.412ba697-e4cf-4ec7-90ac-2cbdd878a1ea",
            "variantId": "DEFAULT",
            "working": true
        }
    }
}

YouTube Block

The YouTube block, designed to simplify embedding videos from YouTube, has four attribute properties.

AttributeData TypeDescription
srcstringThe address of the linked video
startintegerThe starting position of the video in seconds
widthintegerVideo width in pixels
heightintegerVideo height in pixels

And indeed, its data consists of little else:

{
    "type": "youtube",
    "attrs": {
        "src": "https://www.youtube.com/watch?v=u5Lx1UZfCK8",
        "start": 0,
        "width": 400,
        "height": 300
    }
}

Contentlet Blocks

The Contentlet block, which uses the type property value dotContent, allows you to embed structured content developed in dotCMS into the Block Editor. It has only one attribute property: data. Its value is an object that includes content object metadata.

{
    "type": "dotContent",
    "attrs": {
        "data": {
            "hostName": "demo.dotcms.com",
            "modDate": "2020-09-02 16:45:53.787",
            "publishDate": "2020-09-02 16:45:53.787",
            "title": "French Alps",
            "body": "<h2>SKIING IN THE FRENCH ALPS<\/h2>\n<p>Noted for being a significant source of skiing, the French Alps are...<\/p>",
            "baseType": "CONTENT",
            "inode": "919d6bf4-a712-43cf-9cc2-d69d384d8392",
            "archived": false,
            "host": "48190c8c-42c4-46af-8d1a-0cd5db894797",
            "working": true,
            "variantId": "DEFAULT",
            "locked": false,
            "stInode": "2a3e91e4-fbbf-4876-8c5b-2233c1739b05",
            "contentType": "webPageContent",
            "live": true,
            "owner": "dotcms.org.1",
            "identifier": "0e773815-26da-4098-9343-214fb301bafd",
            "languageId": 1,
            "url": "/content.ef67af58-c36b-4127-afb6-03928ad41673",
            "titleImage": "TITLE_IMAGE_NOT_FOUND",
            "modUserName": "Admin User",
            "hasLiveVersion": true,
            "folder": "SYSTEM_FOLDER",
            "hasTitleImage": false,
            "sortOrder": 0,
            "modUser": "dotcms.org.1",
            "__icon__": "contentIcon",
            "contentTypeIcon": "wysiwyg",
            "language": "en-US"
        }
    }
}

Horizontal Line

The horizontal line has only a type property.

{
    "type": "horizontalRule"
}

On this page

×

We Dig Feedback

Selected excerpt:

×