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.

Note that from this example onwards, CSV data tables will be presented in tabular form, rather than the raw, comma-separated format, in order to improve readability.

The unit value for each fact in the loan_amount_lc column varies and cannot be fixed in the table template. The original (local) currency of the loan amount is now reported in a separate column (local_currency). We can specify the value for the unit dimension in the same way as the eg:LoanId typed dimension.

{
    "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": {},
                "local_currency": {},
                "loan_amount_hc": {
                    "dimensions": {
                        "unit": "iso4217:EUR"
                    }
                },
                "loan_amount_lc": {
                    "dimensions": {
                        "unit": "$local_currency"
                    }
                }
            },
            "dimensions": {
                "eg:LoanId": "$loan_id",
                "concept": "eg:LoanAmount",
                "period": "2019-01-01T00:00:00",
                "entity": "lei:FAKE0012345678901274"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table2-data-facts.csv"
        }
    }
}

Example 3 - JSON Metadata

The unit dimension value for the loan_amount_lc column (highlighted) refers to the local_currency column by using the $ symbol. This specifies that the unit value for each row in the loan_amount_lc column will be obtained from the corresponding value of the local_currency column. For example, the unit for fact value 1115 (first row of the loan_amount_lc column) will be iso4217:USD which is the first row of the local_currency column. In this example we now have two parameter columns: loan_id which supplies the typed dimension value to all facts, and local_currency which supplies the unit value to the loan_amount_lc column.

Units in XBRL are specified using "QNames": the combination of a short prefix and a name for the unit. The values in this example all use the iso4217 prefix, indicating that the unit is an ISO 3-letter currency code. XBRL also allows more complex units to be specified, but this is not covered in this tutorial.

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

4 Periods in xBRL-CSV

Data within a table will often be a mixture of instant and duration facts, with the instant facts typically corresponding to either the start or the end of the duration facts. This example demonstrates how a single column containing period information can be used for obtaining instant and duration period values.

Table 3 adds three more columns to the Loan disclosure of Table 1: original_loan_amount (Original Loan Amount), rate (Contracted Interest Rate) and a period column, fixed_rate_period. The original_loan_amount and rate are modelled in the taxonomy as instant and duration concepts respectively. The fixed_rate_period column specifies the valid duration for the interest rate (rate). The period is specified as a date range, with start and end dates separated by dots (..). The ".." notation specifies an inclusive date range; the period includes both the start date and the end date.

original_loan_amount is an instant concept and the report needs the period value for this fact to be the date on which the loan was first disbursed. For the purposes of this example, let’s assume this date is the same as the start date in the fixed_rate_period column:

{
    "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": {},
                "fixed_rate_period": {},
                 "loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "2019-01-01T00:00:00"
                    }
                },
                "original_loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "$fixed_rate_period@start"
                    }
                },
                "rate": {
                    "dimensions": {
                        "concept": "eg:InterestRate",
                        "period": "$fixed_rate_period"
                    }
                }
            },
            "dimensions": {
                "eg:LoanId": "$loan_id",
                "entity": "lei:FAKE0012345678901274"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table3-data-facts.csv"
        }
    }
}

Example 4 - JSON Metadata

The period dimension for the original_loan_amount column refers to the parameter column fixed_rate_period with the suffix @start. This is a "period-specifier" and specifies that the period value for each row in the original_loan_amount column will be obtained from the start of the duration period in the column fixed_rate_period. For example, the period for fact value 1200 (first row of the original_loan_amount column) will be 2017-01-01T00:00:00 which corresponds to the start of the duration in the first row of the fixed_rate_period column.

The period dimension for the rate column refers to the parameter column fixed_rate_period. This specifies that the period value for each row in the rate column will be obtained from the duration period in the fixed_rate_period column. For example, the period for fact value 0.051 (first row of the rate column) will be 2017-01-01T00:00:00/2019-01-01T00:00:00 which corresponds to the duration in first row of the fixed_rate_period column.

xBRL-CSV allows a number of different formats for specifying period dimensions, such as date-time-based formats (e.g. 2019-01-01T00:00:00/2020-01-01T00:00:00) or abbreviated formats like the one used in this example. Refer to Appendix A for a list of permitted period formats.

The first value in the rate column (0.051) will be interpreted with dimension values as follows:

Please note that although eg:InterestRate is a numeric concept, the unit dimension was not specified. This is valid as unit is optional in the OIM model, and corresponds to the special value of xbrli:pure in xBRL-XML (XBRL v2.1).

The OIM model also permits period (for durational concepts) and entity to be omitted. Omitting period corresponds to forever in xBRL-XML. The xBRL-XML specification provides a special not applicable value to represent the absence of the entity dimension.

5 Sharing common values between columns (Table Parameters)

In the previous examples we have seen how dimension values common across all facts of the table can be defined once, as table dimensions. This example explains how to define common dimensions that can be shared between specific columns in a table in order to avoid repetitive definitions.

Table 4 is an extension of the Loan disclosure in Table 1, which has country of incorporation of the borrower (country_inc) in addition to the existing columns. The country of incorporation is modelled as an enumeration concept with duration period type in the taxonomy. The values in the country_inc column are country codes that are defined as domain members in the taxonomy.

In this example we will define a single period dimension with value 2017-01-01..2017-12-31 in one place and use it to obtain an "instant period" value for columns.

{
    "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",
                        "unit": "iso4217:EUR",
                        "period": "$p1@end"
                    }
                },
                "provision_amount": {
                    "dimensions": {
                        "concept": "eg:ProvisionAmount",
                        "unit": "iso4217:EUR",
                        "period": "$p1@end"
                    }
                },
                "country_inc": {
                    "dimensions": {
                        "concept": "eg:CountryOfIncorporation",
                        "period": "$p1"
                    }
                }
            },
            "dimensions": {
                "eg:LoanId": "$loan_id",
                "entity": "lei:FAKE0012345678901274"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table4-data-facts.csv",
            "parameters": {
                "p1": "2017-01-01..2017-12-31"
            }
        }
    }
}

Example 5 - JSON Metadata

In the table section, a "table parameter" p1 is defined with a value 2017-01-01..2017-12-31 (highlighted). A table parameter declares a static value, which can be used as the value for table or column dimensions within that table.

The country_inc column defines a period dimension with value "$p1". A dimension value starting with the $ symbol denotes a parameter reference. As shown in examples 1, 2 and 3, it takes its value from a column with the specified name. If no such column exists in the current table, the value is taken from a table parameter, or if no such table parameter exists, a report parameter (see Section 9).

In this case, as there is no p1 column, the value is taken from the p1 table parameter (2017-01-01..2017-12-31). This is used as the period value for all facts in the country_inc column.

Column loan_amount defines a period dimension referencing the same table parameter, with the addition of the @end period-specifier. This specifies that the period value for all facts in the loan_amount column will be the end of the duration in the parameter value (2018-01-01T00:00:0).

The first value in the country_inc column (eg:GB) will have the following dimension values:

The value eg:GB in the CSV data table is the name of the domain member defined in the taxonomy, specified in QName format. The eg prefix is drawn from the namespaces property (see section Document information), and must correspond to the namespace of the taxonomy.

6 Decimals Property

In XBRL, numeric facts can specify the accuracy to which the value is reported. In previous examples, we have not done this, and so the numeric values will be interpreted as being infinitely precise. Values in a report are often rounded values, and the decimals property can be used to declare the precision of such values.

This example will demonstrate how a decimal property can be specified in the JSON metadata. Table 5 is same as Table 3.

{
    "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": {},
                "fixed_rate_period": {},
                "loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "2019-01-01T00:00:00"
                    }
                },
                "original_loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "$fixed_rate_period@start"
                    }
                },
                "rate": {
                    "decimals": 4,
                    "dimensions": {
                        "concept": "eg:InterestRate",
                        "period": "$fixed_rate_period"
                    }
                }
            },
            "decimals": 0,
            "dimensions": {
                "eg:LoanId": "$loan_id",
                "entity": "lei:FAKE0012345678901274"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table5-data-facts.csv"
        }
    }
}

Example 6 - JSON Metadata

We can see that a decimals property is defined at the table-template level with a value of 0 (highlighted). This specifies a default value for all numeric facts in the table that do not have a value specified at the column level. The rate column specifies a decimals value of 4. This overrides the table-level value, and specifies that values in this column are accurate to 4 decimal places.

