XBRL v2.1 provides a mechanism for defining the calculation relationships that exist between XBRL Concepts, and a process for checking whether the facts in an XBRL Report are consistent with those relationships. The consistency checking process has a number of deficiencies, which can cause erroneous consistency failures on rounded values, and missed consistency failures where duplicate facts are present.
This specification defines alternative calculation functionality intended to address these deficiencies.
This specification makes use of QName notation for error codes. QName prefixes used in this specification are to be interpreted according to the following table:
| Prefix | Namespace URI |
|---|---|
| calc11e | https://xbrl.org/2023/calculation-1.1/error |
| oime | http://www.xbrl.org/2021/oim/error |
QNames in parenthetical red text after a "MUST" or "MUST NOT" statement prescribe standardised error codes to be used if the preceding condition is violated.
"MUST" and "MUST NOT" statements without an explicit error code define non-validation behaviour required of processor, or may refer to validation for which error codes are prescribed by another specification.
Text in a blue, bordered box is non-normative. It is intended to provide additional, explanatory commentary, and does form part of the formal specification.
Example of non-normative text.
This specification defines a process for checking the calculation consistency of facts in an XBRL report with relationships defined in an XBRL taxonomy, and prescribes error codes to be raised if a report is found to be inconsistent (see Section 5.2).
The specification defines a new arcrole that is used to define calculation relationships to which the semantics defined in this specification apply. Processors implementing this specification may optionally apply the semantics described in this specification to relationships defined using the XBRL v2.1 Specification "summation-item" arcrole (see Section 4.1).
This specification defines three classes of error condition that MUST be detected by a conformant processor:
The following codes are classified as calculation inconsistencies:
oime:disallowedDuplicateFactscalc11e:disallowedDuplicateFactsUsingTruncationcalc11e:excessDigitscalc11e:inconsistentCalculationUsingRoundingcalc11e:inconsistentCalculationUsingTruncationThe following codes are non-fatal warnings:
calc11e:oimIncompatibleReportWarningcalc11e:tuplesInReportWarningNote that other specifications MAY upgrade the above calculation inconsistencies to validation errors. For example, the "Allowed Duplicates" feature in xBRL-CSV and xBRL-JSON can be used to prohibit certain classes of duplicate facts. Similarly, the non-fatal warnings are only applicable in a system that does not otherwise require OIM compatible reports (see Section 3.2).
The following codes are classified as validation errors:
calc11e:nonDecimalItemNodecalc11e:duplicateCalculationRelationshipsCalculation inconsistencies do not necessarily indicate a problem with a report. For example, inconsistencies may be raised when there are sufficient facts reported for a calculation to bind but not all contributing facts are reported.
Local filing rules may choose to treat some or all of the calculation inconsistency codes as errors that would cause a filing to be rejected.
This specification makes use of definitions from the Open Information Model, and can be applied to XBRL reports in any OIM-compatible format including xBRL-XML (XBRL v2.1 instance documents), xBRL-JSON, and xBRL-CSV.
xBRL-XML Section 2.1 defines constraints that xBRL-XML reports are required to conform to in order to be loaded into the Open Information Model. Conformant processors MUST apply the constraints as follows:
If the only error(s) raised are xbrlxe:unsupportedTuple, the error(s) are
replaced with a non-fatal warning (calc11e:tuplesInReportWarning), and
the processing defined by this specification continues as if the tuples, the
items in the tuples and any footnote relationships in which they are involved
were not present.
If any other errors are raised, they are replaced with a non-fatal warning (calc11e:oimIncompatibleReportWarning), and no further Calculations 1.1 processing is performed.
This specification does not constrain how many times each warning is reported.
Processors MAY replace all xbrlxe errors with a single instance of the
relevant warning, or MAY produce one warning per error.
The Inline XBRL v1.1 specification defines how to map Inline XBRL reports into XBRL v2.1 instance documents (xBRL-XML reports), and as such, this specification can also be applied to Inline XBRL reports, provided that the resulting xBRL-XML reports comply with the constraints referenced above.
The approach described above is intended as a transitional measure in order to
avoid the situation where a processor with support for this specification
enabled raises xBRL-XML constraint errors on non-OIM compliant reports,
which may not even have summation-item relationships defined in the taxonomy.
The requirement in this specification to downgrade OIM constraint errors to a warning is not intended to prevent the rejection of incompatible reports when a processor is deployed in a system that requires OIM compatibility for other purposes. Where a reporting system requires OIM compatibility, reports should be rejected using the codes specified in the xBRL-XML specification prior to attempting the processing defined in this specification.
A summation-item relationship is an effective relationship defined by a calculationArc element with an arcrole of http://www.xbrl.org/2003/arcrole/summation-item or https://xbrl.org/2023/arcrole/summation-item .
An XBRL v2.1 calculation relationship is a summation-item relationship with an arcrole of http://www.xbrl.org/2003/arcrole/summation-item.
A Calculations v1.1 relationship is a summation-item relationship with an arcrole of https://xbrl.org/2023/arcrole/summation-item (see Appendix A).
An effective relationship is an XLink relationship that has not been prohibited or overridden by an arc with a higher priority, as described in XBRL v2.1 section 3.5.3.9.7.
Calculations v1.1 validation is the process of applying the calculation checking described in Section 5.
XBRL v2.1 calculation consistency checking is the process of the behaviour described in XBRL v2.1 section 5.2.5.2 and signalling inconsistencies between an XBRL report and XBRL v2.1 calculation relationships.
The source and target of a Calculations v1.1 relationship MUST both be a decimal concept (calc11e:nonDecimalItemNode).
A processor implementing this specification MUST apply Calculations v1.1 validation to Calculations v1.1 relationships.
Processors MAY provide a mode of operation that allows Calculations v1.1 validation to be applied to XBRL v2.1 calculation relationships. Processors that do this:
XBRL v2.1 prescribes no behaviour for Calculations v1.1 relationships and XBRL v2.1 calculation consistency checking MUST NOT be applied to them.
Calculations v1.1 relationships and XBRL v2.1 calculation relationships form two completely independent networks, and in the event that both are present in the same taxonomy, validation MUST be applied to each network separately.
Errors raised under either Calculations v1.1 validation or XBRL v2.1 calculation consistency checking do not invalidate an XBRL Report and users and integrators of XBRL processors are free to choose if and how they are handled.
Entities that accept XBRL Reports as part of a filing system should make it clear how calculation validation results will be handled, and if using taxonomies that use XBRL v2.1 calculation relationships, specify whether Calculations v1.1 validation or XBRL v2.1 calculation consistency checking will be applied.
Inconsistencies raised by Calculations v1.1 validation are primarily a subset of those raised under XBRL v2.1 calculation consistency checking, although Calculations v1.1 additionally permits checking of calculations involving some classes of duplicate facts.
Taxonomy authors are encouraged to replace XBRL v2.1 calculation relationships with Calculations v1.1 relationships when updating their taxonomies, in order to obtain improved and unambiguous calculation behaviour. Taxonomy authors are discouraged from including both XBRL v2.1 calculation relationships and Calculations v1.1 relationships in the same taxonomy.
Calculations v1.1 relationships are defined using <calculationArc> elements, and as such the constraints between balance attributes and calculation weights defined in section 5.1.1.2 of XBRL v2.1 apply to Calculations v1.1 relationships.
Calculations are defined in a taxonomy using summation-item relationships.
A calculation is the set of all summation-item relationships sharing a common total concept, a common extended link role, and a common arcrole (see Section 4.1).
There MUST NOT be more than one summation-item relationship with the same total concept and the same contributing concept within a single calculation (calc11e:duplicateCalculationRelationships). Note that XBRL v2.1 section 3.5.3.9.7.5 prescribes some de-duplication of relationships, which MUST be applied prior to this check.
A report can be checked for consistency with a set of calculations, and an error is raised wherever the reported facts are inconsistent with the defined calculations. Each calculation is checked wherever there are sufficient dimensionally aligned facts for it to "bind", as described in Section 5.1.
A reported data point is a set of dimension values for which there exists at least one fact with that set of dimension values as its {dimensions} property and that has a non-nil value. The OIM definition of equal dimension value is used when comparing dimension values.
A calculation binds wherever the following conditions are met:
Two reported data points, a and b, are dimensionally aligned if for every dimension other than the concept core dimension in the {dimensions} property of a, the same dimension is present in b with an equal dimension value.
Where a calculation binds, the consistency of the calculation is determined as follows:
If the rounding mode is "round-to-nearest", the error code calc11e:inconsistentCalculationUsingRounding MUST be raised for each binding of a calculation that is not consistent.
If the rounding mode is "truncation", the error code calc11e:inconsistentCalculationUsingTruncation MUST be raised for each binding of a calculation that is not consistent.
In order to establish the consistency of a calculation, it is necessary to know the set of possible values from which a reported value may have been rounded. This will depend on the rounding method that has been used. This specification defines two possible rounding modes.
Processors implementing this specification are required to support both rounding modes. A single rounding mode MUST be used consistently for all calculations in a report. The rounding mode used SHOULD be a run time configuration option.
The fact value interval for a fact is the range of possible values that the reported fact value is consistent with having been rounded or truncated from, depending on the rounding mode.
The rounded fact value interval for a fact is the range of possible values that
the reported fact value is consistent with having been rounded from, allowing for a "half" value to have been rounded either up or down. For a
fact with {value} v, and finite {decimals} property d, it is defined as:
[v-0.5*10^(0-d), v+0.5*10^(0-d)]
For a fact with a {decimals} property of "infinity", it is defined as the single point interval:
[v, v]
For example, a fact with a value of 5,000 and decimals = -3 represents a rounded fact value interval of:
[5000 - 0.5 * 10^3, 5000 + 0.5 * 10^3]
= [5000 - 500, 5000 + 500]
= [4500, 5500]
Note that all intervals for rounded values are "closed", meaning that they include both the upper and lower bound. The above example indicates that the reported value of 5,000 (decimals = -3) is consistent with having been rounded (down) from 5,500. A reported value of 6,000 (decimals = -3) is also considered consistent with having been rounded (up) from 5,500, even though under any single rounding method only one of these can be correct.
Two intervals are still considered to overlap where the upper bound of one interval is equal to the lower bound of the other, for example [4500, 5500] and [5500, 6500].
The use of closed intervals allows consistency checking to be performed without knowing the how "ties" are treated, but makes the check lax on certain edge cases.
The truncated fact value interval for a fact is the range of possible values that
the reported fact value is consistent with having been truncated from. For a
fact with {value} v, and finite {decimals} property d, the interval is obtained as follows:
The reported value v is first truncated to its stated precision, by replacing
any non-zero digits to the right of the dth decimal place with zero.
The interval is then:
If v > 0:
[v, v+10^(0-d))
If v < 0:
(v-10^(0-d), v]
If v == 0:
(v-10^(0-d), v+10^(0-d))
For a fact with a {decimals} property of "infinity", it is defined as the single point interval:
[v, v]
For example, a fact with a value of 5,000 and decimals = -3 represents a truncated fact value interval of:
[5000, 5000 + 10^3)
= [5000, 5000 + 1000)
= [5000, 6000)
Note that the intervals used for truncation are half-open. They include the bound closest to zero, but not the bound furthest from zero. In the special case of a zero value, they do not include either bound.
A fact has digits in excess of the declared precision if there are non-zero digits to the right of the position identified by the value of the {decimals} property. A fact with a {decimals} property of "infinity" cannot have digits in excess of the declared precision.
More formally, a fact has digits in excess of the declared precision if the {decimals} property is not "infinity" and the reported value is not an integer multiple of 10^(-d) where d is the value of the {decimals} property.
For example, the value 1,100,000 with decimals = -6 has a non-zero in the 100,000s column (10^5) and so has "digits in excess of the declared precision". 1,000,000 (decimals = -6) and 1,100,000 (decimals = -5) are both consistent with their declared precision.
The {decimals} property indicates that the reported value for a fact has been rounded or truncated to the specified number of decimal places. If there are digits to the right of the position identified by the {decimals} property, then the reported value is not consistent with having been rounded to that level, and an error is raised if the value is used in a binding calculation.
Note that this specification only requires an error to be raised where such facts are used in a calculation. Local filing rules may prohibit all such facts.
Where duplicate facts are present in a report, the values may or may not be consistent with having been rounded or truncated from a single underlying value. The Open Information Model provides definitions of consistent duplicates and inconsistent duplicates. These definitions assume that "round to nearest" is used, and are not compatible with the "truncation" rounding mode. Therefore this specification provides a modified definition referred to as calculation 1.1 consistent duplicates.
Two facts are calculation 1.1 consistent duplicates if they meet the specification for OIM duplicate facts, with the modification that the interval used to establish numeric value consistency is the fact value interval, as defined in this specification.
Two facts are calculation 1.1 inconsistent duplicates if they meet the specification for OIM inconsistent duplicates, with the modification that the reference to consistent duplicates is replaced with calculation 1.1 consistent duplicates.
Where this specification requires that an error for inconsistent duplicates be raised, the following error codes should be used:
Where the rounding mode is "round-to-nearest", the definitions of calculation 1.1 consistent duplicates and OIM consistent duplicates are equivalent.
Where consistent duplicates are present, the calculation is performed using the intersection of fact value intervals for all facts within the set. For example, if we have the following consistent duplicates and intervals ("round-to-nearest" rounding mode):
5000 (decimals = -3) => [4500, 5500]
5500 (decimals = -2) => [5450, 5550]
These facts are consistent with having been rounded from a value in the range [5450, 5500], so this is the interval used for the calculation.
Where a reported data point has only a single fact (no duplicates) the calculation is performed with that fact's fact value interval.
This specification requires an error to be raised wherever a calculation binds to a reported data point that has two facts that are calculation 1.1 inconsistent duplicates (Section 5.2).
Other specifications, or local filing rules, may require that all facts in the report are consistent duplicates, or complete duplicates, in which case the consistency checking required by this specification is redundant (assuming "round-to-nearest" rounding mode).
A set of duplicates containing only nil values is considered consistent, but is ignored for the purposes of calculation binding and consistency checking. Any set of duplicates containing a mixture of nil and non-nil values is considered inconsistent, and an error must be raised if it is included in a binding calculation.
The process described above requires two interval arithmetic operations: multiplication and addition.
Addition of two intervals, is defined as:
[x1, x2] + [y1, y2] = [x1 + y1, x2 + y2]
The required multiplication is between an interval from a contributing fact, [x1, x2], and the contribution weight, w, which is effectively a single point interval, [w, w]. The required calculation is:
[x1, x2] * [w, w] = [min(x1 * w, x2 * w), max(x1 * w, x2 * w)]
This section contains XML files that form part of this specification. Each document has a standard publication URL, at which the normative copy of the document is published. A non-normative copy of each document is included in this appendix for convenience.
All references to these documents made for the purposes of DTS Discovery MUST resolve to the publication URL, after applying XML Base processing (where applicable) and resolving any relative URLs.
It should be noted that the path component of a URL is case-sensitive, and so must match exactly. Further, alternative hosts and schemes that happen to resolve to the same location are not considered equivalent and may not be used. See RFC3986 for more details on URL equivalence.
The requirement to reference documents by publication URL does not prevent processors from substituting local copies of the documents for performance or other reasons.
The publication URL for this schema is https://www.xbrl.org/2023/calculation-1.1.xsd.
<?xml version="1.0" encoding="UTF-8"?>
<!-- (c) 2013-2023 XBRL International. All Rights Reserved.
http://www.XBRL.org/legal/ This document 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. XBRL(r), is a trademark or
service mark of XBRL International, Inc., registered in the United States
and in other countries. -->
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:link="http://www.xbrl.org/2003/linkbase"
attributeFormDefault="unqualified" elementFormDefault="qualified"
targetNamespace="https://xbrl.org/2023/calculation-1.1"
>
<xsd:annotation>
<xsd:appinfo>
<link:arcroleType arcroleURI="https://xbrl.org/2023/arcrole/summation-item" id="summation-item" cyclesAllowed="undirected">
<link:definition>Calculation v1.1 summation-item arcrole</link:definition>
<link:usedOn>link:calculationArc</link:usedOn>
</link:arcroleType>
</xsd:appinfo>
</xsd:annotation>
</xsd:schema>
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 Working Group (SWG) up to and including 2024-02-14.
| Number | Date | Sections | Details |
|---|---|---|---|
| 1 | Section 4.1 | Require calculation relationships to be between decimal items (#25) | |
| 2 | Section 3.1 | Clarify validation status of error codes (#28) | |
| 3 | Section 4.1 | Non-normative note clarifying that balance attribute/calculation weight constraint applies to new calculation arcrole (#22) |
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 (https://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 (https://www.xbrl.org/legal).