XBRL Formula 1.0 is built on the assumption that XBRL reports are XML documents, as defined in XBRL v2.1. The more recent Open Information Model (OIM) specification defines a syntax-independent model for an XBRL report, and alternative formats for XBRL reports now exist, as defined by the xBRL-CSV and xBRL-JSON specifications. XBRL Formula provides a powerful mechanism of validating XBRL Reports, and it is desirable to be able to evaluate them directly on these new report formats.
Many XBRL Formula features have no specific dependency on XML, and can be applied directly to a non-XML-based report format. Other features cannot meaningfully be evaluated without reference to an XML document, and as such, cannot be used directly on a non-XML based report, such as xBRL-JSON and xBRL-CSV. Such rules can be evaluated by converting the reports to XML syntax, but doing so negates the performance benefits provided by the new formats.
This specification defines a subset of XBRL Formula that can be evaluated on OIM-based reports without any dependency on XML, and prescribes the expected behaviour of processors when evaluating XBRL Formula on non-XML report formats.
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, in this specification, are to be interpreted as described in IETF RFC 2119.
The keywords expanded name, NCName and QName are to be interpreted as described in the XML Names specification.
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" or "MUST NOT" statements that do not have a prescribed error code are not automatically enforceable, and processors are not required to detect violations.
This specification makes use of QName notation to refer to XML expanded names (the combination of a namespace URI and a localname, and the xBRL-JSON format make use of abbreviated forms for these identifiers. The prefixes used by this specification are shown in the table below. These prefixes are reserved prefixes.
| Prefix | Namespace URI |
|---|---|
| oimfe | https://xbrl.org/PWD/2023-07-26/oim-formula/error |
| xbrl | https://xbrl.org/2021 |
| f | https://xbrl.org/PWD/2023-07-26/function/fact |
| r | https://xbrl.org/PWD/2023-07-26/function/report |
| dtr-type | http://www.xbrl.org/dtr/type/* |
| xs | http://www.w3.org/2001/XMLSchema |
The prefix dtr-type denotes any namespace that is the namespace for a type defined in the Data Types Registry.
An OIM-compatible XBRL formula rule is an XBRL Formula rule that complies with Formula 1.0 and additionally complies with additional constraints of this specification.
When evaluating OIM-compatible XBRL formula, a processor MAY operated in OIM mode. In this mode, XBRL formula evaluation is modified as described in this specification in order to support evalation of XBRL reports that are not represented in XML.
The OIM compatibility flag is a hint that MAY be included in a DTS to indicate to processors that a taxonomy only contains OIM-compatible XBRL formula rules.
The OIM compatibility flag is defined by the combination of parameters with a local name of oim-compatible-formula, as follows:
oim-compatible-formula, and all such parameters have a value of true, then a processor evaluating the XBRL Formula rules in that DTS MAY assume that all XBRL Formula rules are OIM-compatible XBRL formula rules, and raise an error if an XBRL Formula rule that is not OIM-compatible XBRL formula rule is encountered.The definition of this flag is intended to cope with DTSs that are composed of taxonomies from multiple sources which may not all be OIM compatible. Taxonomy authors SHOULD define the parameter in a namespace that is under their control in order to avoid redefinition of parameters.
XBRL Formula makes use of XPath 2.0 expressions (see XBRL Variables Section 1.7). XPath 2.0 permits navigation of the XML node hierarchy. This cannot be supported on an OIM-based report, and so this specification defines a restriction to permitted XPath expressions.
This specification restricts the allowed XPath 2.0 grammar by replacing rule 21:
[21] ValueExpr ::= PathExpr
with:
[21] ValueExpr ::= FilterExpr
XPath expressions appearing within OIM-compatible XBRL formula MUST conform to this modified XPath grammar (oimfe:oimIncompatibleXPathExpression).
The following XPath 2.0 operators and functions MUST NOT be used within OIM-compatible XBRL formula (oimfe:oimIncompatibleXPathFunctionOrOperator).
XPath expressions are evaluated in the context of a context item.
The context item for XPath expressions used in XBRL Formula depends on where the expression is being used, and is defined by the Formula specifications.
The only permitted context items for XPath expressions in OIM compatible XBRL formula are:
xfi:relationship.type implementation defined object, as returned by the xfi:concept-relationships function.Where the context node is specified to be anything else (such as the <xbrli:xbrl> root element of an XBRL Report), an OIM compatible XBRL formula MUST NOT attempt to access the context node (oimfe:unsupportedContextNode).
The OIM fact object is a custom XPath object that represents facts. When operating in OIM mode, all occurrences of XML element nodes that represent facts are replaced with an instance of the OIM fact object.
Only the following operations are supported by OIM fact objects:
dm:typed-value accessor, which returns an atomic value representing fact's {value} property, as described below.dm:nilled accessor, which returns true if the fact's {value} property has a "nil" value.A processor MUST raise oimfe:unsupportedFactOperation if any other operation is attempted on an OIM fact object.
The type xbrl:fact is used in function signatures to denote parameters or return values that are an OIM fact object.
The value and datatype returned by the dm:typed-value accessor on an OIM fact object is as follows:
xs:QName values.dtr-type:SQNamesItemType then the value is a space-separated list of Clark notation values, with a datatype of xs:string.dtr-type:SQNameItemType then the value is a Clark notation value, with a datatype of xs:string.Functions in the Functions Registry have a flag to indicate their OIM-compatibility:
The OIM-compatibility of a function is denoted by the <oimStatus> element in the XML function definition. The value of this element can be exclusive, supported, unsupported, or deprecated.
When an assertion is evaluated or a formula is calculated that uses a function that has been marked as unsupported in the Functions Registry, and the processor is in OIM mode, the processor MUST raise either oimfe:oimIncompatibleRegistryFunction or an implementation-specific error.
When an assertion is evaluated or a formula is calculated that uses a function that has been marked as exclusive in the Functions Registry, and the processor is not in OIM mode, the processor MUST raise either oimfe:oimIncompatibleRegistryFunction or an implementation-specific error.
The above two errors are only triggered if a prohibited function is evaluated. The xfi:oim-mode() function is intended to allow rule authors to write alternative implementations for a rule, based on whether the processor is in OIM mode or not.
Appendix A provides some notes on migrating unsupported and deprecated functions to supported functions.
The following filters are not supported in OIM mode. A processor MUST raise oimfe:unsupportedFilter if an OIM-compatible XBRL formula contains one of filters listed below.
Typed dimension filter with a @test attribute are not supported. The ability to filter typed dimensions based on values is not currently supported other than by General Filters.
A processor MUST raise oimfe:unsupportedFilter if an OIM-compatible XBRL formula contains a typed dimension filter with a @test attribute.
This functionality could be provided by a general purpose dimension value filter that works for both explicit and typed dimensions, but the WG has decided to defer implementing this.
Equality definitions are not supported (oimfe:unsupportedFilter).
The non-dimensional aspect model is not supported in OIM Mode. A processor MUST raise oimfe:oimUnsupportedAspectModel if an OIM-compatible XBRL formula contains a variable set with the non-dimensional aspect model.
The Formula specifications are defined, in part, in terms of "implied XPath expressions". In some cases, these make use of functions which are not supported in OIM Mode. This section defines alternative implied XPath expressions that define the behaviour of a processor when in OIM Mode.
Unless otherwise stated, variables and substitutions in the alternative XPath expressions are as per the original expressions.
This modifies Period Filters Section 2.2.
If the period-start filter has a @time attribute, then the XPath expression implied by a period-start filter is:
if (f:period-is-duration(.) and f:has-dimension(., xs:QName('xbrl:period')))
then (f:period-start(.) eq fn:dateTime(#date, #time))
else fn:false()
If the period-start filter does not have a @time attribute, then the XPath
expression implied by a period-start filter is:
if (f:period-is-duration(.) and f:has-dimension(., xs:QName('xbrl:period')))
then (f:period-start(.) eq fn:dateTime(#date, xs:time('00:00:00')))
else fn:false()
This modifies Period Filters Section 2.3.
If the period-end filter has a @time attribute, then the XPath expression implied by a period-end filter is:
if (f:period-is-duration(.) and f:has-dimension(., xs:QName('xbrl:period')))
then (f:period-end(.) eq fn:dateTime(#date, #time))
else fn:false()
If the period-end filter does not have a @time attribute, then the XPath
expression implied by a period-end filter is:
if (f:period-is-duration(.) and f:has-dimension(., xs:QName('xbrl:period')))
then (f:period-end(.) eq (fn:dateTime(#date, xs:time('00:00:00')) + xs:dayTimeDuration('P1D')))
else fn:false()
This modifies Period Filters Section 2.5.
The XPath expression implied by a forever filter is:
not f:has-dimension(., xs:QName('xbrl:period'))
This modifies Period Filters Section 2.6.
If the @boundary attribute equals start then the XPath expression implied by an instant-duration filter is:
if (f:period-is-instant(.) and f:period-is-duration($#variable) and f:has-dimension($#variable, xs:QName('xbrl:period')))
then (f:period-instant(.) eq f:period-start($#variable))
else fn:false()
If the @boundary attribute equals end then the XPath expression implied by an instant-duration filter is:
if (f:period-is-instant(.) and f:period-is-duration($#variable) and f:has-dimension($#variable, xs:QName('xbrl:period')))
then (f:period-instant(.) eq f:period-end($#variable))
else fn:false()
This modifies Unit Filters Section 2.1.
The XPath expression implied by a single-measure unit filter is:
count(f:unit-numerators(.)) eq 1 and
count(f:unit-denominators(.)) eq 0 and
f:unit-numerators(.)[1] eq #measure
This modifies Variables Section 2.
The aspect test for the period aspect is:
fn:deep-equal(f:period($aspectTest:a), f:period($aspectTest:b))
This modifies Variables Section 2.
The aspect test for the unit aspect is:
fn:deep-equal(f:unit($aspectTest:a), f:unit($aspectTest:b))
This modifies Variables Section 2.
The aspect test for the unit aspect is:
fn:deep-equal(f:unit($aspectTest:a), f:unit($aspectTest:b))
This modifies Variables Section 2.1.2.1.
The default typed-dimension aspect test is:
fn:deep-equal(f:dimension-value($aspectTest:a, #dimension), f:dimension-value($aspectTest:b, #dimension))
This modifies Variables Section 3.4.
The XPath expression:
xfi:non-nil-facts-in-instance(/xbrli:xbrl)
is replaced by:
r:non-nil-facts()
The XPath expression:
xfi:facts-in-instance(/xbrl:xbrl)
is replaced by:
r:facts()
A number of functions in the registry make use of a standardised string presentation for unit core dimension values, referred to as expanded unit string representation.
Expanded unit string representation is obtained from a unit core dimension value as follows:
/ (U+0020, U+002F, U+0020) is appended to the result from step 1, followed by the values of the {denominators} property, in Clark notation, combined in lexicographic order, separated by a single space character.Expanded unit string representation is similar to the unit string representation defined in OIM Common, but avoids the use of QNames in order to avoid the reliance on prefixes.
For the purposes of this specification, the local name in a Clark notation value can include any non-whitespace characters, as per the definition of SQName.
An example value in Clark notation:
{http://www.example.com/namespace}local-name
Clark notation is an alternative to QNames. Unlike QNames, Clark notation does not make use of shorthand prefixes for namespaces, meaning that they can be understood and compared directly, without reference to an external prefix map.
The notation is was originally proposed by James Clark.
This appendix provides information on migrating XBRL Formula Rules from functions that are deprecated or unsupported in OIM mode. The list of functions covered by this appendix is not exhaustive. The normative status of all functions can be found in the functions registry.
xfi:context and xfi:context-*xfi:context returns the <context> element for a fact, and the xfi:context-* elements take that <context> element as input. As <context> is a syntactic, xBRL-XML construct, it is not supported by OIM Formula. Use of these functions should be replaced by functions that provide direct access to the information contained within an xBRL-XML <context> element. For example:
f:period, f:period-start, f:period-end and f:period-instant provide direct access to a fact's period.f:entity, f:entity-scheme, and f:entity-identifier provide direct access to a fact's entity.f:has-dimension and f:dimension-value provide direct access to all dimensions.xfi:period-* and xfi:*-periodThe xfi:context-period function returns a <xbrli:period> element, which can
be used as input to a number of other functions. As the <xbrli:period> is an
XML element, it is not supported in OIM mode and therefore these functions are
not supported. Their use can be replaced by the functions noted above that
provide direct access to period information from a fact.
Note that the value of <xbrli:forever>, which can be used on facts of duration
concepts in xBRL-XML, is used to represent the absence of the Period Core
Dimension in OIM. The f:period-type() and f:has-dimension() functions can
be used to determine the three possible types of period value in xBRL-XML
(period, instant, forever) as follows:
| Concept period type | xBRL-XML period | f:period-type(.) | f:has-dimension(., xs:QName('xbrl:period')) |
|---|---|---|---|
| Duration | Duration | duration |
true |
| Duration | <xbrli:forever> |
duration |
false |
| Instant | Instant | instant |
true |
xfi:unit, xfi:unit-numerator, xfi:unit-denominator and xfi:measure-namexfi:unit returns an <xbrli:unit> element, which can be used as input to xfi:unit-numerator and xfi:unit-denominator. The XML <xbrli:unit> element is not supported in OIM, but use of these functions can be replaced by f:unit, f:unit-numerators and f:unit-denominators which provide unit information directly from a fact.
xfi:measure-name is not supported, but it is not needed as f:unit-numerators and f:unit-denominators return QNames directly, rather than <xbrli:measure> elements.
xfi:fact-identifier-value and xfi:fact-identifier-schemexfi:fact-identifier-value and xfi:fact-identifier-scheme are deprecated. Use of these functions can be replaced by the equivalent f:entity-identifier and f:entity-scheme.
xff:uncovered-aspect, xff:uncovered-non-dimensional-aspects(), and xff:uncovered-dimensional-aspects()xff:uncovered-aspect, xff:uncovered-non-dimensional-aspects(), and
xff:uncovered-dimensional-aspects() are unsupported, and there is currently
no replacement, as there is no clear requirement for this functionality.
xfi:taxonomy-refsxfi:taxonomy-refs has been replaced by the equivalent r:taxonomy, for consistency with OIM terminology.
See specifications.xbrl.org for a list of public releases of this specification.
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 Open Information Model Working Group (SWG) up to and including 2023-07-26.
No errata have been incorporated into this document.
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).