Facts in the other numeric columns (loan_amount and original_loan_amount) will in inherit the decimal property of "0", declaring that reported values are accurate to the nearest whole number.

The first value in the rate column (0.051) will have the following dimension values and decimal property:

Note that, unlike numeric fact values, decimals values are specified as JSON numbers (there are no quotes around the value in the JSON). If a value is reported to infinite precision, any inherited decimals value can be overridden and removed by specifying the special value of #none.

6.1 Decimals suffix

It is also possible to specify the decimals property on an individual fact level using a "decimals suffix". Under this approach, a fact value in a CSV table is suffixed with lowercase d followed by the decimals value. For example:

0.051d4

This specifies a value of 0.051, accurate to 4 decimal places.

Infinite precision can be specified with a suffix of dINF, for example:

0.051dINF

A decimals suffix overrides any decimals value specified at either the column, table or report level.

7 Sharing common dimensions across the report (Report Dimensions)

Generally, an xBRL-CSV report will contain more than one CSV data table and there will be dimensions such as entity and period which are common across all tables. The example in this section demonstrates how such common dimensions can be defined at the report level. In this example we consider two tables:

• Table 6: an extract from the Loan Disclosures set out in Table 1
• Table 7: a new Country-Exposure disclosure. The countries in this disclosure are modelled as explicit taxonomy-defined dimensions. The values in the country column correspond to domain members defined in the taxonomy. The amount of credit exposure (credit_ exposure) is defined as a monetary concept.

The entity, unit and period dimension values are the same for both tables. These can be defined as "report dimensions".

{
    "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",
                        "eg:LoanId": "$loan_id"
                    }
                }
            }
        },
        "country_exposure_template": {
            "columns": {
                "country": {},
                "credit_exposure": {
                    "dimensions": {
                        "concept": "eg:CreditExposure",
                        "eg:country": "$country"
                    }
                }
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table6-data-facts.csv"
        },
        "country_exposure_table": {
            "template": "country_exposure_template",
            "url": "table7-data-facts.csv"
        }
    },
    "dimensions": {
        "period": "2019-01-01T00:00:00",
        "unit": "iso4217:EUR",
        "entity": "lei:FAKE0012345678901274"
    }
}

Example 7 - JSON Metadata

In the table template definition, we can see there are two templates defined. These templates are associated with their respective CSV data tables in the tables property.

The dimension values for period, unit and entity are defined as "report dimensions" (highlighted). These dimension values provide a default for all facts across all tables in the report. This is an efficient way of defining report-wide common dimension values. Dimensions defined at the report level can be overridden at the table or column level. These inheritance rules are discussed in detail in Section 12.

In Table 7, the first value in the credit_exposure column (2000) will have the following dimension values and decimal property:

8 Generating unique values for typed dimensions (Row Numbers)

Rows in a CSV table are typically distinguished in XBRL using a typed dimension. All values from a row will have the same value for the typed dimension. Usually the data will include a suitable identifier for the, such as loan identifier seen in previous examples.

In some cases, there may not be a suitable identifier, and it is necessary to generate an arbitrary value that is unique to each row in order to group the facts in the row. In these cases, it is possible to use the row number as a dimension value, as shown in this example.

Let’s take an example in Table 8 which has details on the number of new contracts per business line. In the taxonomy business_line_name (Line of business name) is modelled as a string concept and no_of_new_contracts (Number of contracts) is defined as an integer. The typed dimension eg:business_line_identification for every row is a dummy serial number which is not available in the CSV data table.

{
    "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": {
        "contracts_data_template": {
            "columns": {
                "business_line_name": {
                    "dimensions": {
                        "concept": "eg:LineOfBusinessName"
                    }
                },
                "no_of_new_contracts": {
                    "dimensions": {
                        "concept": "eg:NewContractsEnteredDuringPeriod"
                    }
                }
            },
            "dimensions": {
                "eg:business_line_identification": "$rowNumber"
            }
        }
    },
    "tables": {
        "contracts_data_table": {
            "template": "contracts_data_template",
            "url": "table8-data-facts.csv"
        }
    },
    "dimensions": {
        "period": "2018-01-01T00:00:00/2019-01-01T00:00:00",
        "entity": "lei:FAKE0012345678901274"
    }
}

Example 8 - JSON Metadata

The value for the eg:business_line_identification typed dimension is set as $rowNumber in the table dimension. This specifies that the dimension value for all facts in a row will correspond to its row number in the CSV data table. The row immediately after the header row (the second row of the table) will automatically have its row number allocated as 1 and additional rows are numbered sequentially.

The first value in the business_line_name column (ABC) will have the following dimension values:

9 Template definition by data collectors (Report Parameters)

In a closed reporting environment, all preparers will typically use the same table structure. In this scenario, xBRL-CSV makes it possible to re-use the same JSON metadata definition across all filings, avoiding the need for preparers to modify the JSON.

As shown in Section 7, it can be convenient to define values for common dimensions, such as entity and period, in report-level metadata. This example demonstrates how such common metadata can also be defined in a CSV file, avoiding the need to include such report-specific or entity-specific information in JSON metadata. We will continue with the loan data example as reproduced in Table 9.

{
    "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": "$period@end"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table9-data-facts.csv"
        }
    },
    "parameterURL": "report_parameters.csv",
    "dimensions": {
        "entity": "$entityLEI",
        "unit": "iso4217:EUR"
    }
}

Example 9 - JSON Metadata

In Section 5 we saw the application of table parameters, which can be referenced in column and table dimensions. We can also define "report parameters" which can be referenced in report, table and column dimensions across the report.

Entity and period (highlighted) are defined as report and table dimensions, respectively, and have values $entityLEI and $period@end. As there are no columns or table parameters with the names entityLEI or period, the values for these parameters are taken from report parameters. In this case, report parameters are defined using the "parameterURL" property, which provides the name of a CSV file containing the values for these parameters. For example:

name,value
entityLEI,lei:FAKE0012345678901274
period,2019

Note that the header (first) row of parameter CSV file must have name and value as fixed values.

In the use case where a data collector is defining the JSON metadata, preparers just need to report a CSV file like the one above specifying the values for the report parameters. Thus, report parameters can be used to specify entity-specific report wide values without editing the metadata file.

The first value in the loan_amount column (1000) will have the following dimension values and decimal property:

The report_parameters.csv file is equivalent to including the parameters directly in the JSON metadata using the "parameters" property:

{
"parameters": {
        "entityLEI": "lei:FAKE0012345678901274",
        "period": "2019"
    }
}

10 Extending metadata definitions

10.1 Referencing an existing JSON metadata file

In the previous example we have seen that a data collector-defined metadata file can be re-used by preparers without modification to create CSV data tables. Using that approach, the preparer has to provide a copy of the metadata file in the same directory as the CSV data file. As all reports will use the same metadata file, it is preferable to include the metadata file by reference. This can be done using the "extends" property.

{
    "documentInfo": {
        "documentType": "https://xbrl.org/2021/xbrl-csv",
        "extends": [ "http://example.com/jsonTemplate/report1.json"]
    }
}

Example 10.1 - JSON Metadata

This metadata file has document information (mandatory for a JSON metadata file) and the extends property. The extends property refers to the absolute URL of the metadata file provided by the data collector. The extends property specifies that all definitions in the referenced file are imported, including namespace prefixes, table templates, tables and parameters.

xBRL-CSV reports are identified by a JSON metadata file from which all CSV data and metadata can be discovered. This is known as the "primary metadata file", and in this case is the short JSON file shown in 10.1

In this example, the tables section in the data collector-defined metadata file in Section 9 (snippet below) includes a URL for a CSV data table:

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

It should be noted that this URL is resolved relative to the primary metadata file, rather than the file in which it appears. In this case the preparer has to create a CSV file with the name table9-data-facts.csv and place it in the same directory as the primary metadata file.

10.2 Extending a data collector’s JSON metadata definitions

When a metadata file is included using the extends mechanism it is possible to define new components such as templates, tables or parameters or add additional dimensions to existing definitions.

Table 10a and Table 10b show an extension of the loan disclosure from Table 9, adding information about the country of the loan. The country is defined as an explicit dimension.

The metadata defined by the data collector (Example 10.3) specifies the value for the country dimension as a table dimension. The value for the eg:Country dimension references a parameter c1 as the list of countries to be reported will vary for each preparer.

A preparer can extend the data collector-defined metadata to accommodate reporting data for multiple countries in separate CSV tables (Table 10a and 10b) as shown below:

{
    "documentInfo": {
        "documentType": "https://xbrl.org/2021/xbrl-csv",
        "extends": [ "http://example.com/jsonTemplate/report1.json" ]
    },
    
    "tables": {
        "loan_data_table_FR": {
            "template": "loan_data_template",
            "url": "table10-FR-data-facts.csv",
            "parameters": {
                "c1": "eg:FR"
            }
        },

        "loan_data_table_US": {
            "template": "loan_data_template",
            "url": "table10-US-data-facts.csv",
            "parameters": {
                "c1": "eg:US"
            }
        }
    }
}

Example 10.2 - JSON Metadata provided by Preparer

As before, the example uses the extends property to import the data collector’s metadata file.

In the tables section there are two tables, (loan_data_table_FR and loan_data_table_US) connected to the same table-template (defined in the imported metadata). The tables have distinct table parameter values (c1).

The loan_data_table_FR specifies table parameter values as eg:FR and will be set as the country dimension value for facts in the France CSV file. The value eg:FR is the name of the domain member defined in the taxonomy, specified in QName format. The eg prefix is drawn from the namespaces property of imported metadata and corresponds to the namespace of the taxonomy.

In Table 10a, the first value in the loan_amount (1000) will have the following dimension values and decimal property:

We have seen that preparers can extended metadata provided by data collectors to add their own definitions. In a closed reporting environment, it is likely that data collectors will want to restrict the ways in which preparers can extend metadata definitions. For example, data collectors may wish to prevent preparers from adding additional dimensions to existing definitions. This can be done using the "final" property as shown in the metadata below.

{
    "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"
        },
        "final": {
            "namespaces": true,
            "dimensions": true,
            "tableTemplates": true,
            "parameters": true,
            "taxonomy": true
        },
        "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": "$period@end",
                "eg:Country": "$c1"
            }
        }
    },
    "parameterURL": "report_parameters.csv",
    "dimensions": {
        "entity": "$entityLEI",
        "unit": "iso4217:EUR"
    }
}

Example 10.3 - JSON Metadata

The final property in the document info (highlighted) lists the components which cannot be extended by importing metadata files. In this example the data collector has restricted extension of namespaces, table templates, taxonomy, parameters and report dimensions. The metadata shown in the previous example (Example 10.2) would still be a valid extension as the preparer has extended tables property which is not listed in the final section.

It should be noted that where components are not listed as final, importing metadata can only add new definitions to the component; it cannot redefine existing definitions. For example, even where namespaces is not specified as final, an importing metadata file cannot redefine the meaning of an existing namespace prefix.

The following components can be listed under the final property to constrain their extension by importing metadata files:

• namespaces
• taxonomy
• tableTemplates
• tables
• (report) dimensions
• (report) parameters
• linkTypes
• linkGroups
• features

Note that the linkTypes, linkGroups and features components are not covered by this tutorial.

11 Key-value data in xBRL-CSV (Property Groups)

So far, we have seen CSV reports resembling a tabular data structure with multiple columns and each row representing a record identified by a taxonomy defined dimension.

This example explains how to represent reports prepared in key-value pair format where the key represents a data point identified by a combination of dimensions.

Table 11 is an extract of a Capital Adequacy Disclosure which is presented as a key-value list. Each item in the list is given a unique identifier, referred to as a data point ID.

This data point-centric style of reporting is preferred by some data collectors, particularly where the values to be collected do not form a logical, two-dimensional table.

The example above can be modelled in xBRL-CSV using "property groups". Each data point is modelled as a property group and identified by its data point ID. This allows the following table arrangement where the first column gives the name of a property group (the data point ID) and the second gives the value.

{
    "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": {
        "capital_adequacy_template": {
            "columns": {
                "item": {
                    "propertyGroups": {
                        "d1": {
                            "dimensions": {
                                "concept": "eg:CETCapitalRatio"
                            }
                        },
                        "d2": {
                            "dimensions": {
                                "concept": "eg:Tier1CapitalRatio"
                            }
                        },
                        "d3": {
                            "dimensions": {
                                "concept": "eg:TotalCapitalRatio"
                            }
                        },
                        "d4": {
                            "dimensions": {
                                "concept": "eg:SurplusDeficitTier1Capital",
                                "unit": "iso4217:EUR"
                            }
                        },
                        "d5": {
                            "dimensions": {
                                "concept": "eg:SurplusDeficitCET1Capital",
                                "unit": "iso4217:EUR"
                            }
                        },
                        "d6": {
                            "dimensions": {
                                "concept": "eg:SurplusDeficitTotalCapital",
                                "unit": "iso4217:EUR"
                            }
                        }
                    }
                },
                "amount": {
                    "dimensions": {
                        "period": "2018-01-01T00:00:00"
                    },
                    "propertiesFrom": [
                        "item"
                    ]
                }
            }
        }
    },
    "tables": {
        "capital_adequacy_data": {
            "template": "capital_adequacy_template",
            "url": "table11-data-facts.csv"
        }
    },
    "dimensions": {
        "entity": "lei:FAKE0012345678901274"
    }
}

Example 11 - JSON Metadata

The first column item is a "property group column". The metadata defines a set of named groups of dimensions and decimal values, referred to as "property groups". The value for each cell in the column must be the name of one of the defined property groups.

The second column amount specifies an attribute "propertiesFrom" with value item, which specifies that the column will inherit the properties (dimensions and decimal values) from the property group named in the corresponding cell in the item column. The amount column additionally specifies a period dimension. This will be combined with the properties inherited from the property value column.

For example, the fourth value (20) in the amount column will take dimension values from the d4 property group named; the fourth value of the item column, combined with the period dimension value defined on the column, and the entity dimension value defined at the report level.

The fourth value in the amount column (20) will have the following dimension and decimal values:

The use of property groups in this example allows all known dimension values to be defined in the JSON metadata and the CSV table is used only to capture fact values.

The property groups feature is not limited to this style of key-value reporting. There can be multiple property group columns in a template, and a single fact column can refer to more than one property group, which will mean the fact will inherit dimensions from all property groups it refers to. Property groups can be used wherever it is desirable to give a shorthand name for a group of dimension and decimal values.

Note that a property group column (item in this example) cannot also be a fact or parameter value column.

12 Dimension inheritance in xBRL-CSV

We have seen a range of examples that permit dimension values to be defined at report, table, property (row) or column level. In the case where a dimension is defined at multiple different levels, the values will have the following priority:

• Column
• Property Group
• Table
• Report

In other words, a table dimension value will only be used if the dimension is not specified as a column dimension or in property group. Likewise, a report dimension value is only used if the dimension is neither a table, property group nor column dimension. This example demonstrates how dimension inheritance works, and also shows how an inherited value can be removed for specific tables or columns.

Table 12 is an extract of Credit Exposure disclosure. A breakdown of Credit Exposure consists of Cash Credit, Term Loan, Working Capital Loan and Non-Funded Exposure, and is reported for each counterparty (firm). The breakdown of Credit Exposure is modelled as an explicit dimension. The firm identification is modelled as a typed dimension.

The Concept and Taxonomy-defined explicit dimension applicable to each column are as follows:

{
    "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": {
        "credit_exposure_template": {
            "columns": {
                "firm_id": {},
                "Cash_Credit": {
                    "dimensions": {
                        "eg:LoanType": "eg:CashCreditMember"
                    }
                },
                "Term_Loan": {
                    "dimensions": {
                        "eg:LoanType": "eg:TermLoanMember"
                    }
                },
                "Working_Capital_Loan": {
                    "dimensions": {
                        "eg:LoanType": "eg:WorkingCapitalLoanMember"
                    }
                },
                "Non_Funded_Exposure": {
                    "dimensions": {
                        "eg:CreditExposureType": "eg:NonFundedMember"
                    }
                },
                "Total_Exposure": {
                    "dimensions": {
                        "eg:CreditExposureType": "#none"
                    }
                }
            },
            "decimals": 0,
            "dimensions": {
                "eg:Firm": "$firm_id",
                "concept": "eg:CreditExposure",
                "eg:CreditExposureType": "eg:FundedMember"
            }
        }
    },
    "tables": {
        "credit_exposure_table": {
            "template": "credit_exposure_template",
            "url": "table12-data-facts.csv"
        }
    },
    "dimensions": {
        "period": "2018-01-01T00:00:00",
        "entity": "lei:FAKE0012345678901274",
        "unit": "iso4217:EUR"
    }
}

Example 12 - JSON Metadata

The concept dimension is common to all facts in the table, and so is defined as a table dimension. The value of eg:FundedMember for the eg:CreditExposureType dimension is common to most facts in the table, and it is possible to define this value as a table dimension and only specify where the value differs from this.

Facts in the Non_Funded_Exposure column should have a value of eg:NonFundedMember for eg:CreditExposureType dimension. This is specified explicitly as a column dimension, overriding the table dimension value of eg:FundedMember.

In the case of the Total_Exposure column, the dimension eg:CreditExposure has to be omitted. As simply omitting the dimension from the column dimension would cause the table dimension value to be inherited, xBRL-CSV provides a mechanism for explicitly removing an inherited value. This is done by specifying a literal value of #none.

In the Table 12 the first value in the Total_Exposure column (75) will have the following dimension values and decimal property:

Note that if a dimension value is obtained from a parameter column, an empty cell will be equivalent to "#none"; any inherited value will be removed.

13 Fact & Row Identifiers

Open Information Model requires all facts to have a unique identifier. The identifiers are useful in providing traceability of facts through different syntactic representations. This example will demonstrate the concept of providing unique identifiers for the facts and rows in the CSV data file. The Loan Disclosure in Table 13 is same as Table 5.

{
    "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": {},
                "fixed_rate_period": {},
                "loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "2019-01-01T00:00:00"
                    }
                },
                "original_loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "$fixed_rate_period@start"
                    }
                },
                "rate": {
                    "decimals": 4,
                    "dimensions": {
                        "concept": "eg:InterestRate",
                        "period": "$fixed_rate_period"
                    }
                }
            },
            "decimals": 0,
            "dimensions": {
                "eg:LoanId": "$loan_id",
                "entity": "lei:FAKE0012345678901274"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table5-data-facts.csv"
        }
    }
}

Example 13.1 - JSON Metadata

Fact IDs in xBRL-CSV are derived by concatenating table, row and column identifiers, separated by a "." (dot). By default, an identifier of "rN", where N is the row number is used as the row identifiers. The row immediately after the header row (the second row of the table), is row 1 and the following rows are numbered sequentially. The fact identifier for the second value in the original_loan_amount column (1500) will be as shown in Figure 1

Figure 1: Example of fact id with default sequential row numbers

In order to give more meaningful identifiers to facts, it is also possible to use the values of a specific column as row identifiers. The table template definition shown below includes a new property of rowIdColumn, with value loan_id. This means that the values in the column loan_id will be used as the row identifier.

{
    "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": {},
                "fixed_rate_period": {},
                "loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "2019-01-01T00:00:00"
                    }
                },
                "original_loan_amount": {
                    "dimensions": {
                        "concept": "eg:LoanAmount",
                        "unit": "iso4217:EUR",
                        "period": "$fixed_rate_period@start"
                    }
                },
                "rate": {
                    "decimals": 4,
                    "dimensions": {
                        "concept": "eg:InterestRate",
                        "period": "$fixed_rate_period"
                    }
                }
            },
            "decimals": 0,
            "rowIdColumn": "loan_id",
            "dimensions": {
                "eg:LoanId": "$loan_id",
                "entity": "lei:FAKE0012345678901274"
            }
        }
    },
    "tables": {
        "loan_data_table": {
            "template": "loan_data_template",
            "url": "table5-data-facts.csv"
        }
    }
}

Example 13.2 - JSON Metadata

In this case, the fact identifier for the second value in the original_loan_amount column (1500) will be as shown in Figure 2

Figure 2: Example of an fact id with row indentifiers

Note that the value for row indentifiers have a restricted format; they cannot include spaces and must not start with a number.

Appendix A Allowed period formats in xBRL-CSV

Appendix B JSON metadata and CSV tables

The JSON metadata files and corresponding CSV data tables can be found at this link. The filenames for JSON metadata correspond to the example serial number.