This Proposed Recommendation has been approved for publication by the XBRL Standards Board. Proposed Recommendation status indicates that the document is complete, and will move to Recommendation status if no adverse feedback is received.
This document serves to document the motivation behind certain design decisions made in the development of the xBRL-CSV Table Constraints specification.
The decimals suffix is incompatible with the philosophy of Table Constraints, in which data rows should be uniform and the type constraint of each constrained column is intended to provide enough information for a processor to extract values from the column. Also, supporting the decimals suffix would significantly complicate the specification, delay its completion and require additional effort from implementors for no gain. Supporting this feature will be reconsidered in future versions of the Table Constraints specification.
The specification requires that any fields in a unique key on which the timeZone property is applicable have that property specified. This ensures that all values for that field are consistent in whether or not they have a time zone component. Date or date/time values with a time zone are not fully comparable to those without a specified time zone. For example, it is not possible to say whether 2026-01-01T12:00:00 (unspecified time zone) is before or after 2026-01-01T12:00:00Z (UTC time zone).
Although full comparability is only actually required if the key is used for row sorting, a consistent approach to time zones is considered good practice, and so for simplicity the specification requires the timeZone property on all such fields in a unique key, whether or not they are used for sorting.
Certain Table Constraints checks are applied after applying xBRL-CSV special value processing. In some cases, the value may not actually be subject to special value processing by the xBRL-CSV specification. This approach was taken because determining whether a value will be subject to special value processing is not trivial, and it is technically possible for a single value to be subject to special value processing in some cases, but not others. Row ID columns are not subject to special value processing and all of the special values (#none, #nil, #empty) would be invalid values for a row ID. Therefore, Table Constraints takes the simplified approach of consistently applying special value processing before applying constraints.
The specification imposes the following constraints on key names:
Requiring reference keys to have unique names across all templates would put an additional burden on designers setting those names as they need to take into account all templates including templates imported from other taxonomies. As there is no clear benefit from unique reference key names, this uniqueness of names is not imposed.
xBRL-CSV allows the values for dimensions and the decimals property to be defined using
parameter references. For example, xBRL-CSV metadata might specify the unit
dimension as being $currency. In this case, a value for the dimension would
be taken from the currency column if such a column exists and has a value in
the current row, and if not, a value would be taken from a parameter with that
name, if present.
This mechanism presents significant complexity for Table Constraints, as it would require processors to take into account these fall-back values when considering key uniqueness and ordering, and when checking value constraints more generally. This is complicated by the fact that where a column is providing fact values (a fact column) no such fall-back mechanism exists; if there is no value, no fact is created. The xBRL-CSV specification permits a single column to be both a fact column and also to be the target of a parameter reference. This means that a column may or may not fall-back on parameter values depending on context.
In order to simplify application of Table Constraints, the specification
forbids parameters with the same name as columns
(tcme:columnParameterConflict and tcre:columnParameterConflict), thereby
ensuring that this fall-back never occurs.
Although this potentially increases table file size, by removing a defaulting mechanism that requires only "unusual" values to be explicitly reported, it significantly simplifies the application of Table Constraints, and ensures greater consistency in data tables.
The fields in a unique key may correspond to parameters or columns. Values for a key must be sorted, and a unique key may span multiple tables, in which case the values must be sorted across all tables. As parameters are specified at table (or report) level, they constrain which facts can appear in each table. Fields of a key are checked in order, so to ensure that it is possible for the values to be sorted across all tables, it is important that parameter fields precede column fields in the key definition.
Consider a composite unique key on Region and Year, with Region supplied by a table parameter and Year sourced from a column.
RevenueEU (region=EU)
year,revenue
2025,42
2026,43
RevenueGB (region=GB)
year,revenue
2025,12
2026,13
The rules for cross-table sorting require that:
for each table A for a template constrained by a unique key there MUST NOT exist another table B for that template for which (
tcre:keySortViolation):
- The key value for the last row of A is greater than or equal to the key value for first row of B; and
- The key value for the last row of B is greater than or equal to the key value for first row of A.
In other words, the range of key values in one table must not overlap with that of another table.
With a unique key of [Region, Year], the cross-table sort requirements are satisfied, because the key value [EU, 2026] is less than the key value [GB, 2025]. All rows in RevenueEU sort ahead of all rows in RevenueGB.
If the key were instead defined as [Year, Region], cross-table sorting would fail, as:
[2026, EU] is greater than [2025, GB]; and[2026, GB] is greater than [2025, EU]The correct ordering of key values is:
As the "EU" and "GB" rows appear in different tables, there's no way to order rows that will satisfy the cross-table sorting requirements.
The specification requires that fields in a key that is used as a sort key have
optional set to false. This constraint was added in earlier drafts of the
specification prior to the prohibition of parameter fallback (see
Section 7). In the absence of parameter fallback, this
constraint is not strictly required, as the question of what value to use when
a cell value is not provided does not arise. It has been retained as it
provides some simplicity, but it may be relaxed in future versions of the
specification.