xBRL-CSV: mapping from Open Information Model 1.0

Public Working Draft 7 August 2019

This version
Herm Fischer, Mark V Systems Limited <fischer@markv.com>
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
David Bell, Donnelley Financial Solutions <david.x.bell@dfsco.com>
Daniel Dracott, CoreFiling <djd@corefiling.com>
Mark Goodhand, CoreFiling <mrg@corefiling.com>
Paul Hulst, De Nederlandsche Bank N.V. <P.J.Hulst@dnb.nl>
Eleanor Joslin, CoreFiling <ejj@corefiling.com>

Table of Contents

1 Introduction

This document defines a CSV-based representation of the information in an XBRL report, as defined in the XBRL Open Information Model OIM. It provides significant flexibility in the layout of the CSV tables, in order to enable tables that are efficient and intuitive, allowing related facts to be grouped into rows, and share common aspects. The structure of the tables is controlled by a JSON metadata file.

The mapping of an xBRL-CSV report into the OIM report model is described in this specification, enabling lossless transformation of xBRL-CSV reports into other formats, including the XML-based xBRL-XML representation.

It should be noted that the flexibility in table layout means that there are many different ways of representing the same OIM report using xBRL-CSV. It is anticipated that processors performing a transformation into the xBRL-CSV format will require some level of user input into the specification of the metadata file in order to achieve intuitive and efficient tables.

2 Identifiers in xBRL-CSV

xBRL-CSV makes use of QNames to represent expanded names and SQNames to represent some other values. The prefix map for resolving QNames and SQNames is provided by the namespaces object.

3 xBRL-CSV report structure

An xBRL-CSV report is a CSV-based representation of a XBRL report, consisting of a JSON metadata file and zero or more CSV data tables. The metadata file provides links to the data tables that contain the report data, and defines the meaning of the columns in each data table.

An xBRL-CSV report is identified by a path or URL to a metadata file, which in turn contains references to the associated CSV files.

3.1 xBRL-CSV metadata file

An xBRL-CSV metadata file is a JSON file that conforms to the format described in this section. The metadata JSON file name SHOULD have an extension of .json.

An metadata file consists of a JSON object with the following properties:

(required) A documentInfo object.
(required) A tables object.
(optional) A links object.

3.1.1 Metadata: documentInfo

The documentInfo object provides document-level information about the xBRL-CSV report. The object has the following properties:

(required) The fixed value http://xbrl.org/PWD/2019-08-07/xbrl-csv
(optional) A reportDimensions object defining dimension values that are common to all facts in the report.
(required) A namespaces object defining the prefix map for QName and SQName values in this report.
(required) A list of URLs defining the taxonomy for the report.
(optional) An integer providing a value for the {decimals} property of numeric facts in the report. Metadata: namespaces

The namespaces object provides the prefix map for QName and SQName values in this report.

Each key provides a prefix, which is mapped to the URI provided by the value. Metadata: linkTypes

The linkTypes object is a URI map defining URI aliases used to identify link types in this report. Metadata: groups

The groups object is a URI map defining URI aliases used to identify groups in this report. Metadata: reportDimensions

The reportDimensions object provides default dimension values for all facts in a report. The reportDimensions object is a dimensions object.

3.1.2 Metadata: tables

The tables object provides information about the individual data tables in a report.

The keys of the tables object are identifiers. This identifier provides the table identifier for the referenced data table..

Each value is a table object with the following properties:

(required) A URL to the CSV file for this table.
(optional) An identifier specifying the name of the column containing a unique identifier for each row in the table.
(required) A factColumns object.
(optional) An integer providing a value for the {decimals} property of numeric facts in the report.
(required) A tableDimensions object.

3.1.3 Metadata: tableDimensions

The tableDimensions object provides default dimension values for all facts in a table. The tableDimensions object is a dimensions object.

3.1.4 Metadata: factColumns

The factColumns object specifies the fact columns for a table.

Each key of the factColumns object MUST be a column identifier in the corresponding data table.

Each value is a fact column object with the following properties:

(optional) An integer providing a value for the {decimals} property of any numeric facts produced by the column.
(required) A columnDimensions object.

3.1.5 Metadata: columnDimensions

The columnDimensions object provides dimension values for all facts in a column. The columnDimensions object is a dimensions object.

3.1.6 Metadata: dimensions object

A dimensions object is a JSON object that defines a set of dimension values. It defines a common format for reportDimensions, tableDimensions and columnDimensions objects.

A dimensions object has the same format and constraints as an xBRL-JSON dimensions object, except as noted below.

A dimensions object defines a set of dimension values which map to the {dimensions} property of facts as described in Section 4.2.5.

If the value of a dimension starts with $ (but not $$), and the object is a columnDimensions or tableDimensions object, then the value MUST take one of the following forms:

Where column and period-specifier are identifiers. column MUST be the column identifier for a column in the same table. If present, period-specifier MUST be either start or end.
The value for the dimension is determined by the cell, C, which is in the column specified by column and the current row, as follows:

If the value of a dimension starts with $$ then it is treated as a literal $.

If the value of a dimension is #none, the dimension has an explicit no-value.

An explicit no-value for a dimension is equivalent to not specifying the dimension at all in the dimensions object, except that it also prevents inheritance of a value for that dimension from another location (see Section 4.2.5).

If the value of a dimension starts with ## then it is treated as a literal #.

See Appendix A for a summary of the special values available in different contexts.

In addition to the syntax supported by xBRL-JSON, the period dimension supports a number of additional formats, described in Section Period formats

The period dimension may be specified in a number of different formats. Either of the date time-based formats permitted by xBRL-JSON may be used:

In addition, a number of abbreviated forms may be used to specify a duration:

Time zone specifiers MUST NOT be included in any of the abbreviated forms.

Examples of these abbreviated forms, and their equivalent ISO8601 date time forms, are shown below:

xBRL-CSV format Period type Equivalent date time-based representation Notes
2019-01-01..2019-12-31 duration 2019-01-01T00:00:00/2020-01-01T00:00:00 inclusive date range
2019-06-01 duration 2019-06-01T00:00:00/2019-06-02T00:00:00 duration of a single day
2019-06 duration 2019-06-01T00:00:00/2019-07-01T00:00:00 calendar month
2019 duration 2019-01-01T00:00:00/2020-12-31T00:00:00 calendar year
2019Q2 duration 2019-04-01T00:00:00/2019-07-01T00:00:00 calendar quarter
2019H1 duration 2019-01-01T00:00:00/2019-07-01T00:00:00 calendar half
2019W29 duration 2019-07-15T00:00:00/2019-07-22T00:00:00 ISO week

The links object defines relationships between facts in the report.

The object has the following form:

The links object defines a list of relationships between S and each fact in TF, with link type G and link type T.

3.2 CSV data tables

A data table is a CSV file that is referenced by table object in a metadata file. Data tables are interpreted as described in this section.

3.2.1 File format

CSV files MUST follow the format defined in RFC 4180, with the following modifications:

This gives the following modified version of the RFC 4180 ABNF grammar:

file = [header line-end] record *(line-end record) [line-end]

header = name *(COMMA name)

record = field *(COMMA field)

name = field

field = (escaped / non-escaped)


non-escaped = *TEXTDATA

COMMA = %x2C

CR = %x0D

DQUOTE = %x22

LF = %x0A

line-end = (CR LF) / CR / LF 

TEXTDATA = %x09 / %x20-21 / %x23-2B / %x2D-D7FF / %xE000-FFFD / %x10000-10FFFF

3.2.2 Structure

The first row in a CSV file is the header row. Each cell in the header row MUST either be empty, or contain a valid identifier.

Each value in the header row provides a column identifier for the column.

A fact column is a column with a column identifier that is a key of the factColumns object for the table.

3.2.3 Cell values

A cell has a value if it falls within the range of data provided in the CSV file and has a literal value of anything other than the empty string or the string #none.

Otherwise, the following special treatment is applied to cell values:

See Appendix A for a summary of the special values available in different contexts.

3.2.4 Identifiers

An identifier is a value used to identify a table, row or column. Identifiers MUST be a valid NCName and MUST NOT contain the . character.

4 Mapping from xBRL-CSV to OIM

This section describes how an xBRL-CSV document is mapped to an OIM Report model. The starting point of the model is the report component, which corresponds to an xBRL-CSV report.

4.1 Report component

The report component has the following properties:

The list of URLs that is the value of the taxonomy member of the documentInfo object.
The union of the sets of facts defined by each data table in the xBRL-CSV report (see Section 4.2).

4.2 Facts

Each cell in a fact column of a data table that has a value is mapped to an fact component, with the properties described in Section 4.2.2.

4.2.1 Definitions

4.2.2 Fact properties

The fact has the following properties:

See Section 4.2.3.
See Section 4.2.5.
See Section 4.2.6.
The value of the cell, after applying the treatment described in Section 3.2.3
A set of link groups containing all relationships defined in the links object for which the current fact is the source.

4.2.3 Fact identifiers

The {id} property for a fact is in an xBRL-CSV report is the concatentation of the table identifier for the current table, the row identifier for the current row and the column identifier for the current column, separated by ., i.e.:


4.2.4 Row identifiers

A row identifier provides a unqiue identifier for a row that is used, in combination with the table identifier and column identifier to produce fact identifiers. The row identifier for the current row is:

The row number for a row is an integer corresponding to the position of the row within the table, with the value 1 corresponding to the row immediately after the header row (i.e. the second row of the table), and other rows numbered sequentially.

If a rowIdColumn is provided, the values in the column have the following constraints:

4.2.5 Fact dimensions

The {dimensions} property of a fact consists of the union of dimension values defined in the following locations:

  1. The columnDimensions object for the current column.
  2. The tableDimensions object for the current table.
  3. The reportDimensions object.

If multiple locations include the same dimension for a single fact, then the first location (considered in the order listed above) that specifies either a value or an explicit no-value is used.

4.2.6 Decimals

The {decimals} property of a numeric fact is determined by the first of the following properties that is present:

  1. The decimals property of the fact column object for the current table.
  2. The decimals property of the table object for the current table.
  3. The decimals property of the documentInfo object.

If no such property exists, the value of the {decimals} property is "infinite".

Otherwise, the value of the decimals property is interpretted as follows:

Appendix A Syntax for special values (non-normative)

The table below shows a summary of the special values that are available for use as cell values in CSV files and xBRL-CSV metadata files. For reference, the equivalent representation in xBRL-JSON is also included.

Unles otherwise stated, all values in monospaced font are string literals. This means that in JSON files they should be enclosed between quotation marks.

Meaning In CSV files In xBRL-CSV metadata (JSON) In xBRL-JSON
Value from CSV column col n/a $col n/a
Period start from CSV column col n/a $col@start n/a
Period end from CSV column col n/a $col@end n/a
Nil value of fact/dimension #nil null (JSON literal) or #nil null (JSON literal)
Empty string #empty Empty string or #empty Empty string
The string literal #val ##val ##val #val
The string literal val# val# val# val#
The string literal $val $val $$val $val
The string literal val$ val$ val$ val$
Nonexistent fact Empty cell n/a No fact object
Decimals value of 3 3 3 (JSON number) 3 (JSON number)
Infinite decimals Empty cell or #inf #inf No decimals property
Inherit decimals (defaults to infinite) n/a4 No decimals property1 n/a
Absent dimension Empty cell or #none #none2 No property for dimension
Inherit dimension n/a4 No property for dimension1 n/a
No period3 Empty cell or #none #none2 No period property
Inherit period n/a4 No period property1 n/a
No entity3 Empty cell or #none #none2 No entity property
Inherit entity n/a4 No entity property1 n/a
No unit3 Empty cell or #none #none2 No unit property
Inherit unit n/a4 No unit property1 n/a


  1. When specifying xBRL-CSV metadata, omitting a property for a dimension or decimals will result in the value being inherited from higher-level metadata, if any. If no such value exists, the fact will not have that dimension (or in the case of decimals will have the value "infinite").
  2. Specifying a property in xBRL-CSV metadata with a value of #none (an explicit no-value) overrides any inherited value. Facts will not have the corresponding dimension (or will have infinite decimals), even if a value is specified in higher-level metadata.
  3. Period, entity and unit are optional in the Open Information Model, but are required for some or all facts in xBRL-XML. xBRL-XML defines specific values for the XML syntax that map to the absence of these dimensions in the model.
  4. Where xBRL-CSV metadata specifies that the value for a dimension (or decimals) is to be obtained from a column in the CSV file (using the "$col" notation), it is not then possible to inherit a value for that dimension. An empty cell in the relevant column will result in the absence of that dimension (or infinite decimals).

Appendix B Example xBRL-CSV report (non-normative)

The table below shows an example data set:

Loan ID Firm ID Country of incorporation Local currency Fixed Rate period Deposit amount (home currency) Deposit amount (local currency) Loan to value Rate
L001 09209384832 GB GBP 2017-01-01 to 2019-12-31 €1,000 2,100 45.6% 5.1%
L002 12312312123 FR EUR 2017-06-21 to 2019-03-20 €1,100 1,374 38.8% 4.6%
L003 02393823489 DE EUR 2017-07-01 to 2017-12-31 €800 871 34.8% 4.3%

Appendix B.1 Metadata example

A sample metadata file for the above table is shown below.

    "documentInfo": {
        "documentType": "http://xbrl.org/YYYY/xbrl-csv",
        "namespaces": {
            "ld": "http://xbrl.org/oim/conformance/firm-loans",
            "lei": "http://standards.iso.org/iso/17442",
            "iso4217": "http://www.xbrl.org/2003/iso4217"
        "reportDimensions": {
            "entity": "lei:00EHHQ2ZHDCFXJCPCL46"
        "taxonomy": [
    "tables": {
        "loan_data": {
            "factColumns": {
                "country_inc": {
                    "columnDimensions": {
                        "concept": "ld:CountryOfIncorporation"
                "deposit_amount_hc": {
                    "columnDimensions": {
                        "concept": "ld:DepositAmount",
                        "period": "$fixed_rate_period@start",
                        "unit": "iso4217:EUR"
                "deposit_amount_lc": {
                    "columnDimensions": {
                        "concept": "ld:DepositAmount",
                        "period": "$fixed_rate_period@start",
                        "unit": "$local_currency"
                "ltv_end_fr": {
                    "decimals": 3,
                    "columnDimensions": {
                        "concept": "ld:ExpectedLoanToValueRatio",
                        "period": "$fixed_rate_period@end"
                "rate": {
                    "decimals": 4,
                    "columnDimensions": {
                        "concept": "ld:InterestRate",
                        "period": "$fixed_rate_period"
            "rowIdColumn": "loan_id",
            "tableDimensions": {
                "ld:Firm": "$firm"
            "url": "loan-data-facts.csv"

Appendix B.2 CSV Example

Corresponding CSV data (load-data-facts.csv) is shown below: