This document is a public draft. Readers are invited to submit comments to the Implementation Guidance Task Force.


  • Revathy Ramanan, XBRL International Inc.
  • Paul Warren, XBRL International Inc.


  • Stuart Barker, CoreFiling Ltd
  • David Bell, UBPartner
  • Harald Schmitt, ABZ Reporting GmbH

1 Abstract

XBRL formula rules is a standardised mechanism for defining validation rules for XBRL reports. This tutorial introduces the features available in XBRL formula rules, and explains how common types of validation rule can be implemented.

This guidance is primarily targeted at taxonomy authors seeking to author validation rules.

2 Why use XBRL formula rules for validation rules?

Validation rules can increase the data quality and accuracy of XBRL reports. Validation rules are backed by requirements from the underlying business domain or driven by the technical requirements of the filing system.

XBRL formula rules is a standardised mechanism for embedding validation rules in an XBRL taxonomy. This allows a collector to publish a taxonomy that contains all of the validation constraints that reports are required to comply with, alongside other metadata such as labels and documentation. Conformant XBRL software will automatically apply the formula rules as part of validation, making it easy for preparers to check reports prior to submission. By publishing the rules in an executable format such as XBRL formula rules, collectors avoid the possibility of mis-interpretation of the rules by preparers and third-party software developers.

XBRL formula rules provides built-in features to work seamlessly with XBRL data, addressing XBRL-specific requirements such as selecting facts based on XBRL aspects, querying taxonomy relationships, and traversing XBRL dimensional models.

3 Scope

This tutorial explains how different types of business rules can be implemented as XBRL formula rules. The tutorial does not attempt to address all features of the XBRL Formula specification1 but covers those required to address the most common types of validation rules. This tutorial only covers the use of XBRL formula rules for validation2 and does not address their use for the production of new XBRL reports.

4 Creating XBRL formula rules

There are three components common to most XBRL formula rules:

The Rule Name
An identifier for the rule that is used to provide an error code if it fails.
The Test Expression
The logic that is evaluated in order to determine the outcome of the rule. This is the core of a rule. The test expression uses the XPath 2 expression language.
Inputs to the test expression. For example, if the test expression performs an aggregation, variables are used to select the total and contributing facts from the XBRL report.

XBRL formula rules may also have other optional components, including preconditions, severities and parameters. These are introduced in later examples.

The examples in this tutorial use the "XF" text-based formula language prototype. This provides exactly the same functionality as the XML-based syntax defined in the XBRL standard but is more concise and easier to read. Although this language is not yet the subject of a formal specification, it is the easiest way to demonstrate XBRL formula rules functionality.

4.1 Simple logical expression

To demonstrate basic XBRL formula rules functionality, consider a simple logical condition such as a requirement that reported Revenue is not negative.

The XF syntax for such a rule is shown below.

namespace eg = "http://example.com/taxonomy"; 
assertion NonNegativeRevenue {
    variable $v1 {
        concept-name eg:Revenue; 
    test { $v1 ge 0 };

The "assertion" keyword is used to define the rule, and provides the rule name, "NonNegativeRevenue".

When creating a formula rule, we first select the facts that we want to apply a test to. This is done using variables. In this case, a single variable "v1" is defined. The "concept-name" line (highlighted) defines a "Concept Filter" which selects facts reported using the "eg:Revenue" concept.

The test expression "$v1 ge 0" will check that the facts assigned to the variable "v1" have a value that is greater than or equal to zero.

The namespace declaration line (highlighted) binds the prefix "eg" to the namespace "http://example.com/taxonomy" for use in QNames in the rest of the XF file.

The rule will be evaluated for each time that the variable matches (or "binds to") the XBRL report. This means that the test expression will be evaluated for each occurrence of a fact using the concept "Revenue". This may include facts reported with different periods, units or taxonomy-defined dimensions. The characteristics (concept, period, unit, taxonomy-defined dimension and entity) used to uniquely identify a fact are known as "Aspects".

Figure 1 shows the results that would be expected from a hypothetical XBRL report containing six "revenue" facts with different aspects.

Figure 1: Evaluation results for facts with different aspects

If no "Revenue" fact is present in the XBRL report then this rule will not be evaluated. Section 4.8 demonstrates how to define a rule that raises an error if a required fact is not reported.

4.2 Rules involving multiple concepts

Business rules often require validation involving multiple facts from an XBRL report.

For example, validating the fundamental accounting rule: "Assets = Equities + Liabilities" involves comparing three facts.

namespace eg = "http://example.com/taxonomy";

assertion BalanceSheetEquality {
    variable $v1 {
        concept-name eg:Assets; 
    variable $v2 {
        concept-name eg:Equities; 
    variable $v3 {
        concept-name eg:Liabilities; 
    test {$v1 eq $v2 + $v3};

In this example, we define three variables (v1, v2, v3) using concept filters to select the facts that we are interested in. The test expression "$v1 eq $v2 + $v3" then performs the required validation on the selected facts.

In the simple case where the XBRL Report contains just a single fact for each concept, in the same period and with the same units and taxonomy-defined dimension value, the rule will be evaluated just once.

It is quite possible that the XBRL report will contain more than one fact for each concept. For example, a report may include facts for multiple reporting periods. In this case it is important that the facts being compared pertain to the same period. More generally, we want to ensure that facts sharing the same aspect values are grouped together for evaluation.

The full article is exclusively accessible to members of XBRL International.

If you or your organisation is a member but you do not have an XBRL username and password, please register for an account.

Not yet a Member?

Join XBRL today in order to get access to exclusive content, and other membership benefits:

  • Discounted conference attendance
  • Access to our Global Community
  • Use of the XBRL logo to promote your products and services
  • Early visibility and ability to influence new standards through Working Group participation
  • Inclusion in our Tools and Services directory

Learn more about joining the consortium.


Would you like
to learn more?

Join our Newsletter mailing list to
stay plugged in to the latest
information about XBRL around the world.

By clicking submit you agree to the XBRL International privacy policy which can be found at xbrl.org/privacy