Table of Contents

The xBRL-JSON specification¹ provides a simple representation of an XBRL report in JSON format. xBRL-JSON is one of a number of standard formats that can be used for XBRL data. The xBRL-JSON format is generally the easiest format to use for consuming data from an XBRL report programmatically. This tutorial explains how XBRL reports can be represented in xBRL-JSON format and is targeted towards users trying to understand the xBRL-JSON specification.

A growing number of XBRL software packages support the xBRL-JSON format and can automatically convert Inline XBRL or xBRL-XML reports into xBRL-JSON, or xBRL-JSON into xBRL-XML.

1 Simple Monetary Fact

The extract below shows a representation of a simple monetary fact for Assets; in xBRL-JSON.

"f1": {
    "value": "1230000",
    "decimals": 0,
    "dimensions": {
        "concept": "eg:Assets",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2020-01-01T00:00:00",
        "unit": "iso4217:EUR"
    }
},

Facts in xBRL-JSON are represented by a value for the fact, associated with a number of dimensions that define the meaning of that value.

The fact value is provided by the value property, in this case 1230000. Note that numeric fact values are represented as JSON strings in xBRL-JSON (see section Numeric Facts Representation.)

The "decimals" property declares the precision of numeric values. Here the decimal property for the fact is specified as 0, declaring that the reported value is accurate to the nearest whole number. In xBRL-JSON, and infinitely precise value is represented by omitting decimals property.

The XBRL dimensions ² applicable to the fact are specified as key-value pairs in the "dimensions" object:

• "concept" provides the meaning for the fact. The value, in this case eg:Assets identifies the name of a concept defined in the associated XBRL taxonomy. The value is in QName format, which is described later in this section.
• "entity" specifies the entity to which the fact relates. This example uses a Legal Entity Identifier, or LEI.
• "period" defines the period in time to which a fact relates, which will be either an instant or a duration. This is determined by the concept. In this case, the fact is stated at an instant (2020-01-01T00:00:00). The time component 00:00:00 represents the start of the day which is technically equal to end of the previous day, 2019-12-31.
  • All periods in xBRL-JSON are represented with a time component. Refer to the section on period representation to understand how the representation differs from xBRL-XML.
• "unit" specifies the units in which a numeric fact is reported. The unit value iso4217:EUR represents Euro as defined in the ISO currency code list.

All facts in an xBRL-JSON report have a unique ID. This is provided by the keys in the "facts" object (in this case f1).

1.1 xBRL-JSON report structure

An xBRL-JSON report will typically contain many facts, following the format shown in the previous section. These facts are defined in a "facts" object within the report. In addition to the facts object, xBRL-JSON reports include a "documentInfo" object which provides contextual information for the report as a whole. The example below shows a complete xBRL-JSON report containing two facts.

{
  "documentInfo": {
    "documentType": "https://xbrl.org/2021/xbrl-json",
    "namespaces": {
      "eg": "http://example.com/xbrl-json/taxonomy/",
      "lei": "http://standards.iso.org/iso/17442",
      "iso4217": "http://www.xbrl.org/2003/iso4217"
    },
    "taxonomy": [
      "http://example.com/xbrl-json/taxonomy/example.xsd"
    ]
  },
  "facts": {
    "f1": {
      "value": "1230000",
      "decimals": 0,
      "dimensions": {
        "concept": "eg:Assets",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2020-01-01T00:00:00",
        "unit": "iso4217:EUR"
      }
    },
    "f2": {
      "value": "230000",
      "decimals": 0,
      "dimensions": {
        "concept": "eg:Equity",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2020-01-01T00:00:00",
        "unit": "iso4217:EUR"
      }
    }
  }
}

Example 1

1.1.1 Document Info

The document information section contains information common to all data in the JSON report and has the following properties:

1.1.2 Document Type

"documentType": "https://xbrl.org/2021/xbrl-json",

A fixed value https://xbrl.org/2021/xbrl-json is specified as the document type which indicates the document is an xBRL-JSON report.

1.1.3 Namespaces

"namespaces": {
        "eg": "http://example.com/xbrl-json/taxonomy/",
        "lei": "http://standards.iso.org/iso/17442",
        "iso4217": "http://www.xbrl.org/2003/iso4217"
        },

As we have seen in the previous example, many values in xBRL-JSON are expressed as QNames, which is a format for providing concise, but globally unique identifiers. QNames consist of a prefix and local name, separated by a colon, for example eg:Assets. The prefix (eg) is a shorthand for a longer URI which is provided by the namespaces object. All prefixes used in an xBRL-JSON report must be defined in the namespaces object.

