Atlassian Document Format

Purpose

Atlassian Document Format (ADF) is used to send messages. Canonically, Atlassian Document Format is represented as a JSON object, describing a tree of nodes where leafs may have a set of marks. Every document starts with a root doc node and have a "version" field equal to 1. The simplest document in ADF:

1
2
3
4
5
{
  "version": 1,
  "type": "doc",
  "content": []
}

JSON schema

A JSON schema which validates documents to ensure they conform to ADF. The latest version can always be found at: http://go.atlassian.com/adf-json-schema.

Nodes

Documents are composed of nodes, in much the same way that HTML documents are. A document is "ordered", in that there's a single sequential path through it. This means that traversing a document and concatenating the nodes together will yield content in the correct order.

Nodes come in two kinds: block and inline. Block nodes are permitted to have a content property, containing an array of nodes. An example of a block node is a paragraph containing text nodes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "Some text in a paragraph"
        }
      ]
    }
  ]
}

"top-level blocks" group nodes

What these nodes have in common is that they can all exist at the same level. For example where-ever a paragraph can occur, so too can a blockquote.

What these nodes don't have in common is their content. For example a bulletList can only contain listItem, but a rule cannot contain anything.

"inlines" group nodes

These nodes can exist at the same level.

No group

Marks

A mark can annotate inline nodes. It has type and optionally an attrs describing attributes. Marks are applied to inline nodes (via the marks property). Different nodes support different sets of marks (e.g. emoji does not support any marks, but text supports many).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "marks": [
            {
              "type": "strong"
            }
          ],
          "text": "Some strong text"
        }
      ]
    }
  ]
}

Type

Just like nodes, marks have a "type". A strong mark:

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

Attributes

Just like nodes, marks can have attributes via the attrs property. A link mark with a href attribute:

1
2
3
4
5
6
{
  "type": "link",
  "attrs": {
    "href": "http://google.com"
  }
}