xBRL-CSV: mapping from Open Information Model 1.0

Public Working Draft 02 May 2017

Copyright © XBRL International Inc., All Rights Reserved.

This version:
<http://www.xbrl.org/Specification/xbrl-csv/PWD-2017-05-02/xbrl-csv-PWD-2017-05-02.html>
Editors:
Herm Fischer, Mark V Systems Limited <fischer@markv.com>
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
Contributors:
David Bell, Donnelley Financial Solutions <david.x.bell@dfsco.com>
Daniel Dracott, CoreFiling <djd@corefiling.com>
Mark Goodhand, CoreFiling <mrg@corefiling.com>
Paul Hulst, De Nederlandsche Bank N.V. <P.J.Hulst@dnb.nl>
Eleanor Joslin, CoreFiling <ejj@corefiling.com>

Status

Circulation of this Public Working Draft is unrestricted. This document is normative. Other documents may supersede this document. Recipients are invited to submit comments to oim@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.

Abstract

This document defines xBRL-CSV, a standardised CSV-based representation of data in an XBRL Report. The format is defined in the form of mappings from the XBRL Open Information Model [OIM], a syntax-independent definition of the data represent by an XBRL v2.1 [XBRL 2.1] instance document.

Comments

1 Paul Warren: Following the approach taken in the current draft of the OIM, this specification does not have a mechanism for representing "custom attributes" as permitted by the XBRL v2.1 specification. It is recognised that these are in use in some implementations, but the OIM attempts to balance the need to support XBRL v2.1 features that are in widespread use, with a desire to provide a simplified model that reduces the number of essentially equivalent technical syntaxes that are available for representing a given requirement. The Working Group is actively seeking feedback on this point.
2 Paul Warren:The Working Group is actively seeking comments on the extent to which this specification should rely on features in the Tabular Metadata and JSON-LD specifications.

Table of Contents

1 Introduction
1.1 Terminology
1.2 Namespaces and namespace prefixes
2 Overview
3 Identifiers in xBRL-CSV
4 xBRL-CSV report structure
4.1 CSV file format
4.1.1 Property inheritance
4.1.2 Property applicability
4.1.3 Column types
4.1.3.1 Fact column
4.1.3.1.1 Applicable properties
4.1.3.2 Simple fact column
4.1.3.2.1 Applicable properties
4.1.3.2.2 Numeric simple fact column
4.1.3.2.2.1 Applicable properties
4.1.3.2.3 Text simple fact column
4.1.3.2.3.1 Applicable properties
4.1.3.3 Tuple fact column
4.1.3.3.1 Applicable properties
4.1.3.4 Property value column
4.1.3.5 Text footnote column
4.1.3.5.1 Applicable properties
4.1.3.6 Unmapped column
4.1.3.7 Column values
4.2 Metadata file format
4.3 Properties
4.3.1 Aspect property
4.3.2 Period properties
4.3.3 Accuracy property
4.3.4 Footnote-for property
4.3.5 Footnote-refs property
4.3.6 Footnote ID property
4.3.7 Footnote group property
4.3.8 Footnote type property
4.3.9 Fact ID property
4.3.10 Tuple parent property
4.3.11 Tuple order property
4.3.12 Column list values
4.3.13 Footnote ID list values
4.3.14 Reference list values
4.4 Examples of mapping to OIM Simple Facts
4.5 Examples of mapping to OIM Tuple Facts
4.6 Examples of mapping to OIM Footnotes
4.6.1 Separate CSV Facts and Footnotes Tables
4.6.2 Combined CSV Table with Facts and Footnotes

Appendices

A References
B Intellectual property status (non-normative)
C Document History (non-normative)
D Errata Corrections incorporated in this document
E CSV report model

Table

1 Namespaces and namespace prefixes

Examples

1 Examples of property inheritance
2 Example of mapping to OIM Simple Facts.
3 Example of mapping to OIM Tuple Facts.
4 Example of mapping to footnotes from separate OIM facts and footnotes tables.
5 Example of mapping to footnotes from a combined CSV table of facts and footnotes.

Definitions

Accuracy property
Aspect property
Column (JSON object)
Column list
Column name
Column type
Column-level properties
columnType property
CSV data table
Fact column
Fact ID property
Footnote group property
Footnote ID
Footnote ID list
Footnote ID property
Footnote type property
Footnote-for property
Footnote-refs property
Header row
Metadata (JSON Object)
Metadata file
Numeric simple fact column
Period property
Production column
Properties (JSON object)
Property
Property name
Property value column
Reference list
Report file set
Report-level properties
Simple fact column
Table (JSON object)
Table schema (JSON object)
Table-level properties
Text footnote column
Text simple fact column
Tuple fact column
Tuple order property
Tuple parent property
Unmapped column


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.

Table 1: Namespaces and namespace prefixes
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):

  1. Column-level properties defined on the production column.
  2. Properties values contributed to the production column by a property value column.
  3. Table-level properties defined for the table that contains the production column.
  4. 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.

Example 1: Examples of property inheritance

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:concept
  • xbrl:tupleParent
  • xbrl:tupleOrder
  • footnoteRefs
  • footnoteFor
  • footnoteGroup
  • footnoteType
  • factId

[Paul Warren: Following the approach taken in the current draft of the OIM, this specification does not have a mechanism for representing "custom attributes" as permitted by the XBRL v2.1 specification. It is recognised that these are in use in some implementations, but the OIM attempts to balance the need to support XBRL v2.1 features that are in widespread use, with a desire to provide a simplified model that reduces the number of essentially equivalent technical syntaxes that are available for representing a given requirement. The Working Group is actively seeking feedback on this point. ]

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:entity
  • xbrl: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:unit
  • accuracy
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:concept
  • xbrl:tupleParent
  • xbrl:tupleOrder
  • footnoteRefs

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:

  • footnoteId
  • footnoteGroup
  • footnoteType
  • footnoteFor
  • xbrl: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

JSON Object: Metadata
This object provides report-level metadata, default aspects that are inherited by all tables, and a list of the CSV tables that define the facts in the report. This object is a description object for a group of tables, as defined in [TABULAR METADATA VOCABULARY], and xBRL-CSV reports MAY use any of the properties defined in that specification, conformant processors are only required to support those properties defined in this specification. [Paul Warren: The Working Group is actively seeking comments on the extent to which this specification should rely on features in the Tabular Metadata and JSON-LD specifications.].
Members:
@context (string)
A JSON-LD context of the value http://www.w3.org/ns/csvw specifying that keywords are expanded for the csvw namespace as required for compatibility with [CSVW].
http://xbrl.org/YYYY/model#metadata (JSON object)
A JSON object containing:
http://xbrl.org/YYYY/model#properties (object)
Optional. Defines report-level properties. See properties object.
tables [CSVW] (JSON array)
An array of table objects.
JSON object: Table
This object represents each table object within a metadata tables object. Each table object contains a reference to a CSV table file, and metadata about that file, as described below.
Members:
tableSchema [CSVW] (JSON object)
A table schema JSON object.
url [CSVW] (string)
A URL to a CSV file. The format of CSV files is described in Section 4.1
http://xbrl.org/YYYY/model#properties (object)
Optional. Defines report-level properties. See properties object.
JSON object: Table schema
Members:
columns [CSVW] (JSON array)
An array of column objects that correspond in order to the column objects of the CSV data.
JSON object: Column
The column object provides metadata for an individual column within a CSV table.
Members:
name [CSVW] (string)
Required. Defines a name of the column. The name MUST be unique within a table, and MUST conform to the constraints specified for the name column property defined in section 5.6 of the Tabular Metadata Model.
http://xbrl.org/YYYY/model#columnType (string)

Required. Defines the columnType property of the column. The possible values are:

  • simpleFact
  • numericSimpleFact
  • textSimpleFact
  • tupleFact
  • propertyValue
  • textFootnote

datatype [CSVW] (string)

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.

http://xbrl.org/YYYY/model#columnProperty (object)

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.

http://xbrl.org/YYYY/model#properties (object)
Optional. Defines column-level properties. See properties object.
JSON object: Properties
An object containing a set of properties
Members:
property name (string)
A value for the property with the property name identified by the member.
deleteInheritedProperties (list)
A list of property names for which values will not be inherited from lower priority locations, as described in Section 4.1.1. This allows properties to be removed, rather than just overridden with a new value. If this properties object also provides a value for a property defined in this list then that value will be applied. In the case of properties with values based on reference list, any inherited values are removed. This has the effect of replacing the list of inherited values, rather an appending to the list.

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

Example 2: Example 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.

Simple Fact Mapping

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 first column ("entry") is a property value column specifies that the ex:entryDimension aspect 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:periodStart and xbrl:periodEnd aspects 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:period dates and the ex:entry dimension) and inherited report-level properties (in this case, just xbrl:entity because this column produces a non-numeric fact).
  • The remaining two columns likewise map to facts and as they are numeric they also receive inherited accuracy and xbrl:unit properties.

4.5 Examples of mapping to OIM Tuple Facts

Example 3: Example 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.

Tuple Fact Mapping

Metadata relevant to the tuple mapping:

  • The column definition with type tupleFact circled 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 the columnProperty member 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.
Lines indicate:
  • 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.

Example 4: Example of mapping to footnotes from separate OIM facts and footnotes tables.

Footnote Mapping

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.
Lines indicate:
  • 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).

Example 5: Example of mapping to footnotes from a combined CSV table of facts and footnotes.

Footnote Mapping In Fact Table

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.

Appendix A References

CSVW
W3C (World Wide Web Consortium). "CSVW Namespace Vocabulary Terms"
Gregg Kellogg.

(See http://www.w3.org/ns/csvw)
IETF RFC 2119
IETF (Internet Engineering Task Force). "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels"
Scott Bradner.

(See http://www.ietf.org/rfc/rfc2119.txt)
IETF RFC 4180
IETF (Internet Engineering Task Force). "RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files"
Y. Shafranovich.

(See https://tools.ietf.org/html/rfc4180)
IETF RFC 6570
IETF (Internet Engineering Task Force). "RFC 6570: URI Template"
J. Gregorio
, R. Fielding, M. Hadley, M. Nottingham, and D. Orchard.
(See https://tools.ietf.org/html/rfc6570)
OIM
XBRL International Inc.. "XBRL Open Information Model"
Paul Warren.

(See http://www.xbrl.org/Specification/tbd/tbd.html)
OIM JSON
XBRL International Inc.. "xBRL-JSON: mapping from Open Information Model 1.0"
Paul Warren
, and Herm Fischer.
(See http://www.xbrl.org/Specification/tbd/tbd.html)
OIMCOMMON
XBRL International Inc.. "XBRL Open Information Model Common Definitions"
Herm Fischer
, Mark Goodhand, and Paul Warren.
(See http://www.xbrl.org/Specification/tbd/tbd.html)
TABULAR METADATA
W3C (World Wide Web Consortium). "Model for Tabular Data and Metadata on the Web"
Jeni Tennison
, Gregg Kellogg, and Ivan Herman.
(See https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/)
TABULAR METADATA VOCABULARY
W3C (World Wide Web Consortium). "Metadata Vocabulary for Tabular Data"
Rufus Pollock
, Jeni Tennison, Gregg Kellogg, and Ivan Herman.
(See https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/)
URI
IETF (Internet Engineering Task Force). "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"
T. Berners-Lee
, L. Masinter, and R. Fielding.
(See http://tools.ietf.org/html/rfc3986)
XBRL 2.1
XBRL International Inc.. "Extensible Business Reporting Language (XBRL) 2.1 Includes Corrected Errata Up To 2013-02-20"
Phillip Engel
, Walter Hamscher, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XBRL-2.1/REC-2003-12-31/XBRL-2.1-REC-2003-12-31+corrected-errata-2013-02-20.html)
XML Names
W3C (World Wide Web Consortium). "Namespaces in XML 1.0 (Third Edition)"
(See http://www.w3.org/TR/2009/REC-xml-names-20091208)

Appendix B Intellectual property status (non-normative)

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to XBRL International or XBRL organizations, except as required to translate it into languages other than English. Members of XBRL International agree to grant certain licenses under the XBRL International Intellectual Property Policy (www.xbrl.org/legal).

This document and the information contained herein is provided on an "AS IS" basis and XBRL INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

The attention of users of this document is directed to the possibility that compliance with or adoption of XBRL International specifications may require use of an invention covered by patent rights. XBRL International shall not be responsible for identifying patents for which a license may be required by any XBRL International specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. XBRL International specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents. XBRL International takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Members of XBRL International agree to grant certain licenses under the XBRL International Intellectual Property Policy (www.xbrl.org/legal).

Appendix C Document History (non-normative)

DateAuthorDetails
02 May 2017Paul Warren

First Public Working Draft

Appendix D Errata Corrections incorporated in this document

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 Specification Maintenance Working Group (SWG) up to and including 02 May 2017. Hyperlinks to relevant e-mail threads may only be followed by those who have access to the relevant mailing lists. Access to internal XBRL mailing lists is restricted to members of XBRL International Inc.

No errata have been incorporated into this document.

Appendix E CSV report model

The following figure shows the model of a CSV report.

CSV Report Model

The model contains metadata describing the mapping from CSV tables to OIM facts and footnotes. The components are: