1 Introduction

A XBRL formula specifies validations based on XBRL instance facts and generation of derived data as output XBRL instance facts.

This overview provides examples and explanation as an introduction to the syntax and semantics of XBRL formula. The accompanying specifications provide the feature descriptions in a rigorous manner for implementation and validation. Illustrations are based on open source and community edition tools.

2 Goals

The goals of XBRL formula are to provide validation capabilities not available in the Base Specification (XBRL 2.1) validation, dimensional validation, in a manner that is closely attuned to XBRL semantics, intuitive in XBRL terms, suitable for business users, extensible, and maintainable. XBRL formula is designed to accommodate the significant variation between filers, annually-released authority instances and filing rules. Finally it is designed to be formally documenting, both for its own maintenance, and to support audit functions.

A goal of XBRL formula is that output instance documents can represent many kinds of derived data, such as transformations, determination of ratios, and data mining.

Transformations can include transforming from one kind of taxonomy to another (for example from Global Ledger to a Financial Reporting taxonomy), from one version of a the same taxonomy to another (such as where namespaces change and some concepts are mapped), and in mapping between different accounting schedules of the same taxonomy (such as relating cash flow to balance sheet and transactions).

Determining of ratios and data mining can identify derived financial data, such as common ratios. In the case of XBRL filings for SEC and IFRS, individual filers may have financial reports that use different concepts or accounting rules than each other. In this case a goal of XBRL formula is to be able to provide declarative specifications that aid in identifying such concepts, which may be by knowing names of alternative names of concepts or possibly by knowing the relationship of concepts to each other (in XBRL's linkbases).

3 Other technologies

There are alternative technologies that each meet some goals of XBRL formula. These fall into three areas: procedural programming, declarative programming, and data warehouse/business intelligence.

Procedural programming includes languages common among XBRL processors today, particularly Java and .net languages (C#, and the Visual Basic family of languages). These have robust XML facilities, and in many cases can be coupled with XBRL processors. XBRL processors are generally required for applications that need validated data or deal with XBRL dimensions and semantics. Such processors are mostly implemented in Java, though they have used C# too. These processors have been used, very successfully, to build the XBRL production systems in use today. Meeting formula's goals in this manner requires a significant technical team, generally results in a large sized application, and implies a significant and difficult-to-staff long term maintenance project. In an environment where personnel turnover is likely (such as government contracting), maintenance is risky and often unsuccessful.

Declarative programming includes one language specific to XML, which is XSLT (and a rules-based generator of XSLT called Schematron). Use of XSLT in the 2.0 version (or a custom-modified Schematron implementation) would be required to have access to XBRL's function registry facilities, although there are production systems successful at an earlier time with XBRL 1.0 interfaced to a Java-implemented XBRL processor. XSLT is fully declarative, based on patterns and templates, and in addition has expressions and procedural function capabilities well matched to XBRL's needs. However without capability a function registry, if not available, building XBRL processing at the syntax level is a dauntingly difficult development task (several such projects were successful in XBRL's early days, but no longer are maintainable). XSLT is a difficult language to truely master, and there are very few people who can use the innate raw expressive power that it takes for XBRL processing in XSLT (in contrast to those who use XSLT to simply format reports of traditional XML data, which is relatively easy). Schematron, being a level more abstract than XSLT, is closer to XBRL formula, and this author has semi-automatically migrated Schematron rules specifications to XBRL formula value assertions, so that dimensionally-aware processing could be accommodated.

The goal for XBRL formula processing is a specific set of validations, mapping, or derived data to perform for one XBRL input instance (or a set of related input instances to a single process processing formula linkbase). When there are a large (and possibly vast) number of input instances to analyse together, it is likely that the processing capabilities of business warehousing and business intelligence (BW/BI), are a suitable technology. These are usually based on SQL databases, which themselves are a declarative form of programming. Whereas XBRL formula operates directly on native XBRL instances with the full semantics of XBRL, a SQL type of database that underlies BI/BW will need an Extraction, Transformation, and Loading (ETL) process to conform XBRL instance data into the schema structures it requires. ETL for XBRL instances can be complex, as each instance of a vast number (such as SEC filings) is likely to have quite different schematic and semantic structure than another. XBRL instances in BW after ETL will have normalized-away the semantic uniqueness that its DTS had in the original form. XBRL formula's goal is to meet the original form, leaving to BI the goal of performing operations across the reduced set of post-ETL information.

4 Formula Processing Overview

The simplified model of formula processing is that an input XBRL instance is provided to a formula processor. The instance specifies discovery of a DTS and includes within it the contexts, units, and facts provided. The formula processor may identify any and all formula linkbase components within that DTS, or it may be given an externally specified formula linkbase. The formula linkbase contains assertions and formulas along with the features to make them work (such as variables, filters and messages). As shown in Figure 1 the processor evaluates some or all assertions and formula processing, and produces assertion results (messages of assertions that are successful or not) and formula results (output XBRL instance facts). In production applications there may be significant interface coding with the formula processor, to control what it should examine, which assertions and formulas may apply to processing inputs, and how to dispose of the formula processing results.

There are four formula models, as shown in Figure 2. The first column has the value and existence assertions, which operate on the input XBRL instance data and provide evaluation feedback (as a boolean successful or not successful result, along with possible message detailing cause and ancillary data). The right column has formula which provides a resulting output fact when it is processed, and below is consistency assertion, which is used when it is desired to compare the formula's output fact with a matching one expected in the input XBRL instance.

Let's first look at simple examples of each of these four models, in Figure 3.

Value assertions check expressions, such as might involve arithmetic ratios and algorithms, string and text issues, and date checks. They are coded in XPath 2, and access data of an instance document by declarative filters. They represent the expression being checked, without need to provide plumbing or wiring to associate elements of data to the expression. That is done by the declarative filters which we'll learn of soon.

Existence assertions count the existence of data that the declarative filter expressions were able to locate (or not find) in an input XBRL instance. Existence assertions were meant to simplify expression of data that must be present, but there are situations where the data that is required is complex to specify, dependent on other data present, and requires a message detailing why something was missing due to other present data. In that case a value assertion, which can have an expression based on data evaluated by the filters, may be more suitable than existence, which only counts data evaluations.

Formula is the most sophisticated feature of XBRL formula linkbase. (As one might infer from its name, it was the original first feature of the formula linkbase, before assertions evolved.) Formula is a little like a value assertion, in that it can have an expression, but whereas a value expression is boolean (success or not), a formula expression produces an output XBRL instance fact. The output fact has all of the aspects that are needed to produce output instance XML syntax, including its concept, value (from the fact's expression), precision if numeric, and context/unit aspects. The context and unit aspects can be copied from data that the filters evaluated or constructed by rules. Two situations are common:

1. The output fact is one 'matching' an input fact, or very close to it. Assets = liabilities + equity is such a situation. The formula need only specify the value expression (liabilities + equity), with the filters providing the right data, and ask to copy context and unit information from one of the terms (such as liabilities). The output fact's concept name, assets, would be specified as a rule that overrides that otherwise copied from liabilities. That way the result has the dates, unit, and dimensions of the input term, a different concept name, with barely any programming effort.
2. The output fact is one quite different from input facts, perhaps if a ratio is derived, it may have different units (monetary units per share, something per time), a different period (an ending balance instant period derived from changes that are durations), or quite different dimensions than the source data from which it was derived. That is accommodated by declaratively coded formula rules, instead of programming procedural coding.

A forth processing model is the consistency assertion, which compares a derived formula output fact with the expectation that there is a matching input that should be close enough (within a tolerance margin). Consistency assertion requires a formula, such as producing assets in the figure box above, and a specification of how close in value it should be to the input fact matching it (by percentage or absolute value).

5 What's in a formula linkbase

To accomplish formula processing the formula linkbase has a set of components, shown in the expsnded view of Figure 4. We'll first identify what the key features are and then begin by example to review them.

Assertions are boolean expressions that are either successful or not, for value (boolean expression evaluation against a matched and possibly filtered set of input fact data), for existence (specified input data exist according to filter expressions), or consistency (a derived output fact is matched to an input fact within a tolerance margin). Formula are values and rule to specify an output fact and its aspects.

Arcs form the relationships that relate the components of a formula linkbase. These relationships are the core of what facilitates extensibility and modularity. Linkbase components that can be shared can have relationships to the sharing features (such as variables and filters shared between different assertions and formulas). These relationships are extensible with the provisions for relationship prohibition. They encourage modularity becase components can be grouped into files for purposes of maintainability and source code management.

Variables declare a way of binding input data, usually fact items, to a name that can be referenced by variable name such as from within an assertion or formula expression. Variables that bind to input fact items are fact variables and use filters to declare what they can bind to in the input. General variables are used for intermediate expression results and other kinds of processing, such as function registry use, lookup table use, and more complex types of DTS linkbase tree traversal.

A variable set is a value assertion, existence assertion, or formula, with its associated variables. The variable set is an evaluatable processing declaration, that when applied by filters to a set of facts in the input XBRL instance, results in assertion attempts and processing of formula values and rules to produce output facts.

Filters specify aspects that constrain which facts can bind to a variable, such as by a name, dimension, or period.

Messages provide text and structured parameters to interface assertion and formula results, with parameters related from evaluation variables, to a reporting or logging system.

Preconditions provide a way of determining if a set of bound variables can activate a formula value and output fact or an assertion value test or existence count.

Parameters are shown overlapping the left border because they can interact with external the external environment in which formula operates. A parameter may have an expression, which is evaluated internally, to produce a global constant for the execution the assertions, formulae, and messages by the processor. It may also have an externally set value. Examples of externally set values would be, for U.S. SEC filings, the expected form type, company identifier, and company name, to be validated against the contents of facts and context information in the input XBRL instance.

Custom functions are shown overlapping the left border because they can be supplied in a programming language implementation that interacts with the external environment. Examples would be custom functions that interact with SQL databases or BI/BW systems. Custom functions can also be implemented within the linkbase (hence the symbols are repeated enclosed in the linkbase). The in-linkbase functions are portable coded in XPath 2 steps, using function arguments, formula parameters, and function registry features, to provide better structure and common expression organization to XBRL formula linkbases.

6 Value assertions

Value assertions often are the most used formula linkbase feature, providing a way to check input XBRL instance facts against an expression. The model in processing value assertions is Figure 5. A formula processor obtains values for any parameters (usually before anything else is done, as they are static during processing). Then it would normally process all the value assertions accessible to the DTS, unless the selection of assertions to process is under the control of an external application. For each value assertion, the variables representing the terms to be evaluated are bound to input XBRL instance facts, according to filtering in effect, and the assertion tested for each applicable set of variables. In this model of processing there are many opportunities for optimisation, such as identifying filter expressions which are common, static, or repeated, and can be removed from repetitive execution, and variable binding in nested iteration conditions, where the nested iterations would duplicate processing from a previous cycle. The illustration, and processing traces below, are simplified to show a serial linear execution (such as is needed for debugging).

6.1 Example testing net incomes to gross incomes

The first example tests that net incomes are less than or equal to gross incomes. Both net and gross incomes are reported for two years, facts are shown in Figure 6. For 2007, GrossIncomes is $500 and NetIncomes is $200, so the NetIncomes ≤ GrossIncomes is $200 ≤ $500 which is true, the assertion should be successful. For 2006, $1,400 is not ≤ $900, the assertion should not be successful.

Figure 6: Example net income and gross income facts.

A tool-view of the corresponding assertion is shown in Figure 7. The top line is the assertion, expressed with a term for NetIncomes, obtained as a fact from the input XBRL instance, represented in XPath 2 with a dollar symbol before the variable name, $netIncome. A second term is the corresponding fact item for GrossIncomes, represented by the variable name, $grossIncomes. The XPath 2 "value comparison" operator for ≤ is the word "le". Each of these terms is, in XBRL formula, a fact variable. Each of these two fact variables declares the concept that they wish to be bound to by a concept name filter, given the QName of the concept, such as concept:NetIncomes. The model for how the assertion declares this is shown in Figure 8

Figure 7: Assertion to test that net incomes are less than gross incomes.

A model-view showing how the assertion declares the value assertion expression, its fact variables, and their filters, is shown is shown in Figure 8.

Figure 8: Assertion model showing variables and filters.

The value assertion's test expression is $netIncomes le $grossIncomes. Each of $netIncomes and $grossIncomes are specified by fact variables. The fact variables filter (restrict) which variables they may be bound to by concept name filters, each of which specifies a QName that must match the corresponding fact's element name.

In the processing model of Figure 5, the formula processor first identifies assertions to be processed, which is the subject assertion. Next it must bind fact variables to input XBRL instance facts in some order. Relationships are used to identify the fact variables for the assertion. Each such relationship also specifies the variable name to associate with the bound fact. We show the netIncomes being first (but there is no dependency between the two, they could be in any order, even parcelled out to two different CPU cores to run in parallel.

NetIncomes is just a fact variable, if it had no filters, it would iterate through all of the input facts, one by one. However it only makes sense to bind NetIncomes to the two facts for concept:NetIncomes. This is specified by the concept name filter, which has a variable-filter relationship to the fact variable. The use of relationships to connect assertions to fact variables to filters provides the flexibility to share common variables (and filters) between different assertions (with name given by the relationship, so that a multiply-used variable can have names specified on each such relationship.

Once the first fact variable, NetIncomes, is bound to a fact then the second fact variable likewise is bound to a fact, but implicit filtering narrows down the scope of which of the GrossIncomes facts can correspond to each NetIncomes fact. The result of implicit filtering is that the 2007 facts represent one evaluation (assignment of value to each variable and trying out the assertion value expression), and the 2006 facts represent the other evaluation.

With facts bound to both NetIncomes and GrossIncomes, the assertion can be evaluated. After the evaluation the processing model of Figure 5 first attempts to be sure that there aren't more GrossIncomes that can be evaluated. There is one more GrossIncomes fact, but it doesn't match NetIncomes in the period aspect (by implicit filtering), so it's skipped.

Once the other GrossIncomes facts had been considered (but not evaluated because of implicit filtering periods mismatch), then the NetIncomes fact variable can assume the second value, and the GrossIncomes tried again.

Example 1 is a detailed trace of the execution of a formula processor with the above instance and assertion (using the Arelle open source processor).

Example 1: Assertion execution detailed trace

Trace log	Meaning
Fact Variable netIncomes filtering: start with 4 facts	Processing of the assertion begins by finding a first fact to bind to $netIncomes. All four facts in the instance are, at first, candidates to be bound (one by one) to $netIncomes.
Fact Variable netIncomes conceptName filter NetIncomesFilter passes 2 facts	The concept name filter that is associated to this fact variable only passes the two facts which have QName matching concept:NetIncomes
Fact Variable netIncomes: filters result [fact(concept:NetIncomes, period-2007, unit, '200'), fact(concept:NetIncomes, period-2006, unit, '1,400')]	Now these two filter result facts are bound, one by one, to $netIncomes.
Fact Variable netIncomes: bound value fact(concept:NetIncomes, period-2007, unit, '200')	First of two netIncomes fact items is bound to $netIncomes.
Fact Variable grossIncomes filtering: start with 4 facts	GrossIncome starts with all 4 facts in the instance
Fact Variable grossIncomes conceptName filter GrossIncomesFilter passes 2 facts	The concept name filter that is associated to this fact variable only passes the two facts which have QName matching concept:GrossIncomes
Fact Variable netIncomes implicit filter period passes 1 facts	Implicit filtering considers all uncovered aspects of the gross income fact, trying to match it to the net income fact. In this example we focus on the period aspect (skipping the traces of aspects that aren't material to this example)
Fact Variable grossIncomes: filters result [fact(concept:GrossIncomes, period-2007, unit, '500')]	Only one of the gross income facts matched the period of the net income fact, and survives this filter>
Fact Variable grossIncomes: bound value fact(concept:GrossIncomes, period-2007, unit, '500')
Value Assertion assertion	Now both net income and gross income have bound values, and the assertion expression can be evaluated
Result: True
	Given the evaluation of the assertion, if there were more than one fact assignable to $grossIncomes it would now be assigned and evaluated, but only one grossIncome fact had been found to pass the filters and implicitly match (by period) to net incomes, so next processing tries for another value of the next outer (first) fact fact variable.
Fact Variable netIncomes: bound value fact(concept:NetIncomes, period-2006, unit, '1,400')	Second of two netIncomes fact items is bound to $netIncomes.
Fact Variable grossIncomes filtering: start with 4 facts
Fact Variable grossIncomes conceptName filter GrossIncomesFilter passes 2 facts
Fact Variable netIncomes implicit filter period passes 1 facts	Second gross income is period matched to second net income fact
Fact Variable grossIncomes: filters result [fact(concept:GrossIncomes, period-2006, unit, '900')]
Fact Variable grossIncomes: bound value fact(concept:GrossIncomes, period-2006, unit, '900')
Value Assertion assertion
Result: False	Second assertion result is false as expected from the data
Value Assertion assertion evaluations : 1 satisfied, 1 not satisfied

Example 2 shows the syntax of the linkbase.

Example 2: Assertion example linkbase syntax

Linkbase syntax	Meaning
<generic:link xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link">	An extended link is the container for formula linkbase resources and arcs. The xlink:role is not significant for formula linkbases, and is not used to separate or control assertion execution (see assertion sets for partitioning of assertions into managed sets)
<va:valueAssertion xlink:type="resource" xlink:label="assertion" id="assertion" aspectModel="dimensional" implicitFiltering="true" test="$netIncomes le $grossIncomes"/>	This is the value assertion. Its xlink:label is the source of arcs to the fact variables of the value assertion. The aspect model, dimensional, specifies that dimensions may be used as aspects on facts (and that implicit filtering will match up uncovered dimension aspects, if there were any in this example).
<variable:factVariable xlink:type="resource" xlink:label="GrossIncomes" bindAsSequence="false"/>	Specifies the fact variable for gross incomes, but does not assign the 'variable name' (that is done on the arc from the assertion to the fact variable). The filtered facts that are assigned to this fact variable are processed one-by-one because bindAsSequence is false.
<variable:factVariable xlink:type="resource" xlink:label="NetIncomes" bindAsSequence="false"/>	Ditto, the fact variable for net incomes.
<variable:variableArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-set" xlink:from="assertion" xlink:to="GrossIncomes" order="1.0" name="grossIncomes"/>	This arc, from the assertion to the fact variable, gives the fact variable its name when used on this assertion ($grossIncomes). (If the fact variable were to have been shared with other assertions, it could have been given different names on the arc from those other assertions.)
<variable:variableArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-set" xlink:from="assertion" xlink:to="NetIncomes" order="2.0" name="netIncomes"/>	Ditto, arc from assertion to net incomes fact variable, assigning it the name ($netIncomes).
<cf:conceptName xlink:type="resource" xlink:label="GrossIncomesFilter"> <cf:concept> <cf:qname> concept:GrossIncomes </cf:qname> </cf:concept> </cf:conceptName>	The filter used by the fact variable for gross incomes, to pass facts which have the concept name, concept:GrossIncomes, and to reject any other named facts.
<cf:conceptName xlink:type="resource" xlink:label="NetIncomesFilter"> <cf:concept> <cf:qname> concept:NetIncomes </cf:qname> </cf:concept> </cf:conceptName>	Ditto, for net incomes.
<variable:variableFilterArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-filter" xlink:from="GrossIncomes" xlink:to="GrossIncomesFilter" complement="false" cover="true" order="1.0"/>	The arc from fact variable gross incomes to its filter (restricting to concepts named Gross incomes).
<variable:variableFilterArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-filter" xlink:from="NetIncomes" xlink:to="NetIncomesFilter" complement="false" cover="true" order="1.0"/>	Ditto for net incomes.
</generic:link>	End of extended link formula resources and arcs construct.

6.2 Example testing movement balances

This example tests a movement pattern, where there is a starting balance, changes, and ending balance, for each of several periods, and it is desired to validate that the ending balance is within a tolerance margin of the starting balance plus changes. The XBRL calculation linkbase doesn't apply to this situation because the balances are instant periods and the changes are duration periods, so a value assertion is required.

Example facts are shown in Figure 9. For 2008, $600 + $400 = $1000, the assertion is successful. For 2009, $1,000 + $800 ≠ $1,790 (within tolerance of $1), so this assertion is unsuccessful. For 2010, $1,790 + $900 = $2,690 so this assertion is successful.

Figure 9: Example movement balance and changes facts.

The corresponding assertion is shown in Figure 10. The top line is the assertion, $beginningBalance + $changes = $endingBalance within tolerance margin (1.00). This is coded as | $beginningBalance + $changes - $endingBalance | ≤ 1.00, or in XPath 2, abs( $beginningBalance + $changes - $endingBalance ) le 1.00. This example introduces explicit filtering for the period aspect of the balances (compared to the prior example, where period filtering was done implicitly). Explicit filtering is required to establish that the starting balance instant period matches the start of the changes duration period, and the ending balance likewise matches the end of the changes period.

Figure 10: Assertion to test starting balance, changes, and ending balance.

A model-view showing how the assertion declares the value assertion expression, its fact variables, and their filters, is shown is shown in Figure 11.

Figure 11: Assertion model showing variables and filters.

This example has a dependency between the changes and balance fact variables, the changes fact must be bound first, so that the balances for start and end can respectively bind to the start and end dates of the period of the changes variable. Also the diagram shows how filters may be shared, as the same concept name filter is used for both balance fact variables.

Example 3 is a detailed trace of the execution of a formula processor with the above instance and assertion (using the Arelle open source processor).

Example 3: Assertion execution detailed trace

Trace log	Meaning
Fact Variable changes filtering: start with 7 facts	$changes starts with all facts in instance
Fact Variable changes conceptName filter filter_changes passes 3 facts	concept name filtering by QName c:changes
Fact Variable changes: filters result [fact(concept:changes, D2008, unit, '400'), fact(concept:changes, D2009, unit, '800'), fact(concept:changes, D2010, unit, '900')]	3 resulting changes facts (to be bound to $changes one-by-one)
Fact Variable changes: bound value fact(concept:changes, D2008, unit, '400')	First evaluation with 2008's changes fact
Fact Variable beginningBalance filtering: start with 7 facts	$beginningBalance starts with all facts
Fact Variable beginningBalance conceptName filter filter_balance passes 4 facts	concept name filtering by c:balance
Fact Variable beginningBalance instantDuration filter filter_periodStart passes 1 facts	period start filter to match $changes start filters down to one fact
Fact Variable beginningBalance: filters result [fact(concept:balance, I2007, unit, '600')]
Fact Variable beginningBalance: bound value fact(concept:balance, I2007, unit, '600')
Fact Variable endingBalance filtering: start with 7 facts	(same as beginning balance)
Fact Variable endingBalance conceptName filter filter_balance passes 4 facts
Fact Variable endingBalance instantDuration filter filter_periodEnd passes 1 facts	(but matches $changes end date)
Fact Variable endingBalance: filters result [fact(concept:balance, I2008, unit, '1,000')]
Fact Variable endingBalance: bound value fact(concept:balance, I2008, unit, '1,000')
Value Assertion assertion Result: True	Assertion is successful for 2008 changes.
Fact Variable changes: bound value fact(concept:changes, D2009, unit, '800')	Processing continues with $changes binding to the second of its facts, for 2009 (the order of taking changes facts is arbitrary and not important, this processor is using document order which happens to be in year order).
Fact Variable beginningBalance filtering: start with 7 facts
Fact Variable beginningBalance conceptName filter filter_balance passes 4 facts
Fact Variable beginningBalance instantDuration filter filter_periodStart passes 1 facts
Fact Variable beginningBalance: filters result [fact(concept:balance, I2008, unit, '1,000')]
Fact Variable beginningBalance: bound value fact(concept:balance, I2008, unit, '1,000')
Fact Variable endingBalance filtering: start with 7 facts
Fact Variable endingBalance conceptName filter filter_balance passes 4 facts
Fact Variable endingBalance instantDuration filter filter_periodEnd passes 1 facts
Fact Variable endingBalance: filters result [fact(concept:balance, I2009, unit, '1,790')]
Fact Variable endingBalance: bound value fact(concept:balance, I2009, unit, '1,790')
Value Assertion assertion Result: False
Fact Variable changes: bound value fact(concept:changes, D2010, unit, '900')
Fact Variable beginningBalance filtering: start with 7 facts
Fact Variable beginningBalance conceptName filter filter_balance passes 4 facts
Fact Variable beginningBalance instantDuration filter filter_periodStart passes 1 facts
Fact Variable beginningBalance: filters result [fact(concept:balance, I2009, unit, '1,790')]
Fact Variable beginningBalance: bound value fact(concept:balance, I2009, unit, '1,790')
Fact Variable endingBalance filtering: start with 7 facts
Fact Variable endingBalance conceptName filter filter_balance passes 4 facts
Fact Variable endingBalance instantDuration filter filter_periodEnd passes 1 facts
Fact Variable endingBalance: filters result [fact(concept:balance, I2010, unit, '2,690')]
Fact Variable endingBalance: bound value fact(concept:balance, I2010, unit, '2,690')
Value Assertion assertion Result: True
Value Assertion assertion evaluations : 2 satisfied, 1 not satisfied

Example 4 shows the syntax of the linkbase.

Example 4: Assertion example linkbase syntax

Linkbase syntax	Meaning
<va:valueAssertion ... test="abs( $beginningBalance + $changes - $endingBalance ) le 1.00"	Value assertion with the balances changes testing XPath expression>
<variable:factVariable xlink:type="resource" xlink:label="variable_beginningBalance" bindAsSequence="false"/>	Beginning balance fact variable
<variable:factVariable xlink:type="resource" xlink:label="variable_endingBalance" bindAsSequence="false"/>	Ending balance fact variable
<variable:factVariable xlink:type="resource" xlink:label="variable_changes" bindAsSequence="false"/>	Changes fact variable
<variable:variableArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-set" xlink:from="assertion" xlink:to="variable_changes" order="1.0" name="changes"/>	Relationships from assertion to the fact variables
<variable:variableArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-set" xlink:from="assertion" xlink:to="variable_beginningBalance" order="2.0" name="beginningBalance"/>
<variable:variableArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-set" xlink:from="assertion" xlink:to="variable_endingBalance" order="2.0" name="endingBalance"/>
<cf:conceptName xlink:type="resource" xlink:label="filter_balance"> <cf:concept> <cf:qname> c:balance </cf:qname> </cf:concept> </cf:conceptName>	Shared concept name filter for both balances fact variables
<cf:conceptName xlink:type="resource" xlink:label="filter_changes"> <cf:concept> <cf:qname> c:changes </cf:qname> </cf:concept> </cf:conceptName>	Concept name filter for changes fact variable
<variable:variableFilterArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-filter" complement="false" cover="true" xlink:from="variable_changes" xlink:to="filter_changes" order="1.0"/>	Changes fact variable concept name filter relationship
<variable:variableFilterArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-filter" complement="false" cover="true" xlink:from="variable_beginningBalance" xlink:to="filter_balance" order="1.0"/>	Beginning balance fact variable shared concept name filter relationship
<variable:variableFilterArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-filter" complement="false" cover="true" xlink:from="variable_endingBalance" xlink:to="filter_balance" order="1.0"/>	Ending balance fact variable shared concept name filter relationship
<pf:instantDuration xlink:type="resource" xlink:label="filter_periodStart" variable="changes" boundary="start"/>	Period start filter aligning beginning balance to start of $changes duration period
<pf:instantDuration xlink:type="resource" xlink:label="filter_periodEnd" variable="changes" boundary="end"/>	(same for ending balance)
<variable:variableFilterArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-filter" complement="false" cover="true" xlink:from="variable_beginningBalance" xlink:to="filter_periodStart" order="6.0"/>	Beginning balance fact variable period filter relationship
<variable:variableFilterArc xlink:type="arc" xlink:arcrole="http://xbrl.org/arcrole/2008/variable-filter" complement="false" cover="true" xlink:from="variable_endingBalance" xlink:to="filter_periodEnd" order="6.0"/>

6.3 Dimensional examples

This example tests a dimensional example, adapted from Victor Morilla's U-Tube XBRL Formula presentation to XBRL 22 in Brussels. Example facts are shown in Figure 12. For a single year, balance sheet facts are shown for a default total dimension, as well as breakdowns by Europe and USA, and within Europe an incomplete breakdown of just France, Germany, and Spain. We will use this dimensional example to show implicit filtering by dimensional aspects, validation formulas with dimensions, and dimensional aggregation. A fact list view, showing concepts (which are dimensional) is in Figure 13, and shows the style of concept usage for dimensional values. The total dimension is default (not appearing in contexts).

Figure 12: Example dimensional facts table by dimension.

Figure 13: Example dimensional fact list by contextRef.

6.3.1 Testing assets equals liabilities and equity per dimension

This first assertion tests that assets = liabilitiesAndEquities in each dimension. The model of the assertion is in Figure 14. There are two fact variables, the first binding to assets one by one. Each assets fact has a default or explicit member value for the CountriesAxis dimension. The second fact variable is implicitly matched to all uncovered aspects of $assets, in particular the Country dimension. As seen in Figure 12, for the France entry, the liabilities and equity is 0€, compared to assets of 10,000€, so the France assertion fails. Spain has no entry for liabilitiesAndEquity, causing the evaluation to not bind (see trace below), and thus no assertion is attempted for Spain.

Figure 14: Assertion to test Assets to LiabilitiesAndEquity in each dimension.

Example 3 is an excerpt of the trace of the execution of a formula processor with the above instance and assertion.

Example 5: Assertion execution trace excerpt

Trace log	Meaning
Fact Variable assets filtering: start with 41 facts	Assets starts with all facts in instance
Fact Variable assets conceptName filter filter_assets passes 6 facts
Fact Variable assets: filters result [fact(ex:Assets, I-2007, EUR, '100,000'), fact(ex:Assets, I-2007-EU, EUR, '50,000'), fact(ex:Assets, I-2007-FR, EUR, '10,000'), fact(ex:Assets, I-2007-DE, EUR, '5,000'), fact(ex:Assets, I-2007-ES, EUR, '35,000'), fact(ex:Assets, I-2007-US, EUR, '50,000')]	Now bound only to Assets facts
Fact Variable assets: bound value fact(ex:Assets, I-2007, EUR, '100,000')	Bound one by one to each Assets fact
Fact Variable liabilitiesAndEquity filtering: start with 41 facts
Fact Variable liabilitiesAndEquity conceptName filter filter_liabilitiesAndEquity passes 5 facts
Fact Variable assets implicit filter ex:CountriesAxis passes 1 facts	Implicit match of CountriesAxis dimension matches LiabilitiesAndEquity to dimension of Assets
Fact Variable liabilitiesAndEquity: filters result [fact(ex:LiabilitiesAndEquity, I-2007, EUR, '100,000')]
Fact Variable liabilitiesAndEquity: bound value fact(ex:LiabilitiesAndEquity, I-2007, EUR, '100,000')
Value Assertion assertion Result: True
Fact Variable assets: bound value fact(ex:Assets, I-2007-EU, EUR, '50,000')	The next country axis dimension member (skipping detailed trace steps)
Value Assertion assertion Result: True
Fact Variable assets: bound value fact(ex:Assets, I-2007-FR, EUR, '10,000')	France Assets
Fact Variable liabilitiesAndEquity filtering: start with 41 facts
Fact Variable liabilitiesAndEquity conceptName filter filter_liabilitiesAndEquity passes 5 facts
Fact Variable assets implicit filter ex:CountriesAxis passes 1 facts
Fact Variable liabilitiesAndEquity: filters result [fact(ex:LiabilitiesAndEquity, I-2007-FR, EUR, '0')]
Fact Variable liabilitiesAndEquity: bound value fact(ex:LiabilitiesAndEquity, I-2007-FR, EUR, '0')	France LiabilitiesAndEquity is zero, doesn't match Assets
Value Assertion assertion Result: False	Fails because liabilities value is 0, compared with 10,000 for Assets
Fact Variable assets: bound value fact(ex:Assets, I-2007-DE, EUR, '5,000')
Fact Variable liabilitiesAndEquity filtering: start with 41 facts	Germany, details omitted
Value Assertion assertion Result: True
Fact Variable assets: bound value fact(ex:Assets, I-2007-ES, EUR, '35,000')	Spain has Assets but no LiabilitiesAndEquity fact
Fact Variable liabilitiesAndEquity filtering: start with 41 facts
Fact Variable liabilitiesAndEquity conceptName filter filter_liabilitiesAndEquity passes 5 facts
Fact Variable assets implicit filter ex:CountriesAxis passes 0 facts	No country axis Spain member found to match Assets for Spain
Fact Variable liabilitiesAndEquity: filters result []	Empty sequence results for Spain, note that there is no evaluation of the assertion because the second fact variable failed to bind.
Fact Variable assets: bound value fact(ex:Assets, I-2007-US, EUR, '50,000')	Now trying USA dimension member
Fact Variable liabilitiesAndEquity filtering: start with 41 facts
Fact Variable assets implicit filter ex:CountriesAxis passes 1 facts
Fact Variable liabilitiesAndEquity: filters result [fact(ex:LiabilitiesAndEquity, I-2007-US, EUR, '50,000')]
Fact Variable liabilitiesAndEquity: bound value fact(ex:LiabilitiesAndEquity, I-2007-US, EUR, '50,000')
Value Assertion assertion Result: True	Successful for USA dimension member
Value Assertion assertion evaluations : 4 satisfied, 1 not satisfied

6.3.2 Testing assets equals current assets plus fixed assets with fallback

This assertion introduces fallback values for missing facts while testing that assets = currentAssets + fixedAssets for each dimension. Review of the facts table for Spain in Figure 12 shows that the entry for fixedAssets is missing. Without a fallback for the fact variable, no evaluation would occur (as above for Spain). However here we desire an unsuccessful evaluation, which can be caused by providing a declaration that in the absence of a value for the fact variable, it is to fallback to zero.
Example 6 The model of the assertion is in Figure 15.

Example 6: Fallback value fact variables example linkbase syntax

Linkbase syntax	Meaning
<variable:factVariable xlink:type="resource" xlink:label="variable_assets" bindAsSequence="false" fallbackValue="0"/>	Fact variables each specify fallbackValue="0"
<variable:factVariable xlink:type="resource" xlink:label="variable_currentAssets" bindAsSequence="false" fallbackValue="0"/>
<variable:factVariable xlink:type="resource" xlink:label="variable_fixedAssets" bindAsSequence="false" fallbackValue="0"/>

Figure 15: Assertion to test Assets to LiabilitiesAndEquity in each dimension.

Example 7 is an excerpt of the trace of the execution of a formula processor with the above instance and assertion.

Example 7: Assertion execution trace excerpt with fallback value

Trace log	Meaning
Value Assertion assertion Result: True	Total (default country dimension member)
Value Assertion assertion Result: True	Europe
Value Assertion assertion Result: True	France
Value Assertion assertion Result: True	Germany
Value Assertion assertion Result: True	USA
Fact Variable fixedAssets: bound value [[0]]	Trying fixed assets with fall back value to see if any matches are possible without duplicating existing-fact evaluations (many trace lines skipped)
Fact Variable assets: bound value fact(ex:Assets, I-2007-ES, EUR, '35,000')	Found a fact variable bindings that with fallen back fixedAssets doesn't duplicate any prior existing-fact evaluation
Fact Variable currentAssets: bound value fact(ex:CurrentAssets, I-2007-ES, EUR, '4,000')	Ditto for current assets
Value Assertion assertion Result: False	Spain (with fallback for fixed assets) assertion is not successful
Value Assertion assertion evaluations : 5 satisfied, 1 not satisfied

6.3.3 Testing France dimension members inventory test (single dimension member)

This assertion introduces dimensional filtering to test that inventory > 15% of current assets, but to restrict this test for France only. The model of the assertion is in Figure 16. A shared explicit dimension filter is used, as in the syntax of

Example 8: Dimension filter example linkbase syntax

Linkbase syntax	Meaning
<df:explicitDimension xlink:type="resource" xlink:label="filter_countries"> <df:dimension> <df:qname> ex:CountriesAxis </df:qname> </df:dimension> <df:member> <df:qname> ex:France </df:qname> </df:member> </df:explicitDimension>	Dimension filter for single member, France

Figure 16: Assertion to test Assets to LiabilitiesAndEquity in each dimension.

A single evaluation results (as would be expected):

Value Assertion assertion evaluations : 1 satisfied, 0 not satisfied

6.3.4 Testing France dimension members inventory test (two dimension members on variable filter)

This assertion introduces dimensional filtering to test that inventory > 15% of current assets, but for France and Spain, by adding Spain to the prior example filter. The model of the assertion is in Figure 17. A shared explicit dimension filter is used, as in the syntax of

Example 9: Dimension filter example linkbase syntax

Linkbase syntax	Meaning
<df:explicitDimension xlink:type="resource" xlink:label="filter_countries"> <df:dimension> <df:qname> ex:CountriesAxis </df:qname> </df:dimension> <df:member> <df:qname> ex:France </df:qname> </df:member> <df:member> <df:qname> ex:Spain </df:qname> </df:member> </df:explicitDimension>	Dimension filter for two members, France and Spain

Figure 17: Assertion to test Assets to LiabilitiesAndEquity in each dimension on a variable filter.

Four evaluation results because the logic (as shown in the diagram) is to each of the two variables for each possible country, including the cross products, because the filter's dimension aspect is covered, preventing implicit filtering on dimension:

Value Assertion assertion evaluations : 3 satisfied, 1 not satisfied

6.3.5 Testing France dimension members inventory test (two dimension members on group filter)

This assertion moves the dimension filter to the assertion, where it is called a group filter, instead of a fact variable filter. The model of the assertion is in Figure 18. With use of the group filter, its aspect (CountriesAxis dimension) is not covered, therefore the formula processor can implicitly filter the fact variables to match the CountriesAxis dimension aspect of each other.

Figure 18: Assertion to test Assets to LiabilitiesAndEquity in each dimension by a group filter.

Two evaluation results because the dimension filter has been moved to the assertion (so it is a group filter), which now leaves the CountriesAxis dimension uncovered, so the fact variables are implicitly matched by the countries dimension:

Value Assertion assertion evaluations : 1 satisfied, 1 not satisfied

7 Aspect models

An aspect is information about a XBRL instance fact that is in addition to its value, such as it concept, period, or dimensions. The aspects of a fact form the basis for matching and filtering facts. The aspects that apply to a fact and description of how that information is split into different aspects form an aspect model. XBRL formula defines two aspect models, dimensional and non-dimensional in a manner that allows for future extension models. Table 1 shows which aspects are present in the dimensional and non-dimensional aspect models for tuples, numeric items, and non-numeric items.

Aspects form the basis for matching and filtering facts. Filtering can be explicit or implicit. Explicit filtering can occur for the group of fact variables that apply to an assertion or other variable set, or for specific fact variables. For example, a group filter may restrict data to a specific period or dimension value, whereas a fact variable filter may bind a fact variable to a certain concept element name, or relate it to a period (such as filtering a balance for the start or ending of a changes duration period). Implicit filtering can match the aspects not otherwise covered (e.g. excluding concept name, but matching dates, dimensions, entity and units as applicable).

Each aspect has a specific matching test implied by the aspect. Concept aspects match by QName of the element, periods by their dates, entity identifiers by their scheme and value, units by their measures, dimensions (if dimensional) by their explicit members and typed contents, and segment and scenario by XML contents, called Open Context Components, or OCCs.

8 Explicit filters

An explicit filter is one that is declared by a formula linkbase filter resource. It has a group filtering behaviour when related to a variable set (value assertion, existence assertion, or formula value and rules producing an output fact). Conversely, it has a fact variable filtering behaviour, when related to a fact variable. The same filter may be related to multiple fact variables and even have group behaviour in one variable set (assertion) and fact filtering behaviour in another variable set.

Filters may be marked as complement, meaning that their boolean result is inverted.

Filters may be combined by and and or relationships using boolean filters, which serve to build groups of filter terms much as parentheses group terms of an expression in a programming language.

Table 2 is a listing of filters by the filter name, aspects covered, filter options, and filter use. The order is by category of filtering action.

9 Implicit filtering

Implicit filtering is used to match the facts bound to a variable set's fact variables in each of the uncovered aspects that each variable's fact(s) has(have), given the aspect model in effect. Implicit filtering doesn't do any matching on any aspect that is covered (when comparing any two facts by any aspect covered on any one of the twofacts).

Implicit filtering can be disabled, for a variable set, by an attribute on the variable set. When disabled, only explicit filtering and user XPath expressions will restrict input instance facts that may be bound to fact variables.

A model-view showing how implicit filtering operates uses the example of Figure 11, where there is a changes variable, filtered only by its concept name, to which balance variables are matched, after explicit filtering on concept name and instant duration period. The balance variables are in all other aspects matched to the concept fact.

The initial fact variable to be bound to a fact is $changes, because both the balance variables depend on it (for explicit filtering of their respective periods). Figure 19 shows that initially all implicit search aspects are unconstrained. In the second column, a concept filter introduces a covered aspect, which is the concept aspect. (The concept name is not to be compared to other fact variables, so it is 'covered'.) In the third column, the aspects that may be carried forward, figuratively, to the next fact variable binding step, include unconstrained aspects for all but concept, which is 'changes'. When matched to a concept fact, as indicated in the rightmost column, the aspects carried forward to the next binding step reflect all the aspects of the $changes fact (with concept name covered).

The next fact variable to be bound to a fact is (either of) the balances fact variables. For this illustration we assume the starting balance is bound first, as shown in Figure 20. The search criteria for a starting balance begins with the aspects uncovered from $changes, and an explicit filter for period (to match the start of the duration period of $changes). The resulting search criteria are shown in the third column, with the bound fact's aspects in the right column.

The last fact variable to be bound to a fact is the other balances fact variable, as shown in Figure 21.

These figures are only used as an illustration, and belittle the actual logic used in explicit and implicit filtering. The trace steps of the original example, and corresponding source code of the open source project used to obtain the trace, provide one possible implementation strategy (but are not proscriptive of an expected strategy).

10 Fact variable fallback values

The example of Section 6.3.2 introduced the notion of fallback values, which allowed the example to evaluate an an assertion which otherwise would not have evaluated because one of the facts was missing. A fallback value is useful to allow assertions and formulas to proceed to evaluation under these circumstances.

Fallback values are assigned to fact and general variables that have @fallbackValue attributes when the variable binds to an empty sequence. For fact variables this means that no facts passing explicit and implicit filtering were identified.

A fallback value isn't helpful for the situation where all variables might fall back in the same evaluation, because for an evaluation (that has variaables) to proceed at least one variable must be bound to a nonempty sequence.

A fallback value is never assigned when to a fact variable that has a bound value in another like evaluation. This prevents having an evaluation where a fact is found duplicate an almost-clone evaluation where the same fact variable is assigned the fallback value. Logic needed to implement this is similar to other predicate-logic computer science languages that maintain a trail of 'visited' evaluations.

The expression for a fallback value cannot have a reference to another fact or general variable (but it may refer to a parameter). The reason it cant reference other variables is that would introduce a specified dependency order, where the desire for fallback values is to be able to substitute for any missing fact.

Fallback values for fact variables are always atomic (scalar valued, not node-valued). The fallback value has no aspects and does not participate in implicit filtering of other variables (and also would be ineffectual if used as an aspect reference variable for a relative filter, match filter, or dimension filter.

11 Existence assertions

An existence assertion is useful for checks of static existence, such as to assure that document descriptive facts such as form type, company identification, and filing identification are present. It is not useful for dependent checks of fact presence for dimension, period, and other reference qualifications, because the existence filter only operates globally. (A value assertion can be used in those cases.) The processing model of an existence figure is shown in Figure 22. The test expression of an existence assertion checks the count of completed evaluations of the variable set, but does not have access to any fact or general values of the completed individual evaluations.

11.1 Example testing existence of a net incomes fact

The first example is a companion to the example in Section 6.1, here testing that a net incomes fact has been reported. A tool-view of the corresponding assertion is shown in Figure 23. The top line is the existence assertion, with no test expression provided. This then will be successful if at least one evaluation of the existence assertion's variable set occurs (which is the case with the sample data in formula example 20). The model for how the assertion declares this is shown in Figure 24

Figure 23: Assertion to test existence of a net incomes fact.

A model-view of an existence assertion, based on the use of UML state symbols expressing a stateful outer counter for an inner state representing evaluation(s) of the variable set .

Figure 24: Existence assertion model.

12 Formulae to produce output XBRL instance facts

Section goes here (this referring to formula constructs that produce an output fact into an output XBRL instance)

13 Consistency assertions

Section goes here

14 Validation messages

Section goes here

15 Function registry overview

Section goes here

16 Custom functions

Section goes here (declaring custom functions)

17 Multi-instance overview

Section goes here

17.1 Chaining by instance relationships

Section goes here

Figure 27: Chaining by instance relationships.

18 Tuple output production overview

Section goes here

18.1 Chaining with variable scope relationships

Section goes here

Figure 29: Chaining by variable scope relationships.