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.
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.
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.
Prefixes used in this specification are to be interpreted according to the following table:
| Prefix | Namespace URI |
|---|---|
| xbrl | http://www.xbrl.org/CR/2020-10-14 |
| xbrli | http://www.xbrl.org/2003/instance |
| xs | http://www.w3.org/2001/XMLSchema |
| xbrlce | http://www.xbrl.org/CR/2020-10-14/error |
The xBRL-JSON format make 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 |
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.
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.
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.
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 XML Schema simple types, identified by a QName. Values within JSON documents MUST have the JSON type specified and MUST be in the canonical lexical representation (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).
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 http://xbrl.org/CR/2020-10-14/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).
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:
Additional properties MUST NOT be included elsewhere (xbrlce:invalidJSONStructure).
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 (xbrlce:invalidJSONStructure).
The content of any such additional properties is not constrained by this specification.
A metadata file consists of a JSON object with the following properties:
documentInfo (object)tableTemplates (object)tables (object)parameters (object)parameterURL (string)xs:anyURI that provides the location of a CSV file containing report parameters. See Section 3.1.13.dimensions (object)decimals (number or string)links (object)The documentInfo object provides document-level information about the xBRL-CSV report. The object has the following properties:
documentType (string)http://xbrl.org/CR/2020-10-14/xbrl-csvnamespaces (object)linkTypes (object)linkGroups (object)taxonomy (array)xs:anyURI) defining the taxonomy for the report. Relative URLs are resolved relative to the primary metadata file.extends (array)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.final (object)features (object)baseURL (string)xs:anyURI) providing a base URL for the report (see Section 3.1.5.6).The namespaces object provides a prefix map for prefixed content values.
Each key provides a prefix, which is mapped to the URI provided by the value.
The prefix map for values appearing within a metadata file is provided by the namespaces object in the effective metadata of the metadata file in which the value appears.
The prefix map for values appearing in a data table is the namespaces object in the effective metadata of the primary metadata file.
The linkTypes object is a URI map 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 metadata file in which the URI alias appears.
The linkGroups object is a URI map 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 metadata file in which the URI alias appears.
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 object | 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 |
See Section 3.1.18.1 for details of interaction with /parameterURL |
The table above uses JSON Pointer notation to specify the objects controlled by each property name.
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.
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.
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 are identifiers, providing a unique table template identifier for each table template.
Each value is a table template object with the following properties:
rowIdColumnrowIdColumn property MUST be the name of a property in the columns object (xbrlce:undefinedRowIdColumn).columnsdecimalsdimensionsThe 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:
decimalsdimensionspropertyGroupspropertiesFromxsd: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 a property group column in the same table (xbrlce:invalidPropertyGroupColumnReference).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 columns are present then the propertyGroups column 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.
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.
If the value of a dimension property starts with $ (but not $$) then it MUST be either a parameter reference or a row number reference, and its value is determined as described in Section 3.1.15 or Section 3.1.16.
If the value of a dimension property starts with $$ then it is treated as starting with a literal $.
Otherwise, the value undergoes special value processing. It
should be noted that whilst the special values #empty and #nil are
permitted in JSON metadata, they are semantically equivalent to an empty JSON
string, and the JSON null value, respectively.
The result of applying special value 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 properties of a dimensions object are listed below. Constraints on the value obtained after applying the processing described above.
concept (string)xs:QName) providing a value for the concept core dimension.entity (string)dtr:SQNameType) providing a value for the entity core dimension.period (string)unit (string)language (string)A decimals value provides a value for the {decimals} property of numeric facts and MUST have one of the following forms: (xbrlce:invalidDecimalsValue)
#none, in which case the value is infinity.Note that this prohibits the use of #nil and #empty as cell values (Section 3.2.3) for the target of parameter references, and where a decimals value is defined in JSON, either directly or as a table parameter or report parameter, it MUST be a JSON number, not a string containing a number. Where a decimals value is defined in a CSV file, it MUST be a valid according to the xs:integer datatype.
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 are identifiers that provide names for the associated fact property group. Each value of a property groups object is a JSON object that defines a fact property group and has the following properties:
decimalsdimensionsWhere 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).
The tables object associates table template definitions with CSV data tables .
The keys of the tables MUST be are 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)xs:anyURI) to the CSV file for this table. Relative URLs are resolved relative to the primary metadata file.template (string)optional (boolean)url property is not required to exist. Defaults to false. If false, the file specified MUST exist (xbrlce:missingRequiredCSVFile).parameters (object)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).
A report parameter is a report-wide value that can be referenced in any table template definition.
Report parameters can be defined using the parameters and parameterURL properties (see Section 3.1).
The parameter property provides an object, with the keys and values giving names and values for the report parameters, respectively.
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)
name and value, in the first and second columns, respectively.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 report parameter, respectively.
Note that report parameters provided via a CSV file are treated as if they
are defined in the parameters property of the primary metadata file
(see Section 3.1.18.1). The CSV file MUST NOT define any parameters
that have the same name as a report parameter defined in the primary metadata file
(xbrlce:illegalReportParameterRedefinition). Note that the constraints
defined in Section 3.1.18 ensure that the CSV file cannot redefine
report parameters that are defined in the parameter property of any other
metadata file in an extension chain.
Names for report parameters MUST be identifiers (xbrlce:invalidIdentifier).
Note that numeric parameter values defined in JSON that are used for decimals values are required to be represented as JSON numbers (see Section 3.1.9) whereas values for dimensions, including numeric values, are required to be represented as JSON strings. The CSV format does not distinguish between string and numeric values.
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.
A parameter reference has one of the following forms:
$parameter-name$parameter-name@period-specifierWhere parameter-name is an identifier, and period-specifier, if
present, MUST be either start or end (xbrlce:invalidPeriodSpecifier).
parameter-name MUST be at least one of the following (xbrlce:invalidReferenceTarget):
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).
If present, period-specifier MUST be either start or end (xbrlce:invalidPeriodSpecifier).
The value of the parameter reference is determined as follows:
start is specified, and the instant at the end of the duration if end is specified.See Appendix A for a summary of the special values available in different contexts.
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.
A row number reference is denoted by the following string:
$rowNumberThe 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.
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 model 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"
}
}
The period dimension MUST be specified in one of the following formats: (xbrlce:invalidPeriodRepresentation)
.. denoting a duration of whole days between, and including, both dates (e.g. 2019-01-01..2019-12-31);2019-01-01);2019-02);2019);Q and an integer in the range 1 to 4 denoting a calendar quarter (three month period) (e.g. 2019Q2);H and either 1 or 2, denoting the first or second half of the year (e.g. 2019H1);YYYYWww where ww is a two-digit integer, in the range 01 to 53, denoting a duration of a week with the corresponding week number (e.g. 2019W03);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 |
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.
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.
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.
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 X that also exists in the corresponding object of 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, if any.
A base file, Y, MAY specify that an object or array is final (see the final object). In this case, the value of the specified object or array in the effective metadata of X MUST be the value of that object or array in the effective metadata of Y (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.
All properties not listed above are not extensible, and, with the
exception of documentInfo, MUST NOT appear in more than one metadata file (xbrlce:illegalRedefinitionOfNonExtensibleProperty).
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).
Note that any report parameters defined via the parameterURL property
(see Section 3.1.13) are treated as if they appear in the
parameters object of the primary metadata file. For this reason, a
metadata file MUST NOT have both parameterURL and a final object
containing parameters in its effective metadata
(xbrlce:unusableParameterURL).
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.
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.
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
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 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).
Column identifiers MUST be unique within a table (xbrlce:repeatedColumnIdentifier).
The following treatment, referred to as special value processing, is applied to certain values:
#empty represents an empty string value.#nil represents the nil value.#none specifies an explicit no-value in the case of a dimension value, or a value of infinity in the case of a decimals value. #none MUST NOT be used in a fact column or a property group column (xbrlce:illegalUseOfNone).## is treated as starting with #.See Appendix A for a summary of the special values available in different contexts.
A column that is referenced by a parameter reference in the same table template, a report dimension or a report-level decimals property (Section 3.1.4) is a parameter value column. Note that a column MAY be both a fact column and a parameter value column.
If a cell in a parameter value column has a value and the column is not also a fact column, then the column MUST be the target of a parameter reference in the definition of at least one fact column that has a value in the current row (xbrlce:unmappedCellValue).
If a cell in a property group column has a value, then the column MUST
be the target of the propertiesFrom property for at least one fact column
that has a value in the current row (xbrlce:unmappedCellValue).
Values MAY appear anywhere in a column that is not a parameter value column or a property group column. If such a column is not a fact column then the values will not be mapped into the OIM Report Model.
All table parameters MUST be referenced by at least one fact column in the table template definition for the table which has a value in that column in at least one row (xbrlce:unmappedTableParameter).
All report parameters MUST be referenced by at least one fact column in any table template definition which is used by at least one table which has a value in that column in at least one row (xbrlce:unmappedReportParameter).
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.
A property group column MUST NOT be a parameter value column or a fact column (xbrlce:invalidColumnType).
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.
The report component has the following properties:
taxonomy member of the documentInfo object.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.
The fact has the following properties:
The value of the cell, after applying special value processing. If the value is non-nil, then it MUST be represented as: (xbrlce:invalidFactValue)
xs:QNames, in the case of a set-valued enumeration fact;xs:QName, in the case of a single-valued enumeration fact;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.
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}
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:
rN where N is the row number of the current row. Where a data table includes a row ID column the values in the column have the following constraints:
The {dimensions} property of a fact consists of the union of the following dimension values:
propertiesFrom property, if present, of the column object for the current 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.
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. The xbrl:noteId dimensions
MUST NOT be defined explicitly in an xBRL-CSV report (xbrlce:invalidNoteIdDimension).
If the value for a taxonomy-defined dimension is not nil, it MUST be expressed in a lexical representation that is valid according to the XML Schema datatype of the dimension (xbrlce:invalidDimensionValue). If the value is nil, the dimension MUST be a nillable, typed taxonomy-defined dimension (xbrlce:invalidDimensionValue). If the value is prefixed content, any prefixes MUST be defined in the namespaces object.
The {decimals} property of a numeric fact is determined by the first of the following that is present:
decimals property of the column object for the current column.decimals property of a fact property group referenced by the propertiesFrom property, if present, of the column object for the current column.decimals property of the tableTemplates object for the current table.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 obtained as described in Section 3.1.9
Non-numeric facts do not have a {decimals} property, and any decimals
properties in the xBRL-CSV metadata are ignored for such facts.
A decimals suffix provides a value for the {decimals} property for an
individual 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 follow the numeric value immediately (no whitespace), and MUST match the following regular expression (whitespace, leading zeros and + are not permitted):
/d(0|-?[1-9][0-9]*|INF)/
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 does not define any standard features. 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.5).
This specification defines a single standard 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:
none — duplicate facts are not permitted.complete — only complete duplicates are permitted.consistent — only consistent duplicates are permitted (note that the definition of consistent duplicates includes complete duplicates.all — (default) all classes of duplicate facts are permitted.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.
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) |
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:
#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 value column, a report parameter or table parameter.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 |
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"
}
}
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:
ld:GB, ld:FR, ld:DE values correspond to explicit domain members defined within the taxonomy.