xBRL-CSV design 1.0

Working Group Notes 14 October 2020

This version
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
Mark Goodhand, CoreFiling <mrg@corefiling.com>

Table of Contents

1 Overview

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.

2 Identifier constraints on column headings

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.

3 Support for CSV dialects

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.

4 Abbreviated period syntax formats

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:


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:


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

5 Extensibility of metadata files

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:

6 Multiple inheritance of metadata files

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.

7 Completeness of mapping

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.

8 Document info

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.