About Atlassian Document Format

Technical Guide

Introduction

The Atlassian Document Format (ADF) represents rich text stored in Atlassian Cloud products. For example, in the Jira Cloud platform, the text in issue comments and in textarea custom fields is stored as ADF. It is a replacement for the older Atlassian Wiki Markup data storage format that is still used in the legacy Server versions of several Atlassian products, as well as in Jira Data Center.

JSON Schema

An ADF document is a structured JSON object conforming to a published JSON schema.

Not all marks and nodes that are included in the JSON schema are available for use in all products. In particular, many features of ADF are specific to the flexible layout of information provided in Confluence and will not function correctly in Jira.

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 the like. Inline nodes contain the document content such as text and images. Some of these nodes can take marks that define text formatting or other embellishments such as bold, italics, or hyperlinks.

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.

Example

Java

1
2
3
4
5
doc(p(
    text("Hello "),
    text("world").strong()
));

ADF

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

Result

Hello world

Structure Details

ADF consists of nodes and (optionally) marks. This documentation refers to “elements” when speaking of nodes and marks collectively. For example, all elements have a required type property that identifies the type of node or mark.

The example document above is composed of five elements:

1. The special doc node that must always be present.
2. A paragraph block node.
3. A text inline node without any marks.
4. Another text node that does have a mark.
5. The strong mark on that text node.

Read on to learn more about:

• Nodes
• Marks