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 specification").
The decimals suffix notation 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 Table Constraints Requirements document describes a requirement for "record sub-types". The use case for this is where multiple different record types can fulfil a given role. For example, a "customer" may be either a company or a person. The information collected for these two record types differs, but there is a need for a customer identifier that is unique across all such records.
The specification addresses this requirement through the "shared unique key" feature. The different record types are collected in separate tables, with separate table templates that define the different columns and constraints required for each type. A unique key can then be defined as being "shared" across these different table templates, allowing the uniqueness of an identifier to be enforced across these different record types.
Note that the rules for cross-table sorting described in Section 8 do not apply across tables for different templates. This means that where a shared key is used, the range of values for a key used in one table may overlap with the range of values for the same key in a table for a different template, even where all such keys are specified as the sort key. This limits the ability of processors to optimise uniqueness checking, but enforcing sorting across different templates may yield constraints that are impossible to satisfy (or would require a potentially very large number of tables).
For the purposes of sorting (and enforcement of uniqueness) a value of "nil" is treated as equivalent to a value not being reported at all. Such values sort before all other values.
The specification prohibits the use of the length, minLength and
maxLength facets on xs:QName. These facets are specified as being
deprecated for use on xs:QName by the XML Schema specification, and have no
effect on values of this type. In order to avoid the potential confusion of
facets which do not have the expected effect, the Table Constraints
specification prohibits their use.
The OIM Report Model uses BCP47 language identifiers. These language identifiers cause some complexity for Table Constraints due to inconsistent approaches to case sensitivity and whitespace normalisation in different specifications.
BCP47 defines language identifiers as being case insensitive, and the
OIM Report Model treats them as such. The xs:language XML
Schema type is derived from xs:string, and treats the values as case
sensitive. In order to avoid the potential problems this creates for
establishing uniqueness, the specification prohibits the use of xs:language
in keys.
The specification provides a type of language for denoting the OIM Language
Core Dimension. Values for this type are required to be reported as lowercase
values, thereby avoiding the risk of duplicate facts resulting from language
dimension values that differ only in case.
It should be noted that there is no requirement that the language type only
be used on values for the OIM Language Core Dimension; it can be used on any
language value, and will enforce the requirement for lowercase values, and
permit the use of the value as a key field.
Where the xs:language type is used in constraints, it is recommend to also
provide a pattern facet to enforce a consistent case convention for reported
values. It may also be desirable to constrain the format of language codes, as
BCP47 provides considerable flexibility beyond the common one part
(language) and two part (language/region) codes.
The specification defines language as having an effective XML Schema base
type (lexical and semantic) of xs:string rather than xs:language. This is
because the xBRL-CSV specification does not prescribe any whitespace
normalisation for language dimension values, and therefore applying the
whitespace normalisation required by xs:language (which is derived via
xs:token) during Table Constraints processing would potentially lead to
acceptance of values that are invalid under xBRL-CSV processing.
The specification requires that the Table Constraints namespace URI can only be
bound to the prefix tc, but it does not require that the tc prefix can only
be bound to the Table Constraints URI. The former gives consistency, and
potential code efficiency: once a processor has verified that tc is being
used for the correct URI, the relevant keys (such as tc:constraints) can be
found with a simple fixed string look-up.
Permitting tc to be bound to other URIs avoids invalidating existing xBRL-CSV
reports that may already be using this prefix for other purposes. It also
allows the tc prefix to be re-used by future versions of the specification.