It should be noted that the "entity dimension" technically uses an SQName. This is essentially the same as a QName, but has a less restrictive local name. Unlike a QName, the local part of an SQName can start with a number.

1.1.4 Taxonomy

"taxonomy": [
        "http://example.com/xbrl-json/taxonomy/example.xsd"
        ]

This provides a list of URLs that identify the taxonomy used by the xBRL-JSON report.

1.2 Facts

The facts object consists of all reported facts identified by ID. The xBRL-JSON report in Example 1 reports two facts, f1 and f2.

2 Text Fact with Language and Duration period

This example shows how a text fact is represented in xBRL-JSON.

{
  "documentInfo": {
    "documentType": "https://xbrl.org/2021/xbrl-json",
    "namespaces": {
      "eg": "http://example.com/xbrl-json/taxonomy/",
      "lei": "http://standards.iso.org/iso/17442",
      "iso4217": "http://www.xbrl.org/2003/iso4217"
    },
    "taxonomy": [
      "http://example.com/xbrl-json/taxonomy/example.xsd"
    ]
  },
  "facts": {
    "f1": {
      "value": "ABC INC",
      "dimensions": {
        "concept": "eg:EntityRegistrantName",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2019-01-01T00:00:00/2020-01-01T00:00:00",
        "language": "en"
      }
    }
  }
}

Example 2

The value of the text concept Entity Registrant Name (ABC INC) is specified in the same way as for the numeric facts in the previous example.

As noted previously, XBRL facts can relate to either an instant or a duration. In this case the fact relates to a duration, which is represented using a pair of date-time values separated by a forward slash ("/"), indicating the duration of time to which the fact relates. Note that as the values identify a date and time, the end date is specified as 00:00:00 on the day after the last day of the period. This is explained in more detail in the section on period representation.

The fact also specifies a language dimension value as en, identifying the language of the text value as English. The value for the language dimension is specified using a BCP 47 language code. Common practice is to use either a one-part language code (e.g. en) or a two-part language-region code (e.g. en-us). xBRL-JSON requires language codes to be represented as lower-case strings.

3 Taxonomy-defined Dimensions (Explicit)

In addition to the built-in dimensions shown in the previous examples, such as concept, entity, period and units, it is also possible for XBRL taxonomies to define their own dimensions.

This example shows an xBRL-JSON representation of fact reported with a taxonomy-defined dimension. Here we take an example of a taxonomy-defined dimension, Classes of Property Plant and Equipment, with possible values of Buildings, Land, Vehicles and Computer. Dimensions for which an allowed list of values is specified in the taxonomy are referred to as explicit taxonomy-defined dimensions.

{
  "documentInfo": {
    "documentType": "https://xbrl.org/2021/xbrl-json",
    "namespaces": {
      "eg": "http://example.com/xbrl-json/taxonomy/",
      "lei": "http://standards.iso.org/iso/17442",
      "iso4217": "http://www.xbrl.org/2003/iso4217"
    },
    "taxonomy": [
      "http://example.com/xbrl-json/taxonomy/example.xsd"
    ]
  },
  "facts": {
    "f1": {
      "value": "1000000",
      "dimensions": {
        "concept": "eg:PropertyPlantAndEquipment",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2020-01-01T00:00:00",
        "unit": "iso4217:EUR",
        "eg:ClassesOfPropertyPlantAndEquipment": "eg:Buildings"
      }
    }
  }
}

Example 3

The fact value and other built-in dimensions are specified as seen in the previous examples. The taxonomy-defined dimension Classes of Property Plant and Equipment is specified as an additional property (eg:ClassesOfPropertyPlantAndEquipment) in the "dimensions" object. The value for this property eg:Buildings corresponds to the domain member Buildings.

The dimension and domain members are specified in QName format. The eg prefix is drawn from the "namespaces object", and must correspond to the namespace of the taxonomy in which these are defined.

Additional taxonomy defined dimensions can be specified in a similar way for multi-dimensional facts, as shown in the extract below.

"f1": {
    "value": "1000000",
    "dimensions": {
        "concept": "eg:PropertyPlantAndEquipment",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2020-01-01T00:00:00",
        "unit": "iso4217:EUR",
        "eg:ClassesOfPropertyPlantAndEquipment":"eg:Buildings",
        "eg:OperatingLeaseStatus":"eg:SubjectToOperatingLeases"
        }
    }

4 Taxonomy-defined Dimensions (Typed)

XBRL taxonomies allow the definition of dimensions that take a value of a particular type, rather than a value from a specified list. These are referred to as typed taxonomy-defined dimensions.

This example shows a fact in xBRL-JSON with a typed taxonomy-defined dimension.

{
  "documentInfo": {
    "documentType": "https://xbrl.org/2021/xbrl-json",
    "namespaces": {
      "eg": "http://example.com/xbrl-json/taxonomy/",
      "lei": "http://standards.iso.org/iso/17442",
      "iso4217": "http://www.xbrl.org/2003/iso4217"
    },
    "taxonomy": [
      "http://example.com/xbrl-json/taxonomy/example.xsd"
    ]
  },
  "facts": {
    "f1": {
      "value": "100000",
      "dimensions": {
        "concept": "eg:Revenue",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2019-01-01T00:00:00/2020-01-01T00:00:00",
        "unit": "iso4217:EUR",
        "eg:BusinessSegment": "Electric Motor Vehicles"
      }
    }
  }
}

Example 4

The typed taxonomy-defined dimension Business Segment is specified as an additional property (eg:BusinessSegment). The value for this property, Electric Motor Vehicles, represents the typed dimension member specified by the preparer.

The name of a typed dimension is specified as a QName and the format of the value will depend on the type specified for the dimension in the taxonomy — in this case, a string type.

5 Links and footnotes

Additional information about a fact can be conveyed by connecting it to other facts using "links". Links can be used to represent xBRL-XML "text footnotes" as well as other relationships between facts.

This example shows how to define a text footnote in xBRL-JSON.

A footnote is linked to fact by specifying a "link type" (arcrole) and categorising into a "link group" (extended link role). The "link types" and "link groups" to be used in the report are specified in documentInfo object.

{
  "documentInfo": {
    "documentType": "https://xbrl.org/2021/xbrl-json",
    "namespaces": {
      "eg": "http://example.com/xbrl-json/taxonomy/",
      "lei": "http://standards.iso.org/iso/17442",
      "iso4217": "http://www.xbrl.org/2003/iso4217"
    },
    "linkTypes": {
      "footnote": "http://www.xbrl.org/2003/arcrole/fact-footnote"
    },
    "linkGroups": {
      "_": "http://www.xbrl.org/2003/role/link"
    },
    "taxonomy": [
      "http://example.com/xbrl-json/taxonomy/example.xsd"
    ]
  },
  "facts": {
    "f1": {
      "value": "1000",
      "dimensions": {
        "concept": "eg:Revenue",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2019-01-01T00:00:00/2020-01-01T00:00:00",
        "unit": "iso4217:EUR"
      },
      "links": {
        "footnote": {
          "_": [
            "f2"
          ]
        }
      }
    },
    "f2": {
      "value": "Includes € 50 unbilled revenue",
      "dimensions": {
        "concept": "xbrl:note",
        "noteId": "f2",
        "language": "en"
      }
    }
  }
}

Example 5

The footnote is reported as a fact, in this case fact f2. The value is the footnote text, and the fact uses the special concept xbrl:note. This special concept is used to represent xBRL-XML footnotes. Such footnotes must also have a special noteId ³dimension, with a value equal to the fact’s ID (in this case, f2).

The footnote is linked to the fact to which it relates using the "links" mechanism. This can be seen on fact f1 in the example. The properties of the "links object" denote the link type. The property names are shorthand values, much like the prefixes used in QNames, and refer to values in the "linkTypes" object in the documentInfo object. In this case, "footnote" resolves to a link type of http://www.xbrl.org/2003/arcrole/fact-footnote, which is the standard link type for xBRL-XML text footnotes.

The properties of the "footnote" object denote link groups, and again, these are shorthand values that must be resolved using the "linkGroups" object in "documentInfo". In this case, the value _ refers to the standard link group, http://www.xbrl.org/2003/role/link.

The value of the _ property is a list containing the IDs of the footnote facts that are to be associated with this fact. In this case, the footnote fact f2 is associated with the fact f1.

It should be noted that footnote and _ are reserved aliases: this means that they may only be bound to the URIs shown above, and that where these URIs are used, they may only use these aliases.

A fact can be associated with multiple footnotes by including more than one ID in this list:

"links": {
  "footnote": {
    "_": ["f2", "f3"]
  }
}

6 The canonical values feature

For many datatypes, there are multiple equivalent ways of representing the same value. For example, 1.23, +1.23, 1.2300 and 01.23 are all alternative representations of the same decimal value.

These alternative representations can make processing more difficult, as any comparison of values must take into account the value’s datatype; 1.23 and 01.23 are equivalent decimal values, but they are not equivalent strings.

In order to simplify processing, xBRL-JSON requires that all built-in dimensions and other specification-defined JSON fields, are expressed in the "canonical lexical representation". This is a standard form that gives a single unique representation for each possible value. For example, the canonical representation of an integer value prohibits leading zeroes and the “+” sign.

Using canonical values enables easy comparison of documents and values, as semantic equivalence can be established by simple string comparison.

xBRL-JSON provides an option that extends the use of canonical values to fact and taxonomy-defined dimension values. The optional "canonical values" feature indicates that an xBRL-JSON document uses canonical values throughout.

This feature is enabled by specifying a value of true for "xbrl:canonicalValues" within the "features" object of "documentInfo", as shown below:

{
  "documentInfo": {
    "documentType": "https://xbrl.org/2021/xbrl-json",
    "features": {
      "xbrl:canonicalValues": true
    },
    "namespaces": {
      "eg": "http://example.com/xbrl-json/taxonomy/",
      "lei": "http://standards.iso.org/iso/17442",
      "iso4217": "http://www.xbrl.org/2003/iso4217",
      "xbrl": "https://xbrl.org/2021"
    },
    "taxonomy": [
      "http://example.com/xbrl-json/taxonomy/example.xsd"
    ]
  },
  "facts": {
    "f1": {
      "value": "1230000",
      "dimensions": {
        "concept": "eg:Assets",
        "entity": "lei:00EHHQ2ZHDCFXJCPCL49",
        "period": "2020-01-01T00:00:00",
        "unit": "iso4217:EUR"
      }
    }
  }
}

Example 6

More information on canonical lexical representation for specific datatypes can be found in the XML schema datatype specification.

The canonical representation for the period dimension is a single date-time value for instant concepts and a pair of date-time value separated by “/” for duration concepts.

7 Extensibility

xBRL-JSON allows additional, custom properties to be included within the document info and top-level report objects, and within individual fact objects. Such custom properties can be used to convey additional information such as rendering information or metadata from the taxonomy, enabling the report to be repurposed for different use cases. Any custom properties must have a name which is a prefixed QName, and the namespace corresponding to the prefix must not use the "xbrl.org" domain name. The value of custom properties can be any valid JSON value, including objects or arrays.

8 Numeric Facts Representation

xBRL-JSON uses a string representation of all fact values, including numeric values. This is because JSON’s native number type uses floating point data types which can result in a loss of precision. The use of strings allows software to handle the values using suitable infinite precision decimal libraries.

9 Key differences from xBRL-XML

There are a few notable differences between xBRL-JSON and the conventional xBRL-XML format.

9.1 Optional Dimensions

The Open Information Model upon which xBRL-JSON is based permits entity, unit and period (for duration concepts) to be omitted. The omission of these dimensions is permitted to address scenarios where a fact does not relate to a legal entity, or specific period-in-time, or is a unitless number.

A special value (scheme: https://xbrl.org/2021/entities; identifier: NA) is used to represent the absence of the entity dimension in xBRL-XML. Absence of the period dimension corresponds to the forever value in xBRL-XML, and absence of the unit dimension corresponds to the special value of xbrli:pure in xBRL-XML.

In example 7, a duration concept Number of Job Grades is reported in xBRL-JSON, without the unit, period and entity dimensions.

{
  "documentInfo": {
    "documentType": "https://xbrl.org/2021/xbrl-json",
    "namespaces": {
      "eg": "http://example.com/xbrl-json/taxonomy/"
    },
    "taxonomy": [
      "http://example.com/xbrl-json/taxonomy/example.xsd"
    ]
  },
  "facts": {
    "f1": {
      "value": "10",
      "dimensions": {
        "concept": "eg:NumberOfJobGrades"
      }
    }
  }
}

Example 7

9.2 Period representations

In xBRL-JSON both the instant and duration period values are represented using the period property. A duration period value is represented using a pair of date-time values separated by /, as seen in the example above. This representation is a subset of formats allowed by ISO8601 for expressing time intervals.

xBRL-XML allows the time component of date times to be omitted, but applies a different interpretation depending on the context in which it is used:

• A period start date with no time component is interpreted as 00:00:00 at the start of that day.
• An end date or instant with no time component is interpreted as 24:00:00 on that day (or, equivalently, as 00:00:00 on the following day)

To avoid the confusion caused by different interpretations of same value, xBRL-JSON requires that the time component is always included in period values. Table 1 gives examples of how dates in xBRL-XML are represented in xBRL-JSON.

Appendix A xBRL-JSON examples

The xBRL-JSON examples used in this tutorial are available for download:

• xBRL-JSON files: xbrl-json-tutorial-examples.zip
• XBRL Taxonomy Package: xbrl-json-tutorial-taxonomy.zip