Table of Contents

The Open Information Models's (OIM) xBRL-CSV specification¹ facilitates the creation and consumption of XBRL report data in CSV syntax. xBRL-CSV combines the exceptionally efficient and widely supported CSV format, with the XBRL benefits of taxonomy-backed structured data, including strong validation, dimensional data point definitions and multi-lingual data exchange. It is targeted towards technical business users and taxonomy owners looking to understand how the xBRL-CSV specifications allow different types of XBRL reports to be represented in xBRL-CSV format.

1 Simple xBRL-CSV report

In the first example we take a Loan Disclosure template as shown in Table 1 and show how it can be represented in xBRL-CSV format. The data in Table 1 is an extract of a simple granular loan containing the amount of each loan that is outstanding as well as the loan loss provision estimated by the lender. These two disclosures are modelled in the taxonomy as monetary concepts and the loan identification is modelled as a typed taxonomy-defined dimension.

1.1 CSV data table

Table 1 can be represented in a CSV data table as shown below. We’ll give it the file name table1-data-facts.csv.

loan_id,loan_amount,provision_amount
L9209384832,1000,100
L12312312123,1100,20
L2393823489,800,40

Note that the CSV data format uses unformatted numbers (thousands separators and currency symbols are not permitted). The first row in an xBRL-CSV table provides column identifiers that are used to associate metadata with individual columns, as explained in the following section. Column identifiers have a restricted format; they cannot include spaces and must not start with a number. CSV values can optionally be enclosed in double quotes. This is necessary for string values that contain commas.

1.2 JSON metadata

In order to transform this CSV data table into xBRL-CSV format, it has to be associated with a separate JSON file specifying the XBRL dimensions² for the fact values. This information in this file is referred to as JSON metadata. The JSON metadata for the CSV data in Table 1 is shown below. JSON metadata re-uses some of the syntax from xBRL-JSON.

Let’s break the JSON code into sections (highlighted) to understand them better.

{
    "documentInfo": {
        "documentType": "https://xbrl.org/2021/xbrl-csv",
        "namespaces": {
            "eg": "http://example.com/xbrl-csv/taxonomy",
            "lei": "http://standards.iso.org/iso/17442",
            "iso4217": "http://www.xbrl.org/2003/iso4217"
        },
        "taxonomy": [
            "http://example.com/xbrl-csv/taxonomy.xsd"
        ]
    },
    "tableTemplates": {
        "loan_data_template": {
            "columns": {
                "loan_id": {},
                "loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "period": "2019-01-01T00:00:00",
                        "unit": "iso4217:EUR",
                        "entity": "lei:FAKE0012345678901274",
                        "eg:LoanId": "$loan_id"
                    }
                },
                "provision_amount": {
                    "dimensions": {
                        "concept": "eg:ProvisionAmount",
                        "period": "2019-01-01T00:00:00",
                        "unit": "iso4217:EUR",
                        "entity": "lei:FAKE0012345678901274",
                        "eg:LoanId": "$loan_id"
                    }
                }
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table1-data-facts.csv"
        }
    }
}

Example 1 - JSON Metadata

1.2.1 Document information

The "document information" section contains information common to all CSV data tables, and has the following properties:

{ 
    "documentType": "https://xbrl.org/2021/xbrl-csv",
    "namespaces": {
        "eg": "http://example.com/xbrl-csv/taxonomy",
        "lei": "http://standards.iso.org/iso/17442",
        "iso4217": "http://www.xbrl.org/2003/iso4217"
    },
    "taxonomy": [
        "https://example.com/xbrl-csv/taxonomy.xsd"
    ],

A fixed value https://xbrl.org/2021/xbrl-csv is specified as the "document type" which indicates this is the JSON metadata for an xBRL-CSV report.

Document information provides a list of namespaces and their corresponding prefixes used in the xBRL-CSV report. These prefixes can be used in both the metadata file and accompanying CSV data tables.

The taxonomy property provides a list of URLs that identify the taxonomy used by the xBRL-CSV report.

1.2.2 Table Templates

The "table templates" section defines the structure of a CSV data table.

   "tableTemplates": {
        "loan_data_template": {
            "columns": {

Each template has a unique identifier, in this case "loan_data_template". The template lists all columns in the CSV data table. The column names specified in the template correspond to the headers in the CSV data table. The CSV data in this example has three columns (loan_id, loan_amount and provision_amount) which is reflected here in the JSON metadata.

                "loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "period": "2019-01-01T00:00:00",
                        "unit": "iso4217:EUR",
                        "entity": "lei:FAKE0012345678901274",
                        "eg:LoanId": "$loan_id"
                    }
                }

Let’s start with the second column: loan_amount. The dimensions property specifies dimension values applicable to all fact values in that column. For this column, fixed dimension values are specified for concept, period, unit and entity. Dimensions specified at column level are referred to as "column dimension".

The value for the typed dimension, eg:LoanId, is specified as "$loan_id". The $ symbol at the beginning of the dimension value means that the value for this dimension is drawn from elsewhere. In this case, the value is drawn from another column, although this syntax can also be used to reference table and report parameters. For each fact produced by this column, the value for this dimension will be drawn from the corresponding cell in the loan_id column. For example, the typed dimension value for fact value 1000 (first row of the loan_amount column) will be L9209384832 which is the first row of the loan_id column.

The provision_amount column is defined in a very similar way:

                "provision_amount": {
                    "dimensions": {
                        "concept": "eg:ProvisionAmount",
                        "period": "2019-01-01T00:00:00",
                        "unit": "iso4217:EUR",
                        "entity":"lei:FAKE0012345678901274",
                        "eg:LoanId":"$loan_id"
                    }
                }

For the first column, loan_id, an empty object is used. The absence of the "dimensions" property specifies that values in that column will not be used as fact values.

                "loan_id": {},
            }
        }
    },

The first value in the column loan_amount (1000) will create a fact with the following dimension values:

When a column value is used as fact values it is referred to as a "fact column". When a column value is used to provide dimension values, it is referred to as a "parameter value column". In this example we have two fact columns (loan_amount and provision_amount) and one parameter value column (loan_id).

Columns in a table will typically be either a parameter value column or a fact column, although it is possible for a column to be used as both, or neither (in which case the values from the column will not appear in the report at all).

1.2.3 Tables

The tables property connects table templates with CSV data tables.

    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table1-data-facts.csv"
        }
    }
}

Here loan_data_table (the table identifier) connects the table template loan_data_template of the JSON metadata with CSV file table1-data-facts.csv. The URL is a relative path from the JSON metadata file. A single template can be re-used across multiple CSV files.

2 Sharing common dimensions across a table (Table Dimensions)

In the JSON metadata for Table 1, the dimension values for period, unit and entity are the same for both the Loan and Provision columns. The eg:LoanId typed dimension value is also the same across each row. This example demonstrates how common dimensions for a table can be defined once to avoiding repetition in the metadata.

In this example we continue with data in Table 1 and show an alternative approach for the JSON metadata.

{
    "documentInfo": {
        "documentType": "https://xbrl.org/2021/xbrl-csv",
        "namespaces": {
            "eg": "http://example.com/xbrl-csv/taxonomy",
            "lei": "http://standards.iso.org/iso/17442",
            "iso4217": "http://www.xbrl.org/2003/iso4217"
        },
        "taxonomy": [
            "http://example.com/xbrl-csv/taxonomy.xsd"
        ]
    },
    "tableTemplates": {
        "loan_data_template": {
            "columns": {
                "loan_id": {},
                "loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount"
                    }
                },
                "provision_amount": {
                    "dimensions": {
                        "concept": "eg:ProvisionAmount"
                    }
                }
            },
            "dimensions": {
                "eg:LoanId": "$loan_id",
                "period": "2019-01-01T00:00:00",
                "unit": "iso4217:EUR",
                "entity": "lei:FAKE0012345678901274"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table1-data-facts.csv"
        }
    }
}

Example 2 - JSON Metadata

The common dimensions for period, unit and entity (highlighted) are defined as "table dimensions", meaning that they will be applied to all facts of the table. This is done by including a dimensions property directly within the table template definition, rather than as part of an individual column definition.

The typed dimension referencing a parameter column loan_id is also defined as a table dimension. As before, this specifies that the typed dimension value for all facts in a row will be obtained from the corresponding value of the loan_id column. The definition of the individual columns, loan_amount and provision_amount is greatly simplified, as only the concept dimension needs to be specified on each.

The first value in the loan_amount column (1000) will create a fact with the following dimension values:

3 Adding more dimensions

In the previous examples we have seen that the period and unit dimensions were common to all cells of the table. Table 2 is an extension of the loan disclosure from Table 1, which reports the loan amount in the home currency (loan_amount_hc) and local currency (loan_amount_lc) of the borrower. The additional disclosure is modelled as a monetary concept in the taxonomy.

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