Use of short circuit evaluation in XBRL Formula 1.0

Document 08 May 2018

Copyright © 2018 XBRL International Inc., All Rights Reserved.

This version:
Paul Warren, XBRL International <>
Herm Fischer, Mark V Systems <>
Harald Schmitt, ABZ Reporting <>
Chris Simmons, CoreFiling <>


Circulation of this Document is unrestricted. Other documents may supersede this document. Recipients are invited to submit comments to, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.


Short circuit evaluation of boolean expressions is a technique that XBRL Formula processors may use in order to improve performance, but its use is not required. Under certain circumstances, this can lead to evaluation errors in processors which do not perform short circuit evaluation, resulting in inconsistent behaviour. This working group note explains the issue and provides guidance on how to write XBRL Formula rules in a way that avoids potential problems.

Table of Contents

1 Short circuit evaluation
2 Application in XBRL Formula
3 Avoiding inconsistent behaviour
4 Interoperability
5 Recommendation


A XBRL Formula examples used in this document
B References
C Intellectual property status (non-normative)
D Acknowledgements (non-normative)
E Document history (non-normative)

1 Short circuit evaluation

Short circuit evaluation is a technique often used to improve performance when evaluating a boolean expression (expressions that give a true/false result, and which may involve operators such as and).

For example, a processor may evaluate the leftmost term to a boolean operator first, and only evaluate the second term if the first is insufficient to determine the result of the expression. For example, if the first argument to an and operation evaluates to false, the result of the expression will always be false, and evaluation of the second argument is unnecessary.

Although short circuit evaluation does not alter the result of the expression, it can be significant if evaluation of the second argument has side effects, such as setting a variable or raising an evaluation error.

In many languages, short circuit evaluation is not only acceptable, but required, and so may be relied upon by programmers as a way to avoid execution of the second argument to an operation. For example, the following code could be used to avoid a division-by-zero error:

x != 0 and y/x < 3

XBRL Formula [FORMULA] makes use of XPath 2 [XPATH 2.0] as its expression language. The expression above, can be written in XPath syntax as follows:

$x ne 0 and $y div $x lt 3

Unfortunately, the XPath 2 specification permits short circuit evaluation but does not require it (see Dynamic Evaluation [XQUERY 1.0 SEMANTICS]). This means that an input of $x = 0 will yield either the value false or an evaluation error, depending on the processor.

XPath 2 is a functional language, meaning that expressions cannot generally have side effects (e.g. setting a variable is not possible in XPath), but as shown in the above example, evaluation errors are possible.

2 Application in XBRL Formula

The example below shows an XBRL Formula assertion that checks the value of the period end of a fact (eg:concept1). A fallback of an empty sequence is provided for the variable, which means that the rule will be evaluated even if eg:concept1 is not reported. The rule will be evaluated for each occurrence of eg:concept2.

The example is shown using XF syntax (see Appendix A).

assertion evaluation_error { variable $v1 { fallback {()} concept-name eg:concept1; }; variable $v2 { concept-name eg:concept2; }; test { xs:date(xfi:period-end(xfi:period($v1))) eq xs:date('2018-01-01') }; };

This code will result in an evaluation error if the document contains eg:concept2 but not eg:concept1, because it will result in an empty sequence being passed to xfi:period.

In a processor that supports short circuit evaluation, the evaluation error could be avoided by checking if v1 is bound to the empty sequence before calling xfi:period:

test { not(empty($v1)) and xs:date(xfi:period-end(xfi:period($v1))) eq xs:date('2018-01-01') };

The above will return false if v1 is empty (i.e. eg:concept1 is not reported) or if it is reported with a value other than "2018-01-01" as the period end.

This approach is not recommended as it is relying on behaviour that is processor-dependent. A better solution is described in the next section.

3 Avoiding inconsistent behaviour

In order to avoid relying on short circuit evaluation, it is possible to rewrite expressions using an XPath if statement. The example above can be rewritten as:

test { if(empty($v1)) then false else xs:date(xfi:period-end(xfi:period($v1))) eq xs:date('2018-01-01') };

It is guaranteed that only one branch of the if statement will be evaluated, and so the evaluation error is completely avoided. This version is arguably easier to read too.

4 Interoperability

XBRL International strives to achieve consistent behaviour between processors in order to ensure interoperability, and provides conformance suites that can be used to test whether processors have implemented the specification correctly. Where interoperability issues are identified, additional test cases are created, and where appropriate, specification errata are published.

The topic of this note is problematic, as the interoperability issue is inherited from a third-party specification. The XBRL Formula Working Group considered publishing an erratum requiring XBRL Formula processors to apply short circuit evaluation consistently, but felt that this was an unreasonable change given that XBRL processors typically rely on third party libraries for processing XPath 2 expressions. As such, the group resolved to instead issue this guidance to the authors of XBRL Formula, advising against reliance on short circuit evaluation.

5 Recommendation

Authors of XBRL Formula rules should be aware that short-circuit evaluation is commonly supported by processors, but it is not required by the XPath specification and that it can lead to inconsistent results if the second part of a boolean expression has the potential to raise evaluation errors. As such, authors should not rely on short circuit evaluation in order to achieve conditional evaluation of an expression.

Where conditional evaluation is required, an if statement should be used.

Appendix A XBRL Formula examples used in this document

To improve readability, the examples of XBRL Formula rules in this document are presented using the XF text-based formula language prototype. Although this language is not yet the subject of a formal specification, it has a one-to-one mapping to XBRL Formula's XLink syntax, and the examples should be readily comprehensible to users who are familiar with XBRL Formula functionality.

Appendix B References

XBRL International Inc.. "XBRL Formulae 1.0"
Phillip Engel
, Herm Fischer, Victor Morilla, Jim Richards, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
W3C (World Wide Web Consortium). "XML Path Language (XPath) 2.0"
Anders Berglund
, Scott Boag, Don Chamberlin, Mary F. Fernández, Michael Kay, Jonathan Robie, and Jérôme Siméon.
W3C (World Wide Web Consortium). "XQuery 1.0 abd XPath 2.0 Formal Semantics"
Denis Draper
, Michael Dyck, Peter Frankhauser, Mary Fernández, Ashok Malhotra, Kristoffer Rose, Micheal Rys, Jérôme Siméon, and Philip Wadler.

Appendix C Intellectual property status (non-normative)

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 (


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 (

Appendix D Acknowledgements (non-normative)

This document could not have been written without the contributions of many people including the participants in the Formula Working Group.

Appendix E Document history (non-normative)

03 April 2018

Initial draft