This document serves to document the motivation behind certain design decisions made in xBRL-CSV. As the metadata format for xBRL-CSV is closely related to the xBRL-JSON syntax, this document should be read in conjunction with the xBRL-JSON design document.
xBRL-CSV constrains column headers to be "identifiers", which are strings that
cannot contain whitespace, amongst other constraints. This means that column
headers must be defined using a string such as country_of_incorporation
rather than a more human-readable "Country of incorporation".
As the column names are used to tie columns to their associated metadata, it was felt that restricted identifiers were more appropriate, particularly as human-readability of the CSV files is not a design priority.
There are many different dialects of CSV file in common use, varying in details such as escape characters and line endings. Consideration was given to allowing the metadata file to specify exactly which dialect of CSV is being used in a report.
It is expected that existing CSV files will not be used directly as part of an xBRL-CSV report; at least some degree of value transformation will typically be required. As such, requiring transformation to a required CSV dialect should not be a significant burden. It was decided to adopt a single, permissive CSV format that accomodates all of the most commonly used dialects, rather than the non-trivial additional complexity of making the dialect configurable.
Earlier drafts of the xBRL-CSV required all periods to be denoted using the full ISO8601 datetime format, minimising the burden on the implementers of consuming applications. This is consistent with the approach taken in xBRL-JSON, and removes any ambiguity about whether a date refers to the start or end of the day.
Many common applications of XBRL operate at a "whole day" level of granularity, and periods are naturally described using inclusive dates. For example, a year is typically described as running from "1st Janary to 31st December" (and includes both of those dates). Expressed as an ISO8601 duration, this would be:
2019-01-01T00:00:00/2020-01-01T00:00:00
This is both verbose, and unintuitive as the end date is expressed as the start of 1st January.
As compactness of representation is a design priority for xBRL-CSV, it was felt
that a more concise format should be supported, but in an attempt to avoid a
repetition of the confusion caused by XBRL v2.1's handling of dates and date
times, it was decided to use a different notation for the abbreviated syntax
with .. as the date separator. For example:
2019-01-01..2019-12-31
The .. separator is explicity defined as an inclusive date range, and cannot
be used with datetimes. Similarly, the / separator cannot be used with
dates.
Having taken the step to move away from a single notation for durations, in the name of conciseness and convenience, it was felt reasonable to add further abbreviated notations for common calendar periods, e.g.:
A primary use case for xBRL-CSV is the reporting of large volumes of data within a regulatory reporting environment. Such reporting environments are typically closed reporting systems, where the data to be reported is entirely prescribed by the data collector. In such a system, the ability of preparers to define the layout of the reported tables is neither required nor desirable.
On the other hand, where entities are publishing data in xBRL-CSV, it is desirable for such reports to be self-describing, by including metadata that documents the meaning of the CSV data tables.
xBRL-CSV's use of extensible metadata files caters for a number of scenarios:
It is anticipated that the designers of xRBL-CSV reports will wish to modularise metadata definitions, using separate metadata files for different reporting templates. xBRL-CSV supports inheritance from multiple metadata files, allowing the overall metadata definition to be assembled from such modular metadata definitions.
The specification allows the same properties to be inherited from multiple sources provided they have the same values. This is to allow common information, such as namespace declarations, to be inherited by all modular metadata definitions. Providing such modular definitions do not introduce namespace definitions that bind different values to the same prefix, they can be combined without conflict.
The specification has a number of constraints that required that data reported in CSV data files, and as parameter values, are incorporated into the resulting report model. For example, it is an error to have a value in a parameter column if there is not a value in at least one fact column that references it.
This is to avoid data that is included in an xBRL-CSV report not being reflected in the resulting report model, leading to potential disputes over unreflected data being shared to a regulator and therefore known (or not) by that regulator.
xBRL-CSV metadata files contain a top-level documentInfo object.
Amongst other properties, this includes a documentType string which
identifies the document as conforming to the xBRL-CSV specification.
A documentInfo object is also defined in xBRL-JSON, and it is planned to
include documentInfo objects in other JSON-based XBRL formats so that
processors can automatically determined document type.
documentInfo is also used to hold other information, including namespace
prefixes, and there was some discussion within the working group about which
components should be defined within documentInfo.
The principle that has been adopted is that documentInfo should be used to
contain information that is necessary is necessary to correctly understand the
rest of the document.