Rate this page:

Atlassian Document Format

Purpose

The Atlassian Document Format (ADF) represents rich text stored in Atlassian products. For example, in Jira Cloud platform, the text in issue comments and in textarea custom fields is stored as ADF.

JSON schema

An Atlassian Document Format document is a JSON object. A JSON schema is available to validate documents. This JSON schema is found at http://go.atlassian.com/adf-json-schema.

Marks and nodes included in the JSON schema may not be valid in this implementation. Refer to this documentation for details of supported marks and nodes.

JSON structure

An ADF document is composed of a hierarchy of nodes. There are two categories of nodes: block and inline. Block nodes define the structural elements of the document such as headings, paragraphs, lists, and alike. Inline nodes contain the document content such as text and images. Some of these nodes can take marks that define text formatting or embellishment such as centered, bold, italics, and alike.

A document is ordered, that is, there's a single sequential path through it: traversing a document in sequence and concatenating the nodes yields content in the correct order.

For example:

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

Result in the text "Hello world".

Nodes

Nodes have the following common properties:

PropertyRequiredDescription
typeDefines the type of block node such as paragraph, table, and alike.
content✔ in block nodes, not applicable in inline nodesAn array contaning inline and block nodes that define the content of a section of the document.
version✔ in the root, otherwise not applicableDefines the version of ADF used in this representation.
marksDefines text decoration or formatting.
attrsFurther information defining attributes of the block such as the language represented in a block of code.

Block nodes

Block nodes can be subdivided into:

  • the root (doc) node.
  • top level nodes, nodes that can be placed directly below the root node.
  • child nodes, nodes that have to be the child of a higher-level mode.

Some top-level nodes can be used as child nodes. For example, the paragraph node can be used at the top level or embedded within a list or table.

Root block node

Every document starts with a root doc node. This node contains the version and contentproperties. The simplest document in ADF is this root node with no content:

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

Top-level block nodes

The top-level block nodes include:

Child block nodes

The child block nodes include:

Inline nodes

The inline nodes include:

Marks

Mark have the following properties:

PropertyRequiredDescription
typeDefines the type of mark such as code, link, and alike.
attrsFurther information defining attributes of the mask such as the URL in a link.

The marks include:

Rate this page: