xBRL-CSV: CSV representation of XBRL data 1.0

Recommendation 13 October 2021
with errata corrections to 19 April 2023

This version
https://www.xbrl.org/Specification/xbrl-csv/REC-2021-10-13+corrected-errata-2023-04-19/xbrl-csv-REC-2021-10-13+corrected-errata-2023-04-19.html
Editors
Herm Fischer, Mark V Systems Limited <fischer@markv.com>
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
Mark Goodhand, CoreFiling <mrg@corefiling.com>
Contributors
David Bell, UBPartner SAS <dbell@ubpartner.com>
Daniel Dracott, CoreFiling <djd@corefiling.com>
Paul Hulst, De Nederlandsche Bank N.V. <P.J.Hulst@dnb.nl>
Eleanor Joslin, CoreFiling <ejj@corefiling.com>

Table of Contents

Definitions

Error codes

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.

1.1 Documentation conventions

1.1.1 Error codes

QNames in parenthetical red text after a "MUST" or "MUST NOT" statement prescribe standardised error codes to be used if the preceding condition is violated. "MUST" or "MUST NOT" statements that do not have a prescribed error code are not automatically enforceable, and processors are not required to detect violations.

1.2 Namespaces and namespace prefixes

xBRL-CSV makes use of QNames to represent expanded names and SQNames to represent some other values. The prefix map for resolving QNames, SQNames and other prefixed content is provided by the namespaces object. Any prefixes used by QNames or SQNames are resolved as described in OIM Common.

Prefixes used in this specification are to be interpreted according to the following table:

Prefix Namespace URI
xbrl https://xbrl.org/2021
xbrli http://www.xbrl.org/2003/instance
xs http://www.w3.org/2001/XMLSchema
xbrlce https://xbrl.org/2021/xbrl-csv/error

1.3 URIs and URI aliases

The xBRL-JSON format makes use of URI aliases as an abbreviated representation of URIs, as described in OIM Common. The table below defines reserved URI aliases for the linkTypes and linkGroups URI maps.

URI alias URI
footnote http://www.xbrl.org/2003/arcrole/fact-footnote
explanatoryFact http://www.xbrl.org/2009/arcrole/fact-explanatoryFact
_ http://www.xbrl.org/2003/role/link

2 Validation

On encountering a document with the xBRL-CSV document type an xBRL-CSV processor MUST raise errors with the specified error codes if the document does not conform to the constraints defined in this specification. Additionally, such a processor MUST perform the validation required of a conformant processor. A processor MAY apply the validation required of a validating conformant processor.

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, referred to as the primary metadata file.

The metadata file may optionally extend other metadata files in order to reuse definitions that are common to multiple xBRL-CSV reports.

The metadata files contain 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. A metadata file name SHOULD have an extension of .json.

3.1.1 JSON representation constraints

xBRL-CSV metadata files MUST be valid JSON, per RFC 8259 (xbrlce:invalidJSON).

In order to avoid interoperability issues, objects within JSON documents conforming to this specification MUST have unique keys (xbrlce:invalidJSON).

JSON documents MUST use the UTF-8 character encoding (xbrlce:invalidJSON), and MAY include a Unicode Byte Order Mark, although this is neither required nor recommended.

This specification documents the allowed types for all values in JSON metadata. Types are specified as a combination of JSON primitive types (string, array, object, number, boolean and null) and an optional XML Schema built-in simple type, identified by a QName. Values within JSON documents MUST have the JSON type specified and, where an XML Schema type is specified, MUST be in the canonical lexical representation for that type (xbrlce:invalidJSONStructure). Note that values for facts and taxonomy-defined dimensions are not required to be in canonical form.

Properties marked as "required" MUST be present wherever the enclosing object is present (xbrlce:invalidJSONStructure).

3.1.2 Document type identification

A document has the xBRL-CSV document type if it is a valid JSON document in which the JSON Pointer /documentInfo/documentType resolves to the string https://xbrl.org/2021/xbrl-csv. A document that does not have the xBRL-CSV document type MUST be treated as described in OIM Common and the errors defined in this specification MUST NOT be raised, aside from xbrlce:invalidJSON (see Section 3.1.1).

3.1.3 Extensibility

In order to facilitate the inclusion of additional information within the metadata file, additional properties beyond those defined in this specification MAY be included within the following objects:

Any such additional properties included in the above objects MUST have names that are QName values (xbrlce:invalidJSONStructure), and unless defined in a specification published by XBRL International MUST have a prefix that identifies a namespace that does not use the xbrl.org domain name.

The content of any such additional properties is not constrained by this specification.

Where xBRL-CSV metadata is split across multiple files (see Section 3.1.18), any extension properties are required to follow the same constraints as other non-extensible properties. This means that where the same property appears in multiple files, it must have the same value.

3.1.4 Metadata: report structure

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

documentInfo (object)
(required) A documentInfo object.
tableTemplates (object)
(optional) A tableTemplates object.
tables (object)
(optional) A tables object.
parameters (object)
(optional) An object that provides metadata report parameters. See Section 3.1.13.
parameterURL (string)
(optional) An xs:anyURI that provides the location of a CSV file containing CSV report parameters. See Section 3.1.13.
dimensions (object)
(optional) A dimensions object that defines report dimensions. Report dimensions provide default dimension values for all facts in a report.
decimals (number or string)
(optional) A decimals value providing a default value for the {decimals} property of numeric facts in the report.
links (object)
(optional) A links object.

Additional properties are allowed, subject to the constraints in Section 3.1.3.

3.1.5 Metadata: documentInfo

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

documentType (string)
(required) The fixed value https://xbrl.org/2021/xbrl-csv
namespaces (object)
(optional) A namespaces object.
linkTypes (object)
(optional) A linkTypes object.
linkGroups (object)
(optional) A linkGroups object.
taxonomy (array)
(optional) An array of URLs (xs:anyURI) defining the taxonomy for the report. Relative URLs are resolved relative to the file in which the property appears.
extends (array)
(optional) An array of URLs (xs:anyURI) of other xBRL-CSV metadata files. The current metadata file is combined with the referenced files, as described in Section 3.1.18. Relative URLs are resolved relative to the file in which the property appears. If a URL in the extends property cannot be resolved, a processor MUST raise xbrlce:unresolvableBaseMetadataFile. A processor MAY make use of URL remappings when resolving URLs.
final (object)
(optional) A final object, specifying objects that cannot be extended by an importing metadata file (see Section 3.1.18).
features (object)
(optional) a features object, indicating additional constraints to which this document conforms (see Section 5).
baseURL (string)
(optional) a URL (xs:anyURI) providing a base URL for the report (see Section 3.1.5.7).

Additional properties are allowed, subject to the constraints in Section 3.1.3.

Processors MUST support http, https and file URLs in the taxonomy and extends properties. Processors MAY support other schemes, but such use is discouraged as they may not be supported in all processors. Use of absolute file URLs is also discouraged, as reports using this are unlikely to be portable.

3.1.5.1 Metadata: documentInfo/namespaces

The namespaces object is a URI map object that provides the prefix map for QNames, SQNames and other prefixed content values.

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

The prefix map for all QName, SQName and other prefixed content values in an xBRL-CSV report is provided by the namespaces object in the effective metadata of the primary metadata file.

Note that this means that such values appearing in a metadata file MAY rely on prefixes that are only declared in a metadata file that imports it.

3.1.5.2 Metadata: documentInfo/linkTypes

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

The URI map for a URI alias for a link type is the linkTypes object in the effective metadata of the primary metadata file.

3.1.5.3 Metadata: documentInfo/linkGroups

The linkGroups object is a URI map object defining URI aliases used to identify link groups in this report.

The URI map for a URI alias for a link group is the linkGroups object in the effective metadata of the primary metadata file.

3.1.5.4 Metadata: URI map object

A URI map object is a JSON object providing a map of URI aliases to full URIs. The content of the URI map MUST conform to the constraints defined in OIM Common for URI maps.

The keys of the object (xs:NCName) provide the URI alias to be defined, and the values (xs:anyURI) provide the URI to be associated with the alias.

Additional properties MUST NOT be included (xbrlce:invalidJSONStructure).

3.1.5.5 Metadata: documentInfo/final

The final object defines objects and arrays which cannot be extended in importing files. The object has the properties shown in the table below. All properties are optional, and if present take the fixed value of true, indicating that the corresponding object or array cannot be extended by importing metadata files (see Section 3.1.18).

Property name Corresponding JSON property Notes
namespaces /documentInfo/namespaces
taxonomy /documentInfo/taxonomy
linkTypes /documentInfo/linkTypes
linkGroups /documentInfo/linkGroups
features /documentInfo/features
tableTemplates /tableTemplates
tables /tables
dimensions /dimensions Note that this refers to the root-level dimensions object that defines report dimensions only.
parameters /parameters
parameterURL /parameterURL

The table above uses JSON Pointer notation to specify the objects controlled by each property name.

Additional properties MUST NOT be included (xbrlce:invalidJSONStructure).

3.1.5.6 Metadata: documentInfo/features

The features object indicates additional constraints to which the report conforms, beyond those required for xBRL-CSV itself. See Section 5 for more information.

The properties of the object are xs:QName values, corresponding to the name of a feature. The values can be any non-null JSON value, indicating the state of the feature. A value of false is equivalent to omitting the property, and indicates that the feature is disabled. Any other value indicates that the feature is enabled. Values other than true may be used to indicate specific additional properties of the feature.

3.1.5.7 Metadata: documentInfo/baseURL

If present, the baseURL property provides the value of the {base-url} property for the {report}. Otherwise, the {base-url} property for the {report} may optionally be set to the absolute URL of the primary metadata file.

When creating an xBRL-CSV report from an OIM report model, this baseURL may optionally be set to the {base-url} property for the {report}, if any, and MUST be absent otherwise.

The baseURL property enables the meaning of relative URLs in fact and dimension values to be preserved. The baseURL property does not play any role in resolving URLs that appear within xBRL-CSV metadata. See also Section 3.1.18.2.

3.1.6 Metadata: tableTemplates

The tableTemplates object provides table template definitions.

A table template defines the structure of a table that may be included in an xBRL-CSV report. Each CSV data table is the instantiation of a table template in a CSV file. Each table template may be used by zero or more tables with the report.

The keys of the tableTemplates object MUST be identifiers (xbrlce:invalidIdentifier) and provide a unique table template identifier for each table template.

Each value is a table template object with the following properties:

rowIdColumn (string)
(optional) An identifier specifying the name of the row ID column. A row ID column provides a unique identifier for each row, and is used to construct the {id} property for each fact in a table, as described in Section 4.2.3. The value of the rowIdColumn property MUST be the name of a property in the columns object (xbrlce:undefinedRowIdColumn). The referenced column MUST NOT be a comment column (xbrlce:invalidRowIdColumn).
columns (object)
(required) A columns object.
decimals (number or string)
(optional) A decimals value.
dimensions (object)
(optional) A dimensions object that defines table dimensions. Table dimensions provide default dimension values for all facts in a table.

Additional properties are allowed, subject to the constraints in Section 3.1.3.

3.1.7 Metadata: tableTemplates/columns

The columns object specifies the columns that may appear in a table.

Keys of the columns object MUST be identifiers (xbrlce:invalidIdentifier).

Each value is a column object with the following properties:

comment (boolean)
(optional) A boolean value indicating that the column is a comment column. Defaults to false.
decimals (number or string)
(optional) A decimals value providing a default value for the {decimals} property of any numeric facts produced by the column.
dimensions (object)
(optional) A dimensions object that defines column dimensions. Column dimensions provide dimension values for all facts in a fact column.
propertyGroups (object)
(optional) A property groups object defining named fact property group that may be used in the column (see Section 3.1.10).
propertiesFrom (array of strings)
(optional) An array of xsd:string values providing the names of property group columns providing decimal and dimension values for facts produced by the column (see Section 4.2.6 and Section 4.2.5). If present, the members of the array MUST be the names of property group columns in the same table template (xbrlce:invalidPropertyGroupColumnReference).

Additional properties are allowed, subject to the constraints in Section 3.1.3.

If either of dimensions or propertiesFrom are present then the column is a fact column. Note that the dimensions object MAY be empty.

The decimals property MUST NOT be present unless the column is a fact column (xbrlce:misplacedDecimalsOnNonFactColumn).

If the propertyGroups property is present then the column is a property group column.

If either the dimensions or propertiesFrom properties are present then the propertyGroups property MUST NOT be present (xbrlce:conflictingColumnType).

A column object MAY be empty. This declares a column that MAY be included in a corresponding CSV data table (see Section 3.2.2), but which is not a fact column or a property group column.

If the comment property is present and set to true then the column is a comment column. Comment columns permit the inclusion of data in CSV data tables that does not make a contribution to the report model (see Section 3.2.5).

If propertyGroups, propertiesFrom or dimensions is present, then comment MUST be absent, or set to false (xbrlce:conflictingColumnType).

It is intended that comment columns are used for information that is only useful to the preparer of the report, rather than the consumer. Information intended for consumption by others should be included as XBRL facts.

3.1.8 Metadata: dimensions object

A dimensions object is a JSON object that defines a set of dimension values.

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

The dimensions object has the following properties and JSON values types:

concept (string)
Provides a value for the concept core dimension.
entity (string)
Provides a value for the entity core dimension.
period (string)
Provides a value for the period core dimension.
unit (string)
Provides a value for the unit core dimension.
language (string)
Provides a value for the language core dimension.
Any QName (string or null).
Provides a value for a taxonomy-defined dimension. Note that as in xBRL-JSON all values (with the exception of null values) are represented as a JSON string providing a valid lexical representation for the relevant XML Schema datatype, including those based on numeric and boolean datatypes. The key for this property MUST have a prefix, and the prefix MUST NOT be xbrl (xbrlce:invalidJSONStructure).

Additional properties MUST NOT be included (xbrlce:invalidJSONStructure).

Note that noteId is not permitted in the dimensions object. The value of the note ID core dimension is inferred from the fact ID (see Section 4.2.5).

If a value starts with $ (but not $$) then it MUST be either a parameter reference or a row number reference (xbrlce:invalidReference).

The value of each property undergoes the processing defined below in order to obtain a resolved value:

The result of the above processing may be 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).

The following constraints listed below apply to the resolved value for each property. Where the resolved value is obtained from a parameter reference or a row number reference, the constraints are only applied if the value is used as a dimension value, as described in Section 4.2.5. For other values, the constraints are applied to all dimensions objects appearing in the effective metadata of the primary metadata file.

concept
The resolved value MUST be a valid QName (xbrlce:invalidConceptQName).
entity
The resolved value MUST be an explicit no-value or a valid SQName (oimce:invalidSQName).
period
The resolved value MUST be an explicit no-value or a string conforming to one of the period formats described in Section 3.1.16.2 (xbrlce:invalidPeriodRepresentation).
unit
The resolved value MUST be an explicit no-value or a string conforming to the unit string representation format (oimce:invalidUnitStringRepresentation).
language
The resolved value MUST be an explicit no-value or a valid BCP 47 language code (xbrlce:invalidLanguageCode).
Any QName
If the dimension identified by the property is an explicit taxonomy-defined dimension, the resolved value MUST be an explicit no-value or a valid QName that is not the default member for that dimension (xbrlce:invalidDimensionValue). Otherwise, the resolved value MUST be an explicit no-value, nil or a value that is a valid lexical representation for the XML Schema datatype of the typed taxonomy-defined dimension (xbrlce:invalidDimensionValue). If the dimension is not a nillable, typed taxonomy-defined dimension the resolved value MUST NOT be nil (xbrlce:invalidDimensionValue). If the value is prefixed content, any prefixes MUST be defined in the namespaces object (oimce:unboundPrefix).

Where a value that is not used by a fact is validated, constraints from the OIM specification that can be applied without reference to other dimension values are applied in addition to the xbrlce constraints listed above. Specifically, this means that processors MUST apply the validation associated with the following OIM error codes, and MUST NOT attempt further validation unless the dimension value is used by a fact:

The implication of the above is that literal values are always validated even if they are in an unreferenced template, or they can be determined to be an excluded dimension. Values obtained via a parameter reference are only validated if used. Note that this means that, for example, validation errors in a unit dimension obtained via a parameter reference are not raised if the unit dimension is excluded based on the concept.

Validation of the OIM constraints listed above is done with respect to the taxonomy identified by the taxonomy member of the documentInfo object in the effective metadata of the primary metadata file (see Section 4.1). This means that this validation cannot be applied to a metadata file in isolation, as the taxonomy may be modified by a file that extends the current file. QNames and SQNames must also be validated in the context of the primary metadata file as it is possible, although not recommended, that the necessary namespace prefixes are only defined in an extending metadata file.

3.1.9 Metadata: decimals values

A decimals value provides a value for the {decimals} property of numeric facts and MUST have one of the following forms: (xbrlce:invalidDecimalsValue)

Note that this prohibits the use of #nil and #empty as cell values (Section 3.2.3) for the target of parameter references. Where a numeric decimals value is defined directly in JSON it MUST be a JSON number. Where a numeric decimals value is obtained via a parameter reference, either from a CSV file or from JSON metadata, the target MUST be a string that is valid according to the xs:integer datatype.

3.1.10 Metadata: property groups object

A property groups object is a JSON object that defines a set of named fact property groups.

A fact property group is a set containing an optional decimals value and zero or more dimension values.

The keys of a property groups object MUST be identifiers (xbrlce:invalidIdentifier) and provide names for the associated fact property groups. Each value of a property groups object is a JSON object that defines a fact property group and has the following properties:

decimals
(optional) A decimals value providing a default value for the {decimals} property for any numeric facts produced by fact columns that reference this fact property group.
dimensions
(optional) A dimensions object that provides dimension values for facts produced by fact columns that reference this fact property group.

Additional properties are allowed, subject to the constraints in Section 3.1.3.

3.1.10.1 Validation of multiple fact property groups

Where the propertiesFrom property of a column object specifies more than one property group column, then there MUST NOT exist a dimension in any of the fact property groups defined by one of those columns which also exists in any of the fact property groups in any of the other columns (xbrlce:repeatedPropertyGroupDimension).

Similarly, the decimals property MUST appear in at most one of the sets of fact property groups defined by the referenced property group columns (xbrlce:repeatedPropertyGroupDecimalsProperty).

3.1.11 Metadata: tables object

The tables object associates table template definitions with CSV data tables .

The keys of the tables MUST be identifiers (xbrlce:invalidIdentifier) and provide a unique table identifier for each data table.

Each value is a table object with the following properties:

url (string)
(required) A URL (xs:anyURI) to the CSV file for this table. Relative URLs are resolved relative to the primary metadata file.
template (string)
(optional) A table template identifier. If this property is omitted, then it defaults to the table identifier. The value MUST be the identifier of a table template present in the effective metadata of the file in which the table object appears (xbrlce:unknownTableTemplate).
optional (boolean)
(optional) A boolean value indicating that the CSV file specified by the url property is not required to exist. Defaults to false. If false, the file specified MUST exist (xbrlce:missingRequiredCSVFile).
parameters (object)
(optional) An object that provides table parameters. See Section 3.1.12.

Additional properties are allowed, subject to the constraints in Section 3.1.3.

3.1.12 Metadata: tables/*/parameters (table parameters)

A table parameter is a table-wide value that can be referenced in the table template definition for the table.

The keys and values of the parameters object provide the names and values for the table parameters, respectively.

Names for table parameters MUST be identifiers (xbrlce:invalidIdentifier).

Values for table parameters MUST be JSON strings (xbrlce:invalidJSONStructure)

3.1.13 Metadata: parameters (report parameters)

A report parameter is a report-wide value that can be referenced in any table template definition.

Report parameters can be either metadata report parameters or CSV report parameters.

A metadata report parameter is a parameter specified in the parameters JSON object (see Section 3.1.4).

The keys and values of the parameters JSON object provide names and values for the metadata report parameters, respectively. Values MUST be a JSON string (xbrlce:invalidJSONStructure).

A CSV report parameter is a parameter defined in the CSV file specified by the parameterURL property (see Section 3.1.4).

The parameterURL property is treated as a URL to a CSV file, as defined in Section 3.2.1. Relative URLs are resolved relative to the primary metadata file. The specified file MUST exist (xbrlce:missingParametersFile).

The file MUST conform to the following constraints: (xbrlce:invalidParameterCSVFile)

Where the first field in a row other than the first row is not empty, the first and second fields of the row provide the name and value of a CSV report parameter, respectively.
The names MUST be unique within the file (xbrlce:invalidParameterCSVFile).

Note that the special value of #empty can be used in a CSV file to specify the empty string as a value for a CSV report parameter. Similarly, the absence of a dimension, or an infinite decimals value can be specified for a CSV report parameter using #none.

Names for report parameters MUST be identifiers (xbrlce:invalidIdentifier).

3.1.13.1 Report parameters example

An example report parameter CSV file is shown below:

name,value
default_decimals,-3
entityLEI,254900ARU0VC1WY6GJ71
default_units,iso4217:EUR

Referencing this CSV file using the parameterURL property is equivalent to including the following parameters object in the report metadata:

{
    "parameters": {
        "default_decimals": "-3",
        "entityLEI": "254900ARU0VC1WY6GJ71",
        "default_units": "iso4217:EUR"
    }
}

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.1.15 Parameter references

A parameter reference has one of the following forms:

Where parameter-name is an identifier, and period-specifier, if present, MUST be either start or end (xbrlce:invalidPeriodSpecifier).

Parameter references are resolved according to the effective metadata of the primary metadata file of an xBRL-CSV report. This allows the value for a parameter reference to be provided by a metadata file that extends the metadata file in which the parameter reference appears (see Section 3.1.18).

The errors listed below relating to the resolution of parameter references MUST only be reported if the parameter is used to obtain a value for a fact property, as described in section Section 4.2.2.

When resolving a parameter reference, parameter-name MUST be at least one of the following (xbrlce:invalidReferenceTarget):

The value of the parameter reference is determined as follows:

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

3.1.15.1 Parameter reference example

The following metadata extra shows how parameter references can be used as part of a tableTemplate definition:

{
    "parameters": {
        "report_period": "2020-06-01..2021-05-31",
    },
    "tableTemplates": {
        "AssetsTable": {
            "columns": {
                "asset_class": { },
                "opening_balance": {
                    "dimensions": {
                        "concept": "eg:AssetValue",
                        "period": "$report_period@start"
                    }
                },
                "closing_balance": {
                    "dimensions": {
                        "concept": "eg:AssetValue",
                        "period": "$report_period@end"
                    }
                }
            },
            "dimensions": {
                "eg:AssetClass": "$asset_class"
            }
        }
    }
}

The AssetsTable defines a table dimension of eg:AssetsClass. All facts from this table will have this dimension, with a value taken from the asset_class column.

The period for the facts is obtained from the report_period report parameter, with facts for the eg:AssetValue concept being reported at both the start and end instants from the period.

3.1.16 Row number reference

A row number reference is denoted by the following string:

The value of a row number reference is the row number for the current row.

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

3.1.16.1 Row number reference example

The row number reference mechanism provides a convenient unique identifier for a row, and can be used to group values from the same row. For example, the table below shows a table of names and values:

Name Amount
Amy 37,000
John 13,000
James 42,000

This could be modelled using two concepts (e.g. Name and Amount) and a typed dimension (e.g. PersonID) taking an integer value to associate names with values. The following extract from a tableTemplate metadata definition shows how rowNumber can be used to provide unique values for a typed dimension. The Name and Amount facts for each row will have the same value for the PersonID dimension, corresponding to the row number.

{
    "columns": {
        "Name": {
            "dimensions": {
                "concept": "eg:Name"
            }            
        },
        "Amount": {
            "dimensions": {
                "concept": "eg:Amount",
                "unit": "iso4217:EUR"
            }            
        }
    },
    "dimensions": {
        "eg:PersonID": "$rowNumber"
    }
}

3.1.16.2 Period formats

The following formats are permitted for specifying periods in xBRL-CSV:

A suffix of @start or @end may be added to any of the abbreviated formats, specifying the instant at the start or end end of the duration, respectively.

Time zone specifiers MUST NOT be included in any formats except the period string representation.

Examples of these abbreviated forms, and their equivalent ISO 8601 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-01-01T00: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
2019W29@start instant 2019-07-15T00:00:00 Start of ISO week
2019Q2@end instant 2019-07-01T00:00:00 End of calendar quarter

3.1.17 Identifiers

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

3.1.18 Extending metadata

In order to allow reuse of common definitions, xBRL-CSV metadata may be split across multiple JSON metadata files. The metadata file for a report may reference another metadata file via the extends property on the documentInfo object. Referenced metadata files may in turn extend other metadata files, forming a chain. A metadata file MUST NOT extend itself, either directly or indirectly (xbrlce:cycleInExtensionChain).

The effective metadata for a metadata file consists of the metadata defined in that file combined with that of any metadata files that are referenced directly or indirectly from that file via the extends property. The process for combining metadata files is described in this section. For the purposes of the above, the /documentInfo/extends property is not considered to be part of the metadata defined by a metadata file.

When a metadata file, X, extends a list of other metadata files, YY, the properties of the following objects in X are combined with the corresponding object in the effective metadata of each metadata file, Y, in YY (this list uses JSON Pointer notation):

If a key exists in one of the above objects in X that also exists in the corresponding object in the effective metadata of Y, the properties MUST have the same value (xbrlce:conflictingMetadataValue).

If the same key exists for corresponding objects in the effective metadata of multiple files in YY, then the properties MUST have the same value (xbrlce:conflictingMetadataValue).

The following array of X is extensible:

The value of this array in the effective metadata of X is the concatenation of the value of this array in each Y in YY, in order, followed by the value of the array in X, with duplicates removed to leave only the first occurrence. De-duplication is performed after resolving any relative URLs. URLs in the documentInfo/taxonomy property are resolved relative to the file in which the property appears, as per Section 3.1.5.

A base file, Y, MAY specify that a JSON property is final (see the final object). In this case, if the specified property is present in the effective metadata of Y then it MUST be present in the effective metadata of X with the same value; otherwise, it MUST be absent (xbrlce:illegalExtensionOfFinalProperty).

Although the final object itself cannot be marked final, it still respects the constraint that once defined, keys cannot be altered during extension. This means that X inherits, and can only add to, final definitions from Y. If another metadata file, Z, extends X, Z cannot extend any objects that are specified as being final in either X or Y.

The documentInfo object MUST appear in all metadata files and MUST have at least the documentType property (see Section 3.1.2). All metadata files that contribute to the effective metadata of the primary metadata file MUST have the same value for the documentType property (xbrlce:multipleDocumentTypesInExtensionChain).

All properties not listed above are not extensible. With the exception of the `/documentInfo/documentType property, which is handled as described above, if a property exists in both the metadata of X and the effective metadata of Y, or in the effective metadata of multiple files in YY then all occurrences MUST have the same value (xbrlce:illegalRedefinitionOfNonExtensibleProperty).

Note that references to "same value" require deep equality of JSON values. Objects MUST have the same properties, and each property MUST have the same value. JSON numbers MUST be compared as numbers (i.e. 2.0 and 2 are the same).

3.1.18.1 Table template extensibility

It should be noted that whilst an extending metadata file cannot modify the definition of a table template from another file, it can add additional dimensions to an imported table template by specifying them as report dimensions. If this is undesirable, the base file should include dimensions in final.

3.1.18.2 URL resolution

Processors SHOULD use remappings provided by XBRL Taxonomy Packages when resolving URLs that appear within xBRL-CSV metadata, including taxonomy URLs (see Section 3.1.5) and references to other metadata files (see Section 3.1.18).

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 (xbrlce:invalidCSVFileFormat):

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)

escaped = DQUOTE *(TEXTDATA / COMMA / CR / LF / 2DQUOTE) DQUOTE

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 table is the header row. Each cell in the header row MUST either be empty, or contain a valid identifier (xbrlce:invalidHeaderValue).

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

Column identifiers MUST be defined in the table template definition for the table (xbrlce:unknownColumn). Note that all columns are optional, and are not required to be present in the table.

Column identifiers MUST be unique within a table (xbrlce:repeatedColumnIdentifier).

As any content in a column with an empty header cell cannot make a contribution to the report model, any such content will trigger xbrlce:unmappedCellValue (see Section 3.2.5). Therefore, if a column header is empty, the entire column must be empty.

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.

3.2.4 Special values

The following treatment, referred to as special value processing, is applied to certain values:

A value that starts with # MUST be one of the forms listed above (xbrlce:unknownSpecialValue).

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

3.2.5 Unmapped cell values

Every non-empty cell in a CSV data table MUST make a contribution to the report model unless it is in a comment column (xbrlce:unmappedCellValue). A value makes a contribution to the model if:

  1. It provides the value for a fact, as described in Section 4.2.2;
  2. It contributes to the row identifier part of a fact's {id} property, as described in Section 4.2.3 and Section 4.2.4;
  3. It provides the {decimals} property for a fact, as described in Section 4.2.6; or
  4. It provides the value for a dimension that is not an excluded dimension for a fact, as described in Section 4.2.5.
  5. It provides a fact property group for a fact, as described in Section 3.2.7.

Note that for (3), if the fact value has a decimals suffix, this will override the value provided and the cell is not considered to make a contribution to that fact.

Note that for (5), the cell makes a contribution even if the referenced fact property group is empty, or contains only excluded dimensions or ignored decimals values (Section 4.2.6).

3.2.6 Unreferenced parameters

All report parameters MUST be referenced by at least one value in a dimensions object, {decimals} property or property groups object within the effective metadata of the primary metadata file (xbrlce:unreferencedParameter).

All table parameters MUST be referenced by at least one value in a dimensions object, {decimals} property or property groups object within the table template definition for the table where the parameter is specified, or by at least one value in the report dimensions within the effective metadata of the primary metadata file, or by the value of the {decimals} property of the effective metadata of the primary metadata file (xbrlce:unreferencedParameter).

3.2.7 Property group columns

Property group columns allow sets of decimal and dimension values (fact property groups) to be selected by an identifier, and applied to fact columns.

If a cell in a property group column has a value then it MUST be the value of a key in the property groups object for the column (xbrlce:unknownPropertyGroup). The fact property group corresponding to the value will be applied to facts produced by any fact columns that reference the property group column via the propertiesFrom property, as described in Section 4.2.5 and Section 4.2.6.

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:

{taxonomy}
The list of URLs that is the value of the taxonomy member of the documentInfo object.
{facts}
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:

{id}
See Section 4.2.3.
{dimensions}
See Section 4.2.5.
{decimals}
See Section 4.2.6.
{value}

The value of the cell, after applying special value processing. If the value is non-nil, then it MUST be represented as: (xbrlce:invalidFactValue)

If value is nil, the fact MUST be nillable (xbrlce:invalidFactValue).

If the value is prefixed content, any prefixes MUST be defined in the namespaces object (oimce:unboundPrefix).

{links}
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 concatenation 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.:

{table-identifier}.{row-identifier}.{column-identifier}

4.2.4 Row identifiers

A row identifier provides a unique 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.

Where a data table includes a row ID column the values in the column have the following constraints:

Note that the r_ prefix makes it permissible to use values that start with a number in a row ID column.

4.2.5 Fact dimensions

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

  1. The column dimensions for the current column.
  2. The dimension values defined by fact property groups named in property group columns referenced by the propertiesFrom property, if present, of the column object for the current column.
  3. The table dimensions for the current table.
  4. The report dimensions object.

Note that where propertiesFrom is provided, any of the specified columns MAY be absent from the table, and if present, MAY have an empty cell in the current row. In this case, no dimensions are obtained from that property group column.

In the case of a non-numeric fact, values for the unit core dimension are excluded.

In the case of a non-text fact, values for the language core dimension are excluded.

An excluded dimension is one which is excluded by one of the two preceding rules.

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.

Note that it is an error to provide a duration value for an instant fact. Where the period is obtained from a duration value via a parameter reference, a period-specifier can be used to obtain an instant value that is either the either the start or end of the duration.

If the concept core dimension for a fact is xbrl:note then the {dimensions} property additionally has an xbrl:noteId dimension with a value equal to the fact's {id} property. noteId is not a permitted key of the dimensions object.

4.2.6 Decimals

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

  1. A decimals suffix.
  2. The decimals property of the column object for the current column.
  3. The decimals property of a fact property group referenced by the propertiesFrom property, if present, of the column object for the current column.
  4. The decimals property of the tableTemplates object for the current table.
  5. The top-level decimals property of the report (see Section 3.1.4).

Note that where propertiesFrom is provided, the specified column MAY be absent from the table, and if present, MAY have an empty cell in the current row. In this case, no decimals value is obtained from that property group column.

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

Otherwise, the value of the {decimals} property is obtained as described in Section 3.1.9

Nil-valued and non-numeric facts do not have a {decimals} property, and any decimals properties in the xBRL-CSV metadata are ignored for such facts.

4.2.7 Decimals suffix

A decimals suffix provides a value for the {decimals} property for an individual numeric fact value. A decimals suffix is represented by a lowercase d followed by the decimals value, or INF in the case of infinite decimals. For example, the following indicates a value that is accurate to the nearest 1000:

37000d-3

The suffix MUST match the following regular expression (leading zeros and + are not permitted) (xbrlce:invalidDecimalsSuffix):

/d[\r\n\t ]*(0|-?[1-9][0-9]*|INF)[\r\n\t ]*/

Note that the whitespace characters tab, newline, carriage return and space MAY appear before and after the d and after the suffix value.

5 Features

The features mechanism allows an xBRL-CSV report to assert that it conforms to additional constraints beyond those required by this specification. This can be used by consuming software to safely make simplifying assumptions about how data can be processed.

A feature is a specific property of the report, identified by an expanded name. This specification defines a single standard feature, which MUST be supported by all processors. Additional features MAY be defined by other specifications. Such specifications that are not published by XBRL International MUST NOT use a namespace that uses the xbrl.org domain name.

Feature enablement is controlled by the features object (see Section 3.1.5.6).

5.1 Standard features

This specification defines a single standard feature:

5.1.1 Allowed Duplicates feature

The Allowed Duplicates feature allows an xBRL-CSV document to declare what classes of duplicate facts, if any, are permitted in the report. By default, all types of duplicates are permitted.

The Allowed Duplicates feature is identified by the QName xbrl:allowedDuplicates, and takes one of the following string values:

If present, the xbrl:allowedDuplicates feature MUST have one of the values listed above (xbrlce:invalidJSONStructure).

Processors MUST use the error code oime:disallowedDuplicateFacts if prohibited duplicates are detected.

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 in xBRL-CSV metadata files. For reference, the equivalent representation in xBRL-JSON is also included.

Unless 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
Reference to parameter param n/a $param n/a
Period start from parameter param n/a $param@start n/a
Period end from parameter param n/a $param@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)5 3 (JSON number)
Numeric taxonomy-defined typed dimension value of 3 3 3 (JSON string) 3 (JSON string)
Infinite decimals #none #none No decimals property
Inherit decimals (defaults to infinite) Empty cell 4 No decimals property1 n/a
Absent dimension Empty cell or #none #none 2 No property for dimension
Inherit dimension (defaults to absent) 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

Notes:

  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 such as a report or table dimension, or, in the case of a parameter reference value, a report parameter or table parameter.
  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 parameter reference, then the value will be taken from the first of a column value, table parameter or report parameter that has a value. If no value is obtained, then the dimension is absent (or decimals is infinite); there is no fallback to higher level dimension metadata (table dimensions or report dimensions).
  5. Where a decimals value is obtained via a parameter reference, the parameter value is represented as a JSON string, not a number.

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

This section shows an example of an xBRL-CSV report consisting of two tables. This provides information about individual loans, with one row per loan.

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%

The second table provides summary information about loans broken down by country:

Country Number of loans Amount outstanding
GB 208 €1,284,486
FR 512 €1,734,222
DE 333 €325,031

B.1 Metadata example

A sample metadata file for the above tables 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"
        },
        "taxonomy": [
            "https://xbrl.org/oim/conformance/firm-loans.xsd"
        ]
    },
    "dimensions": {
        "entity": "$entityLEI",
        "period": "$reportPeriod"

    },
    "tableTemplates": {
        "loan_data_template": {
            "columns": {
                "loan_id": {},
                "company_lei": {
                    "dimensions": {
                        "concept": "ld:CompanyLEI"
                    }
                },
                "country_inc": {
                    "dimensions": {
                        "concept": "ld:CountryOfIncorporation"
                    }
                },
                "local_currency": {},
                "fixed_rate_period": {},
                "deposit_amount_hc": {
                    "dimensions": {
                        "concept": "ld:DepositAmount",
                        "period": "$fixed_rate_period@start",
                        "unit": "iso4217:EUR"
                    }
                },
                "deposit_amount_lc": {
                    "dimensions": {
                        "concept": "ld:DepositAmount",
                        "period": "$fixed_rate_period@start",
                        "unit": "$local_currency"
                    }
                },
                "ltv_end_fr": {
                    "decimals": 3,
                    "dimensions": {
                        "concept": "ld:ExpectedLoanToValueRatio",
                        "period": "$fixed_rate_period@end"
                    }
                },
                "rate": {
                    "decimals": 4,
                    "dimensions": {
                        "concept": "ld:InterestRate",
                        "period": "$fixed_rate_period"
                    }
                }
            },
            "rowIdColumn": "loan_id",
            "dimensions": {
                "ld:LoanId": "$loan_id"
            }
        },
        "loan_summary_template": {
            "columns": {
                "country": {},
                "loan_count": {
                    "dimensions": {
                        "concept": "ld:NumberOfLoans",
                        "period": "$reportPeriod@end"
                    }
                },
                "amount": {
                    "dimensions": {
                        "concept": "ld:AmountOutstanding",
                        "period": "$reportPeriod@end"
                    }
                }
            },
            "rowIdColumn": "country",
            "dimensions": {
                "ld:Country": "$country"
            }
        }
    },
    "tables": {
        "loan_data": {
            "template": "loan_data_template",
            "url": "loan-data-facts.csv"
        },
        "loan_summary": {
            "template": "loan_summary_template",
            "url": "loan-summary-facts.csv"
        }
    },
    "parameters": {
        "entityLEI": "lei:00EHHQ2ZHDCFXJCPCL46",
        "reportPeriod": "2019-01-01T00:00:00/2020-01-01T00:00:00"
    }
}

B.2 CSV Example

Corresponding CSV data is show below.

loan-data-facts.csv

loan_id,company_lei,country_inc,local_currency,fixed_rate_period,deposit_amount_hc,deposit_amount_lc,ltv_end_fr,rate
L001,5299006S3ALB1X1PU159,ld:GB,iso4217:GBP,2017-01-01..2018-12-31,1000,2100,0.456,0.0510
L002,529900VVQ4470YJ67K26,ld:FR,iso4217:EUR,2017-06-21..2019-03-20,1100,1100,0.388,0.0465
L003,549300UGDXWZ30VPHZ52,ld:DE,iso4217:EUR,2017-07-01..2017-12-31,870,870,0.348,0.0435

loan-summary-facts.csv

country,loan_count,amount
ld:GB,208,1284486
ld:FR,512,1734222
ld:DE,333,325031

Note:

Appendix C Errata corrections

This appendix contains a list of the errata that have been incorporated into this document. This represents all those errata corrections that have been approved by the XBRL International Open Information Model Working Group (SWG) up to and including 2023-04-19.

Number Date Sections Details
1 3 November 2021 Section 3.1.5 Specify error code for unresolvable metadata files in extends property (#560)
2 12 May 2022 Section 3.2.6 Clarify when xbrlce:unreferencedParameter is to be raised (#567, #571)
3 9 June 2022 Section 3.1.7 Replace erroneous references to "columns" with "properties" (#580)
4 21 July 2022 Section 3.1.6 Reworded ambiguous reference to "identifier" in description of rowIdColumn (#554)
5 21 July 2022 Section 3.1.18 Prohibit directed cycles in metadata import chains (xbrlce:cycleInExtensionChain) (#547)
6 28 July 2022 Section 3.1.15 Clarify the handling of an explicit no-value in a period specified (#572)
7 29 September 2022 Section 3.1.6 Specify that a row ID column cannot be a comment column (xbrlce:invalidRowIdColumn) (#592)
8 10 November 2022 Section 3.1.13 Remove legacy non-normative note that erroneously stated that decimals values obtained via parameter references were required to be JSON numbers (#592)
9 10 November 2022 Section 3.1.8 Explicitly prohibit inclusion of default dimension values, and specify error code (xbrlce:invalidDimensionValue) (#557)
10 6 April 2023 Section 4.2.6 Fix erroneous reference to decimals being a property of documentInfo (#597)