This document is a review draft. Readers are invited to submit comments to the Best Practices Board.


  • Revathy Ramanan, XBRL International Inc.
  • Paul Warren, XBRL International Inc.


  • Mark Goodhand, CoreFiling

Table of Contents

The xBRL-JSON specification1 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 2 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.

The full article is exclusively accessible to members of XBRL International.

If you or your organisation is a member but you do not have an XBRL username and password, please register for an account.

Not yet a Member?

Join XBRL today in order to get access to exclusive content, and other membership benefits:

  • Discounted conference attendance
  • Access to our Global Community
  • Use of the XBRL logo to promote your products and services
  • Early visibility and ability to influence new standards through Working Group participation
  • Inclusion in our Tools and Services directory

Learn more about joining the consortium.


Would you like
to learn more?

Join our Newsletter mailing list to
stay plugged in to the latest
information about XBRL around the world.

By clicking submit you agree to the XBRL International privacy policy which can be found at xbrl.org/privacy