1 Introduction
1.1 Terminology
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, in this specification, are to be interpreted as described in [IETF RFC 2119].
The keywords expanded name, NCName and QName are to be interpreted as described in the XML Names specification [XML Names].
The keywords aspect, taxonomy-defined aspect, simple fact, numeric simple fact and text simple fact are to be interpreted as described in the OIM specification [OIM].
The keywords SQName and prefix map are to be interpreted as described in the OIM Common Definitions specification [OIMCOMMON].
1.2 Namespaces and namespace prefixes
Many values in the Open Information Model are XML expanded names, the
combination of a namespace URI [URI] and a localname. This specification
uses QName notation in the form prefix:localname to
refer to these, where the prefix is a short string representing a
full namespace URI. The prefixes used by this specification are
defined below.
| Prefix | Namespace URI |
|---|---|
| xbrl | http://www.xbrl.org/PWD/2017-05-02/xbrl |
| csvw | http://www.w3.org/ns/csvw |
2 Overview
This document defines a CSV-based [IETF RFC 4180] 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 which builds upon the W3C's Tabular Metadata specification [TABULAR METADATA], and extends it to include XBRL-specific metadata, such as taxonomy references and common aspect definitions.
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 in order to achieve intuitive and efficient tables.
3 Identifiers in xBRL-CSV
xBRL-CSV makes use of SQNames to represent expanded names and some other values. The prefix map for resolving SQNames is provided by the prefixes property of the metadata.
4 xBRL-CSV report structure
An xBRL-CSV report is a CSV-based representation of a report, as defined in the XBRL Open Information Model [OIM]. An xBRL-CSV report consists of a JSON metadata file, and a number of CSV files, collectively known as a report file set. The metadata file provides links to the CSV files that contain the report data, and defines the meaning of the columns in each CSV table.
An xBRL-CSV report file set consists of a metadata file and zero or more CSV data tables.
A report file set is identified by a path or URL to a metadata file, which in turn contains references to the associated CSV files.
A metadata file is a JSON file that
contains only a metadata object.
The metadata JSON file name SHOULD have an extension of
.json.
4.1 CSV file format
A CSV data table is a CSV file that is referenced by table object in a metadata file. CSV data tables are interpreted as described in this section.
Columns in a CSV data table are of one of four basic column types:
The first row in a CSV file is the header row. This row MAY be used to provide a human readable label for a column, but it provides no semantic information and does not correspond to any information in the report. Cells in subsequent rows are interpreted as described below.
Each non-empty cell in a fact column results in the contribution of a fact to the model.
Each non-empty cell in a text footnote column results in the contribution of a footnote to the model, provided that the footnote is associated with at least one fact, as described in Section 4.1.3.5.
Each non-empty cell in a property value column contributes a property value to some or all of the facts and footnotes produced by cells in fact columns and footnote columns in the same row. See the documentation of the columnProperty member of the column metadata object for details of this mechanism.
Unmapped columns contribute nothing to the resulting model.
4.1.1 Property inheritance
The properties associated with a fact or text footnote MAY be defined in a number of different locations. This allows common property values to be defined at the report, table or row level.
The production column is the fact column or text footnote column that contributes the fact or text footnote to the model.
Properties with a value based on reference list take a value that is the concatenation of the lists of values defined for that property in all possible locations, starting with the lowest priority location.
All other properties take a single value and a value defined in a higher priority location will override any values for that same property defined at a lower priority location. The possible locations are (highest priority first):
- Column-level properties defined on the production column.
- Properties values contributed to the production column by a property value column.
- Table-level properties defined for the table that contains the production column.
- Report-level properties.
The properties objects that are used to define column-level properties and table-level properties can use the deleteInheritedProperties member to block inheritance of properties from lower priority locations. This allows properties to be removed, rather than overridden with a new value. This also provides a mechanism for replacing, rather than appending to, the list of values for properties with values based on reference lists.
Report-wide or table-wide values can be specified using a properties object:
"http://xbrl.org/YYYY/model#properties": { "xbrl:entity": "scheme:01", "accuracy": 2, "footnoteRefs": [ "f1", "f2" ] }
These values can be replaced (or extended, in the case of list properties) by properties defined at the column level:
"http://xbrl.org/YYYY/model#properties": { "accuracy": 4, "footnoteRefs": [ "f3" ] }
In this example, facts defined in this column would have a value of scheme:01 for the xbrl:entity aspect property, "4" for the accuracy property and [ "f1", "f2", "f3" ] for the footnoteRefs property
It is also possible to specify properties whose value will be taken from a cell in a given column and applied to other columns in the same row. In the example below, values from cells in the column will provide a value for the periodStart property for all other cells in the same row to which periodStart is applicable (i.e. all simple fact columns).
{ "name": "period", "datatype": "dateTime", "http://xbrl.org/YYYY/model#columnType": "propertyValue", "http://xbrl.org/YYYY/model#columnProperty": "xbrl:periodStart" }
Values specified in this way will override report-level and table-level properties, but will be overriden by any column-level properties.
4.1.2 Property applicability
Properties are applicable to one or more column types, as defined in Section 4.1.3. When producing a fact or text footnote, the set of properties obtained via property inheritance ( Section 4.1.1) is filtered to those that are applicable to the production column's column type. All other properties are ignored.
4.1.3 Column types
This section defines the column types that appear in an CSV data table. The type of a column is defined by the columnType property of the column metadata object for the column.
The definitions below include the set of applicable properties for each production column column type.
4.1.3.1 Fact column
A fact column is a column that is a simple fact column, a a numeric simple fact column, a a text simple fact column, or a tuple fact column.
4.1.3.1.1 Applicable properties
The following common properties are applicable to all fact columns:
xbrl:conceptxbrl:tupleParentxbrl:tupleOrderfootnoteRefsfootnoteForfootnoteGroupfootnoteTypefactId
4.1.3.2 Simple fact column
A simple fact column is a column with a columnType property of simpleFact contains values
for simple facts. Each row that has a non-empty value in a
simple fact column corresponds to a
fact in the report. facts with empty string values, or the "nil" value may be represented using the "#empty" and "#nil" special values, as defined in Section 4.1.3.7.
4.1.3.2.1 Applicable properties
In addition to the properties defined for all fact columns, the following properties are applicable to simple fact columns:
xbrl:entityxbrl:period- any taxonomy-defined aspect
4.1.3.2.2 Numeric simple fact column
A numeric simple fact column contains values for numeric simple facts [OIM].
4.1.3.2.2.1 Applicable properties
In addition to the common properties defined for all simple fact columns, the following properties are applicable to numeric simple fact columns:
xbrl:unitaccuracy
4.1.3.2.3 Text simple fact column
A text simple fact column contains values for simple string facts[OIM].
4.1.3.2.3.1 Applicable properties
In addition to the common properties defined for all simple fact columns, the following property is applicable to text simple fact columns:
xbrl:language
4.1.3.3 Tuple fact column
A tuple fact column contains OIM fact IDs and specifies that a tuple is to be produced for each row with a non-empty value in this column. The children of the produced tuple fact are all facts produced from any CSV data table in the report file set with a tuple parent property that references the value in this column.
The values in tuple fact columns MUST be unique within the report file set.
4.1.3.3.1 Applicable properties
The common properties defined for all tuple fact columns are:
xbrl:conceptxbrl:tupleParentxbrl:tupleOrderfootnoteRefs
4.1.3.4 Property value column
A property value column provides values for
properties that are applicable to either the
whole row, or to some specified subset of the values in that row. The property name, and the columns to which it
applies, are defined by the http://xbrl.org/YYYY/model#columnProperty member
of the corresponding column object.
4.1.3.5 Text footnote column
A text footnote column contains text for a text footnotes. Footnotes may be associated with facts in the same row using the footnoteFor property. Alternatively, the footnotes may be referenced by a fact defined anywhere in the report that have a footnote-refs property that contains the value of the footnote's footnote ID property.
A footnote is produced for each non-empty cell that is associated with at least one fact. To create an empty footnote, the special value of "#empty" may be used, as described in Section 4.1.3.7.
4.1.3.5.1 Applicable properties
The properties applicable to text footnote columns are:
footnoteIdfootnoteGroupfootnoteTypefootnoteForxbrl:language
4.1.3.6 Unmapped column
A unmapped column is any column for which the columnType property is absent.. The contents of unmapped columns are completely ignored by xBRL-CSV processors.
4.1.3.7 Column values
The following special values are defined for use on property value columns, simple fact columns and text footnote columns.
- A value of '#nil' represents the nil value.
- A value is '#empty' it represents an empty string value.
- If the initial two characters are '##' they represent a single '#' as initial value character.
- Other values, including those starting with a single '#' are treated literally.
4.2 Metadata file format
- documentType: "http://xbrl.org/YYYY/xbrl-csv",
- prefixes: a Prefixes JSON object and
- dtsReferences: an array of DTS Reference JSON objects.
name column property defined in section 5.6 of the Tabular Metadata Model.
Required. Defines the columnType property of the column. The possible values are:
simpleFactnumericSimpleFacttextSimpleFacttupleFactpropertyValuetextFootnote
Optional. The datatype of the column, as defined by section 4.6 of the Tabular Metadata Model. If specified on a fact columns, the specified datatype MUST be the nearest ancestor type of the fact concept that is supported by the Tabular Metadata Model. If the column is required to support the special values of "nil" or the empty string, and the appropriate datatype does not support the "#nil" or "#empty" representations required by this specification (see Section 4.1.3.7) then this property MUST be omitted.
An example of this would be a need to use a nil-valued
fact based on xbrli:decimalItemType, as "#nil" is not a valid value for xsd:decimal.
This property is used for columns which contribute a
property value to facts and footnotes produced by
other columns in the same row.
This property MUST be present if columnType is
property, MAY be present if columnType
is tupleFact or footnote, and MUST be absent otherwise.
The value is interpreted as follows:
- If the value is a string (e.g., "xbrl:periodStart") then the value is a property name, and the value for each cell in the corresponding CSV table column is applied to all other cells in that row, as described in Section 4.1.1 and Section 4.1.2.
-
If the value is an object then the keys are property
names and the values are column lists
defining the columns to which the property value applies. For example,
{xbrl:periodStart: ["property", "equipment"]}means that the value of the cell is applied to item facts produced by the columns named "property" and "equipment"). If the value is an empty list, the value is applied to all other cells in that row, as for the case of a string value described above.
If columnType is tupleFact then the sole property specified by this object MUST be the tuple parent property.
If columnType is textFootnote then the sole property specified by this object MUST be the footnote-for property.
The property factId specifies an @id attribute to be
produced for a fact producing column that has this property applied.
The property footnoteId specifies a footnote reference ID for a footnote producing column that has this property applied.
When this property is present and columnType is tupleFact,
it MUST specify an xbrl:tupleParent property.
4.3 Properties
A property is a piece of information associated with a fact or footnote. A property consists of a property name and a property value.
A property name is a string or SQName that identifies a property. Available property names, and their associated behaviour, are described in the following sections.
4.3.1 Aspect property
An aspect property is identified by an SQName corresponding to the name of an OIM aspect.
An aspect property provides a value for the corresponding OIM aspect to any facts to which it applies.
4.3.2 Period properties
A period property is identified by an SQName corresponding xbrl:periodStart or xbrl:periodEnd.
A period property provides a value for the start or end of the time interval for the OIM period core aspect to any facts to which it applies. The special value of "forever" is represented by omitting both properties (or deleting any values for them using deleteInheritedProperties.
4.3.3 Accuracy property
An accuracy property is identified by the integer accuracy.
An accuracy property provides a value for the OIM accuracy property of a numeric simple fact to any facts to which it applies. The property can only be used to provide a numeric value for accuracy. The special value of "infinity" is represented by omitting this property (or deleting any value for it using deleteInheritedProperties).
4.3.4 Footnote-for property
A footnote-for property is identified by the string footnoteFor.
A footnote-for property specifies that a footnote or fact produced by a cell in the the column to which it is applied provides a footnote to the columns specified in the property value. The value of a footnote-for property MUST be a column list.
4.3.5 Footnote-refs property
A footnote-refs property is identified by the string footnoteRefs.
A footnote-refs property specifies that the fact produced by a cell to which it is applied has the footnotes with footnote IDs listed in the property value. The value of a footnote-refs property MUST be a footnote ID list.
4.3.6 Footnote ID property
A footnote ID property is identified by the string footnoteID.
A footnote ID property specifies the footnote ID for the text footnote produced by the cell to which it is applied.
A footnote ID is a unique identifier for a footnote. It is used only for referencing within the report file set and its value is not included in the model. A footnote ID MUST conform to the varname format defined in the Variables section of RFC 6570 with the additional restriction that the first character MUST NOT be underscore.
Footnote IDs MUST be unique within the report file set. The requirement for uniqueness means that it typically only makes sense to define this property using a property value column, but this is not a requirement of the specification.
4.3.7 Footnote group property
A footnote group property is identified by the string footnoteGroup.
A footnote group property specifies the OIM footnote group property for a footnote. Where the property is applied to a text footnote column, any footnotes produced by the column will have the specified footnote group. Where the property is applied to a fact column, any facts produced by the column that are used as footnotes for other facts will have that footnote group. In all other cases, the footnote group property is ignored.
4.3.8 Footnote type property
A footnote type property is identified by the string footnoteType.
A footnote type property specifies the OIM footnote type property for a footnote. Where the property is applied to a text footnote column, any footnotes produced by the column will have the specified footnote type. Where the property is applied to a fact column, any facts produced by the column that are used as footnotes for other facts will have that footnote type. In all other cases, the footnote type property is ignored.
4.3.9 Fact ID property
A fact ID property is identified by the string factID.
A fact ID property specifies the OIM fact ID property for any facts produced by the cells to which it is applied. Fact IDs MUST be valid NCNames [XML Names] and MUST be unique within the report file set. The requirement for uniqueness means that it typically only makes sense to define this property using a property value column, but this is not a requirement of the specification.
Fact IDs MAY be referenced by tupleParent properties.
4.3.10 Tuple parent property
A tuple parent property is identified by the string tupleParent.
A tuple parent property specifies the tuple fact that is the parent of facts produced by columns to which it is applied. The value of this properties is an OIM fact ID defined in a tuple fact column within the report file set.
4.3.11 Tuple order property
A tuple order property is identified by the string tupleOrder.
A tuple order property specifies the relative ordering of facts within a tuple. The value MUST be a decimal number, and is used only to establish the ordering between facts; the value is not present in the OIM.
4.3.12 Column list values
A column list is a reference list of column names.
The values in a column list MUST be column names for columns present in the same table. Column lists MUST NOT appear as values for report-level properties.
4.3.13 Footnote ID list values
A footnote ID list is a reference list of footnote IDs.
The values in a footnote ID list MUST be footnote IDs defined elsewhere in the report file set.
4.3.14 Reference list values
A reference list is a list of references to identifiers defined elsewhere in the report file set . Where a reference list appears in a metadata file, it is represented as a JSON array of string values. Where a reference list appears in a CSV data table, it is represented as a space-separated list.
4.4 Examples of mapping to OIM Simple Facts
The following figure illustrates how a CSV data table (top left) and associated metadata file (top right) map to a set of OIM simple facts.
This example's CSV table has two kinds of columns, two property value columns and three simple fact columns. The first two provide row-level properties to be applied to a row's three facts producing columns. Report-level properties are specified by values in the metadata file (at top) and are inherited by facts produced by all rows.
Metadata drives the mapping:
Arrows demonstrate how the mapping works. Red arrows demonstrate how information in the metadata file provides meaning for a CSV data table. Blue arrows show how data from the table is converted into OIM facts.
- Report-level properties provide property values to all facts produced by all rows, filtered as described in Section 4.1.2:
- the accuracy is applied to all numeric simple facts
- the
xbrl:entityaspect property is applied to all simple facts - the
xbrl:unitaspect property is applied to all numeric simple facts
- The first column ("entry") is a property value column
specifies that the
ex:entryDimensionaspect value is to be the value of the first column for all the facts produced by that row. - The second column, ("period") is another property value column
is its value is likewise applied to both the
xbrl:periodStartandxbrl:periodEndaspects of all facts produced by that row. - The third column ("location") is a simple fact column
and produces a an OIM fact for each row in the column, with a value taken from the cell.
The fact will have aspects specified by the properties object on the column (
xbrl:concept, in this example) along with inherited row-level columnProperty aspects (xbrl:perioddates and theex:entrydimension) and inherited report-level properties (in this case, justxbrl:entitybecause this column produces a non-numeric fact). - The remaining two columns likewise map to
facts and as they are numeric they also receive inherited
accuracyandxbrl:unitproperties.
4.5 Examples of mapping to OIM Tuple Facts
OIM tuple facts are produced by a non-empty value in a tuple fact column
Facts that are children of a tuple identify their parent fact using the tuple parent property. As a shorthand for doing this, the column object for a tuple fact column may include a columnProperty object that contributes a tuple parent property to some or all other columns in the same table. This means that other facts in the same row defined in those columns will automatically become children of the tuple fact.
The example below demonstrates the use of columnProperty to produce a tuple from facts contained in the same row of a table.
Metadata relevant to the tuple mapping:
- The column definition with type
tupleFactcircled specifies that this column maps to an OIM tuple fact. This column contains an id value to be used as the tuple ID. The column also uses thecolumnPropertymember to contribute this ID as a tupleParent property to all other facts in the row. - The column definitions of type simpleFact specify a tupleOrder property which defines the relative order of the child facts.
- The circled tupleFact properties, columnProperty properties of the first column, named "Tuple Id" in metadata and titled "tuple id" in the CSV table, specify that a tuple fact with indicated xbrl:concept aspect is produced for the id of the column, that the column contains an id attribute to be mapped to the tuple fact produced and that the contents of this column to be mapped as tuple parent to other facts produced by the row.
- The circled simpleFact type objects of the other columns have an xbrl:tupleOrder aspect (in addition to the aspects of the prior example).
4.6 Examples of mapping to OIM Footnotes
This example extends the previous example to demonstrate the mapping of OIM Footnotes. Two separate approaches are demonstrated:
- Separate CSV tables, one with facts and the other with footnotes.
- A combined CSV table, with separate columns for facts and for footnotes.
In either case, a fact may have mulitple footnotes. Footnotes may be text footnotes or fact footnotes.
4.6.1 Separate CSV Facts and Footnotes Tables
A fact (simple or tuple) may have zero to many footnoteId properties applied to it. The footnote Id properties form an array that may hook up to multiple footnotes.
This example has two CSV tables, an augmented CSV Facts Table, with information to provide footnote ids on facts and a CSV Footnotes Table. The prior example of a dimensional CSV facts table is supplemented with columns to provide footnote ids for both property and equipment columns. When there is an entry in this CSV Facts table for property footnoteIds, the applied fact is hooked up to footnotes matching the ids, likewise for equipment facts. (Footnote ids may be applied to multiple columns, for situations when they uniformly apply to the same group of facts of table rows.)
The CSV Footnotes Table has columns for footnote id, to hookup by footnote ids to facts of the CSV Facts Table). Example footnotes are multilingual text resources, with a column per language of footnote. FootnoteGroup (XBRL link role) and footnoteType (XBRL arcrole) may either be specified as constants for the table (as in this example) or in the columns for each row of footnotes.
Metadata relevant to the separate facts and footnotes tables mapping:
- There are two CSV tables in the metadata, a facts table and a footnotes table.
- In the CSV facts table, the additional footnote column for Property has the circled footnoteIds ["property"] to specify that the contents of this column are footnote ids for the metadata column named "property". It's an array to provide for footnote ids applying to multiple fact producing columns.
- The CSV footnote table columns have circled properties indicating that they are footnoteId and footnote text contents.
- There are two footnote text columns, for languages "en" and "fr", each of which maps to a separate OIM Fact Footnote per language.
- The mapping to the CSV facts table that couples footnote id column to simple fact column(s). (A second line isn't shown but would exist for the Equipment column and its footnote id column.)
- Each footnote table metadata description and corresponding column.
- That the footnote language columns of the CSV footnotes table, which are adjacent, produce separate OIM fact foootnotes for each language. Where footnotes are shared among several facts in the CSV tables, for the OIM model of facts, the footnotes are replicated for each sharing OIM fact (shown here, the CSV footnote fn1, shared by two property facts, replicates for each language for each sharing fact).
4.6.2 Combined CSV Table with Facts and Footnotes
When footnotes can be specified in the same row of tables producing facts, they are hooked up to the facts by having a footnotes property applied to the facts. In this manner they don't need the footnote Id surrogate mechanism to connect fact to footnote.
There can be zero to many footnotes hooked up to a fact, and they can be a mixture of footnotes hooked up by footnote property (in same row of same table) and footnotes hooked up by matching footnote id (located elsewhere).
The combined example CSV Facts and Footnotes Table represents footnotes in columns adjacent to facts columns. The earlier example of a dimensional CSV facts table is supplemented with columns to provide footnote text for both property and equipment columns. When there is an entry in a row for property footnote, the property fact is mapped with that footnote text, likewise for equipment facts. (Footnotes can be mapped for groups of columns as well, for situations when they always apply to the same groups of facts in table rows.)
This example shows that when footnote applies to multiple facts produced from separate rows, text is repeated for each attributed fact, in contrast to the separate table footnotes example, where the shared footnote is given an id that is used for each attributed fact.
In the previous example with separate CSV tables for facts and footnotes, a fact attributed by multiple footnotes has a list of ids in its footnote Ids column. In this example with combined facts and footnotes, to provision for multiple footnotes of a single fact, it would be necessary to provide multiple footnote columns for the fact.
Metadata relevant to the combined facts and footnotes table mapping:
- There is a single CSV table in the metadata, with shared footnote properties at the table object level.
- In the CSV facts table, the additional textFootnote column for Property has the columnProperty, footnoteFor, to specify that the contents of this column are footnote text for the metadata column named "property". It's an array to provide for footnote text applying to multiple fact producing columns.
- If there were a need for multiple languages of footnotes in this example, they could be represented by additional columns.
