Copyright © 2015 XBRL International Inc., All Rights Reserved.
Circulation of this Document is unrestricted. Other documents may supersede this document. Recipients are invited to submit comments to spec@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.
1 Introduction
1.1 Notation
2 Segment and scenario
2.1 Recommendations
3 Dimensional validity
3.1 Open hypercubes
3.2 Use cases for open hypercubes
3.3 Negative hypercubes
3.4 Non-dimensional facts
3.5 Recommendations
4 Positive and negative hypercubes
4.1 Recommendation
5 Dimension defaults
5.1 Recommendation
6 Complex typed dimensions
6.1 Recommendations
A References
B Intellectual property status (non-normative)
C Acknowledgements (non-normative)
D Document history
E Errata corrections in this document
1 Validity of facts against individual hypercubes
2 Validity of facts against multiple hypercubes
3 Validity of facts against negative hypercubes
4 Dimensions used on non-dimensional facts
5 Defining invalid regions
6 Defaulted dimensions
The XBRL Dimensions specification [DIMENSIONS] reached Recommendatation status in 2006. Since then, practical usage of the specification has uncovered a number of features in the specification which are either unnecesary, or which can lead to undesirable results if not used carefully. This document enumerates these issues, and where possible, provides guidance on if and how such features should be used.
This scope of this Working Group Note, published by the Base Specification and Maintenance Working Group is restricted to the technical implications of particular dimensional constructs and features, and is not intended to provide comprehensive best practice guidance on the use of XBRL Dimensions.
In order to make examples more readable, this document uses a short-hand notation to describe dimensional facts and hypercubes. The following denotes a fact reported against concept "C" with member "m1" for dimension "d1" and member "m2" for dimension "d2":
C[d1=m1,d2=m2]
The following example denotes a hypercube, H, with a dimension A with usable members a1 and a2, and a dimension B, with usable members b1 and b2:
H[[A={a1,a2},B={b1,b2}]]
The XBRL v2.1 specification provided two containers for providing additional
information about the nature of a reported fact: the <segment> and
<scenario> elements contained within the context. Both of these
containers can contain arbitrary XML content, with the XBRL v2.1 specification
providing no mechanism for defining or constraining the information that
appears within these elements.
The XBRL Dimensions specification provides a more structured way to define additional information about the nature of a reported fact. This is preferrable to using arbitrary XML elements within segment and scenario, as the meaning of XBRL Dimensions can be precisely defined and constrained using an XBRL taxonomy.
The syntactic constructs which appear in an XBRL instance document to represent
such dimensional qualifications may appear within either the <segment> or
<scenario> elements, depending on the definition of the relevant hypercube.
As the meaning of an XBRL Dimension can be defined precisely and completely
within an XBRL taxonomy, separately grouping them into the broad categories of
"segment" and "scenario" offers little additional value. As the decision as to
whether an individual dimension appears within <segment> or
<scenario> is attached to the hypercube as a whole rather than to
individual dimensions, attempting to classify dimensions between the two
introduces additional complexity as additional hypercubes must be introduced.
Common practice in taxonomy design is to select one or other out of the two options, and to use it for all hypercubes within a taxonomy. The choice between segment and scenario is arbitrary: in effect, the greater precision of dimension definition offered by the XBRL Dimensions specification renders the broad, binary classification offered by the XBRL v2.1 specification redundant from a technical perspective.
<segment> and <scenario> elements should only be used to contain XBRL Dimensions, and should not be used to contain other XML elements (this will be enforced where a <segment> or <scenario> element is constrained by a closed hypercube) <segment> and <scenario> for its hypercubes exclusively. <scenario> only.It is desirable, and most likely expected, behaviour that an XBRL fact which is considered dimensionally valid has had each of its associated dimensional values validated against a domain that is defined in the taxonomy as being applicable to that dimension. We shall refer to this property as Full Dimensional Validity
There are a number of ways of using the XBRL Dimensions specification [DIMENSIONS] which allow a fact to be considered Dimensionally Valid without requiring Full Dimensional Validity. This section outlines these scenarios, and provides recommendations for avoiding them.
Where Full Dimensional Validity is not enforced, no assumptions can be made about the unvalidated dimensional values. In the case of an explicit dimensional value, there is no guarantee that the referenced member exists in the taxonomy, meaning that a process may not be able to find labels or other meta-data for the member. Further, even if the member does exist as a concept, there is no information available about the relative ordering or hierarchy between dimensional members. In the case of a typed dimensional value, there is no requirement that the value is checked against the corresponding data type.
The discussion in this section assumes that the above recommendation to use
only one of <segment> and <scenario> for dimensions, and that
the other container is enforced to be empty.
The XBRL Dimensions specification allows hypercubes to be declared as either "open" or "closed". This alters the validation rules that are applied when considering whether a fact with dimensions is valid.
Initially, we will consider only hypercubes that are associated to concepts by an "all" relationship (or "positive hypercubes"). Hypercubes associate via "notAll" relationships ("negative hypercubes") are discussed later in Section 3.3.
In order to be considered valid against a closed hypercube, a fact must include a dimension value for each dimension associated with that hypercube (except for those with dimension defaults, which may be omitted), and may not include dimension values for any other dimensions.
On the other hand, a fact will be considered valid against an open hypercube even if it includes values for dimensions that are not part of the hypercube, provided that it includes a valid value for each dimension that is part of the hypercube (or omits those with dimension defaults).
For example, consider a concept C associated with hypercube H1[[A={a},B={b}]] by an "all" relationship. Facts have the following validity against this hypercube:
| Fact | Hypercube Open/Closed | Validity | Notes |
|---|---|---|---|
| C[A=a,B=b] | Either | Valid | |
| C[A=a,B=x] | Either | Invalid | x is not a valid member of B |
| C[A=a] | Either | Invalid | Does not contain all dimensions for hypercube H |
| C[A=a,B=b,D=d] | Closed | Invalid | Contains a dimension that is not part of the hypercube |
| C[A=a,B=b,D=d] | Open | Valid | Additional dimension is allowed by open hypercube |
It should be noted that in the last case, no validation of the "D" dimension occurs. A concept or member called "d" may or may not be present in the taxonomy, and even where it is, there is no domain-member tree attached to the hypercube which would provide the relative ordering and hierarchy of values used for the "D" dimension.
The example above demonstrates the validity of a fact against an individual hypercube. A concept may be associated with multiple hypercubes, in which case the overall validity of a fact is determined by whether it is valid against at least one of the associated hypercubes. The use of open hypercubes can have undesirable consequences in the case of a concept being associated with multiple hypercubes where the dimensions of one are a subset of another.
Consider now that C is associated with a second hypercube, H2[[A={a},B={b},D={d}]]
Now consider the fact C[A=a,B=b,D=x].
If H1 is open, then this fact will be considered valid, even though x is not a valid member for the dimension D in hypercube H2. This is because the fact can successfully be validated against H1 as, being an open hypercube, the additional dimension D is allowed and not checked further.
If H1 is closed, then this fact is invalid against H1, because H1 does not allow dimension D, and invalid against H2, as x is not a valid member for dimension D. The fact is therefore dimensionally invalid.
The validation semantics shown in the example are almost certainly both unexpected and undesirable. If dimension defaults are used, this problem is extended from hypercubes that are a subset of another's dimensions, to hypercubes which have sets of dimensions which are merely overlapping.
The use case of open positive hypercubes is unclear. If a given reporting environment does not allow extensions, then a taxonomy author will know about all dimensions which are available in the taxonomy, and is in a position to create closed hypercubes that explicitly allow all permissible combinations. The use of dimension defaults makes it easy to be very flexible in the allowed combinations.
On the other hand, in a reporting environment where taxonomy extensions are permitted, whilst the original taxonomy author may not know about all possible dimensions, authors of an extension taxonomy are in a position to create or extend closed hypercube definitions to meet their needs.
Concepts may be associated with hypercubes by one of two relationships: "all" or "notAll". These are often referred to as creating positive and negative hypercubes respectively. Negative hypercubes specify combinations of dimension members which are invalid.
It is valid for a concept to have only negative hypercubes in a given base set. This arrangement immediately precludes Full Dimensional Validity, as any combination of dimension values which is not explicitly excluded by the associated hypercubes will be considered valid.
A more normal arrangement is to use negative hypercubes only in conjunction with a positive hypercube to disallow specific regions within that positive hypercube. In order to have any effect, the negative hypercube must describe a region that is within the positive hypercube which means that it must either be associated with the same set of dimensions as the positive hypercube, or with a strict subset of those dimensions. In the latter case, it is necessary for the negative hypercube to be "open" in order that it applies to facts with all dimensions required by the positive hypercube.
For example, consider a concept C associated by an "all" with closed hypercube H:
and by a "notAll" relationship with hypercube N
Facts have the following validity against this combination of hypercubes:
| Fact | Hypercube N Open/Closed | Validity | Notes |
|---|---|---|---|
| C[A=a2,B=b1,C=c1] | Either | Valid | Not in the region excluded by N |
| C[A=a1,B=b1] | Either | Invalid | Does not include all necessary dimensions for H |
| C[A=a1,B=b1,C=c1] | Open | Invalid | N excludes A=b1, B=b1, and can ignore C as it is open. |
| C[A=a1,B=b1,C=c1] | Closed | Valid | N is closed and does not include dimension C |
When defining a negative hypercube, it may be convenient to specify a proper subset of the dimensions allowed by the positive hypercube. In this case, the negative hypercube must be "open" in order to allow the remaining dimensions to take any value allowed by the positive hypercube.
As noted above, a fact is considered dimensionally valid if it is valid against at least one of the hypercubes with which its concept is associated. Where a fact is reported against a concept with no associated hypercubes, dimensional validation is not applied at all, even if the fact includes XBRL dimension values. The result is the same as if the concept were associated with an open hypercube with no dimensions. This can be avoided by associating the concept with an empty, closed hypercube.
Consider a concept Revenue that is not associated with any hypercubes. As no dimensional validation takes place, reporting facts against this concept with dimensions is valid, for example:
Revenue[Country=UK] = $10
The dimension Country and the member UK are not
validated in any way, and may not even be present in the taxonomy, so all of
the following would also be valid:
Profit[LoanMaturity = OneYear] = $10
Profit[LoanMaturity = Europe] = $10
Profit[LonMaturty = eUrope] = $10
Associating the concept with a closed, empty hypercube would prevent any dimensions from being reported on corresponding facts.
It is desirable that all dimensional facts have Full Dimensional Validity. This gives rise to the following specific recommendations:
In order to achieve the expected validation semantics, negative hypercubes should be open (in some scenarios, this will lead to the same validation semantics as a closed hypercube, but the recommendation is stated as is in the name of simplicity).
It is often the case that some combinations of dimensional values within a hypercube not considered valid reporting points, and it is desirable to prevent reports from including facts against these points. There are a number of different approaches for achieving this:
Negative hypercubes allow invalid regions within a positive hypercube to be precisely identified, and enforced by XBRL Dimensons validation, however the concept of negative hypercubes can be unintuitive, and the syntax used to construct them is complex.
From a validation perspective, anything that can be achieved by combining negative hypercubes with a positive hypercube can be achieved by combining multiple positive hypercubes, but this is not to say that the two approaches are entirely equivalent. An approach that uses only positive hypercubes loses information about the relative positions of the valid regions. This is shown in the following example:
Consider the following table, with two dimensions, A={a1,a2} and B={b1,b2}.
| A=a1 | A=a2 | |
|---|---|---|
| B=b1 | 1 | |
| B=b2 | 2 |
Only the two points labelled 1 and 2 are valid. This can be modelled using a positive hypercube for the whole table:
P1[[A={a1,a2}, B={b1,b2}]]
and two negative hypercubes:
N1[[A={a1}, B={b1}]]
N1[[A={a2}, B={b2}]]
The same validation semantics can be acheived with two positive hypercubes, identifying the two allowed cells:
P2[[A={a1}, B={b2}]]
P3[[A={a2}, B={b1}]]
What is lost in this arrangement is the relative positioning of the two valid cells. When using the first approach, the dimensions attached to the positive hypercube P1 give us the overall order of the members for those dimensions. i.e. a1 comes before a2, b1 comes before b2. In this second example, we have two completely independent regions of allowed space:
| A=a1 | |
|---|---|
| B=b2 | 2 |
| A=a2 | |
|---|---|
| B=b1 | 1 |
It is not possible to infer the arrangement shown in the original table from the information present in the taxonomy.
The importance of maintaining the overall structure of the main hypercube will depend on the application. Where the Table Linkbase specification is used to provide table renderings, the importance of maintaining the structure of tables in the dimensional definition is diminished.
The third approach of using external validation, such as XBRL Formula, to define disallowed regions means that the overall structure of the table can be maintained in a single positive hypercube, but it introduces a different potential problem. XBRL Formula, and other such mechanisms, do not lend themselves to static analysis. In other words, whilst they can identify whether a given fact is valid or not, they cannot readily provide a list of the allowed facts. This makes it impossible to present the type of view shown in the original example where disallowed cells are greyed out.
The XBRL Dimensions specification allows facts dimensions to have a default value. This is a value that may be assumed when the dimension is not reported for a fact.
For example, consider the concept "Revenue" associated with hypercube HC:
HC[[Region={All Regions,Asia-Pac,EMEA,Americas},Segment={Services,Products}]].
By providing a default for "Region" of "All Regions", a fact reported as:
Revenue[Segment=Services]
is understood to mean:
Revenue[Region=All Regions, Segment=Services]
and is valid against the HC hypercube.
Dimension defaults can be appealing, as it means that a fact that requires a dimension, but which is reported against the "total" member ("Region=All Regions", in the example above) are reported consistently to those which do not require that dimension at all.
It should be noted that dimension defaults are global, and apply to all facts that do not explicitly report a value for that dimension, regardless of the hypercubes with which the concepts are associated. This can lead to somewhat unintuitive behaviour. In the example above, applying the default of "Region=All Regions" across all facts may seem reasonable, but consider a dimension used to indicate loan maturity, for example:
Maturity={All Maturities, Less than 1 year, More than 1 year}
In this case, "All Maturities" is the natural choice for a default, but it may be unintuitive to see this associated with facts that are unrelated to loans, such as the Revenue fact reported above. This is not inherently problematic, but tools may correctly show all default dimensions when displaying a fact.
Choosing a default value which is not the natural total for a dimension is clearly more problematic. For example, selecting "Less than 1 year" as the default for the "Maturity" dimension would mean that the Revenue fact reported above would be understood to mean:
Revenue[Region=All Regions, Segment=Services, Maturity=Less than 1 year]
This is unlikely to be what was intended.
The XBRL Dimensions specification allows for the creation of typed dimensions based on any XML Schema data type. Common practice is to use XML Schema simple types for typed dimensions, but the specification explicitly allows the option of using complex types.
A complex type effectively allows a single dimension value to be made up of
multiple component values. Complex typed dimensions are inherently difficult
for XBRL tools to render, or provide a data-entry interface to. In the case of
a simple typed dimension, the dimension provides labels for the dimension
value. For example, a simple typed dimension representing a customer number
might have a dimension called <CustomerID> , with a type of
xsd:integer, and an English label of "Customer Number" associated
with it. An XBRL tool can use that label to describe the single dimension
value provided by the simple type, and taxonomy authors are free to provide
labels in other languages (or with other types).
In the case of a complex typed dimension, there is no mechanism for providing labels for the elements that make up the complex type. The XBRL Dimensions specification uses an example of a telephone number as a complex typed dimension, with separate elements representing the country code, city code and number:
There is no mechanism for labelling the contained elements such as
<phone> or <country> so in the absence of hard-coded
information about the taxonomy, an XBRL tool has no way of displaying this
information in a user-friendly format, and will typically resort to exposing
the raw XML to the end-user.
The example from the Dimensions specification is not particularly realistic: where telephone numbers are included in a taxonomy, they are typically modelled as concepts, rather than dimensions, and are not typically broken up into components. More generally, real world experience has not yet revealed any use cases for complex typed dimension that cannot be adequately (or better) represented as multiple simple typed dimensions.
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).
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 Base Specification and Maintenance Working Group up to and including 25 March 2015. 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.