Functions & Properties

Before a XULE expression can be executed it needs to be compiled. The expression can be either compiled at run time or compiled and saved and run separately. The latter is how the Data Quality Committee ruleset .zip files are distributed from the reference implementation code.

As an example, the snippet below as ‘Assets.xule’ – it will return the value of Assets with no dimensions reported in specified filings:

output assets[@concept.local-name = 'Assets']

In the command below the xule file called Assets.xule will be compiled and processed in a single step.

python3.9 arellecmdline.py --plugins xule -f https://www.sec.gov/Archives/edgar/data/1095595/000095010320007907/ceo-20191231.xml --noCertificateCheck --xule-compile "path/to/sample.xule" --xule-run --xule-rule-set "path/to/sample.zip"

This command uses the Arelle command line program called arellecmdline.py.

The xule plugin is called using the –plugins argument which is included in the Arelle plugins library in the Arelle distribution.

• the -f argument to select the instance document that will be processed. This can be a url or a local file.

• the –xule-compile argument identifies the location of the xule expression file. In this case it is Assets.xule.

The command line uses some additional options:

• the argument –noCertificateCheck is used to perform an https connection to the SEC
• the –xule-run argument instructs the processor to process the instance
• the –xule-rule-set argument tells the command line where to put the compiled xule rule.

Aggregation of Facts

Shown below are the various aggregation functions and properties shown in use as a function or as a property. When performing aggregation functions on facts in an XBRL Report they should be put into a list before the aggregation is performed.

Average

avg(list({covered @Assets}))

list({covered @Assets}).avg

Count

count(list({covered @Assets}))

list({covered @Assets}).count

Sum

sum(list({covered @Assets}))

list({covered @Assets}).sum

Max

max(list({covered @Assets}))

list({covered @Assets}).max

Min

min(list({covered @Assets}))

list({covered @Assets}).min

Standard Deviation

stdev(list({covered @Assets}))

list({covered @Assets}).stdev

Product

prod(list([covered @Assets where $fact > 0]))

list([covered @Assets where $fact > 0]).prod

First

first(sort(list({covered @Assets})))

list({covered @Assets}).sort.first

Last

last(sort(list({covered @Assets})))

list({covered @Assets}).sort.last

All

all(list(true, true, true))  :  Returns true

list(true, true, true).all

Any

any(list(true, true, false)) : Returns true

list(true, true, true).any

Properties of Facts

Shown below are the examples using fact properties to extract data from an XBRL report. The variable $fact shown in the examples is the fact extracted from the XBRL report. $fact is the default variable returned when the where clause is used in an expression.

Decimals

count(list({covered @Revenues where $fact.decimals == -6})) : Returns the count of values in Millions

Concept Name

count(list({covered where $fact.concept.name == Revenues})) : Returns the count of facts using the concept Revenues

Period

count(list({covered @concept = Revenues where $fact.period.days > 100})) : Returns the count of Revenue facts with a duration greater than 100 days

Period Start

count(list({covered @concept = Revenues where $fact.period.start > date('2015-12-15')})) : Returns the count of Revenue facts that start after 2015-12-15

Period End

count(list({covered @concept = Revenues where $fact.period.end > date('2016-12-15')})) : Returns the count of Revenue facts that end after 2016-12-15

Taxonomy Defined Dimensions

count(list({covered @StatementBusinessSegmentsAxis = * where $fact.dimension(StatementBusinessSegmentsAxis).name == f:FinancialServicesSegmentMember})) : Returns the count of  facts that have the f:FinancialServicesSegmentMember on the StatementBusinessSegmentsAxis.

Can also be written as the following but this does not use the fact.dimension property:

count(list({covered @StatementBusinessSegmentsAxis =f:FinancialServicesSegmentMember}))

Units

count(list({covered @concept = Assets where $fact.unit == unit(iso4217:USD)})) : Returns the count of facts in USD.

Entity

{@where $fact.entity.id = ‘00000000001’} : Returns all facts for entity 00000000001

Selecting Factsets

Factset selection is performed using aspect filters to limit the facts returned.  If no filters are defined then all the facts in the XBRL Report will be returned.

No Filters

To return all the facts in an XBRL Report no filters need to be defined. The following expressions will return all the facts in an XBRL Report into a list.

list(covered @)

list({covered})

list({covered @})

Select facts with no Taxonomy Defined Dimensions

list([covered])

list([covered @])

Selecting Concepts

Select all Assets with no taxonomy defined dimensions and add to a list:

list([covered @Assets])

Select all Assets into a list and sum the list:

sum(list({covered @concept = Assets}))

Select all Assets irrespective of namespace with no taxonomy defined dimensions and add to a list:

list([covered @concept.local-name = 'Assets'])

Select all facts that are measured at a point in time.

@concept.period-type = instant

Select all facts that are measured over a duration of time.

@concept.period-type = duration

Select all facts that use a concept with a balance type equal to debit.

@concept.period-type = instant @concept.balance = debit

Select all facts that use a concept with a balance type equal to credit and add to a list.

list([covered @concept.period-type = instant @concept.balance = credit])

Select all facts that use a concept that is a monetary item type, and have no taxonomy defined dimensions and add to a list.

list([covered @concept.data-type = xbrli:monetaryItemType])

Select all facts that use a concept that is a string item type.

@concept.base-type = xbrli:stringItemType})

Select all facts that use a concept with an enumeration equal to “dei”

@concept.enumerations = 'dei'

Select all facts that use a concept with a enumerations

@concept.has-enumerations = true

Select all facts that use a concept that is  monetary.

@concept.is-monetary = true

Select all facts that use a concept that is not monetary.

@concept.is-monetary = false

Select all facts that use a concept that is a number.

@concept.is-numeric = true

Select all facts that use a concept that is not a number.

@concept.is-numeric = false

Select all facts that use a concept that are from the 2014 dei taxonomy.

@concept.namespace-uri = 'http://xbrl.sec.gov/dei/2014-01-31'

Select facts based on multiple concepts and record in a list.

list([covered @concept in list(Assets, Liabilities)])

Selecting Periods

Select all instant facts that have a date of  ‘2017-12-31’ and add to a list.

list([covered @period = date('2017-12-31')])

Select all Asset facts that have a date of  ‘2017-12-31’ and add to a list.

list({covered @Assets @period = date('2017-12-31')})

Select all facts that have a start date of  ‘2017-01-01’ and end date of ‘2017-12-31’ or have an instant date of ‘2017-12-31’

@period in list(duration('2017-01-01', '2017-12-31'), date('2017-12-31')

Select ProfitLoss facts that have a start date of  ‘2017-01-01’ and have no dimensions

[@concept = ProfitLoss @period.start = date('2017-01-01')]

Select all facts that are 90 days in duration and add to a list.

list({covered @period.days = 90})

Selecting Units

Select all facts with a unit of pure.

@unit = unit(xbrli:pure)

Select all facts with a unit of USD/shares.

@unit = unit(iso4217:USD, xbrli:shares)

Select all facts with and without units (All facts in the XBRL Report) and add to a list.

list({covered @unit})

Select all facts that have a unit.

@unit = *

Selecting Entities

Select Assets facts reported with an SEC identifier and add to a list.

list({covered @Assets @entity.scheme = 'http://www.sec.gov/CIK'})

Select Assets facts reported with the identifier of 0000320193 and add to a list.

list({covered @Assets @entity.id='0000320193'})

Selecting Taxonomy Defined Dimensions

Selects facts with the ConsolidationItemsAxis. It does not return values with no dimensions (default values). It includes facts that have other dimensions in addition to the ConsolidationItemsAxis.

@ConsolidationItemsAxis = *

Selects facts with only the Consolidation Items Axis. It does not return default values because the filter uses square brackets . It also will not return Asset facts that have other dimensions in addition to theConsolidation Items Axis and adds to a list.

list([covered @Assets @ConsolidationItemsAxis = *])

Selects Asset facts including default values in the instance, but takes the ConsolidationItemsAxis out of alignment and adds to a list.

list({covered @Assets @ConsolidationItemsAxis })

Selects Asset facts with the ConsolidationItemsAxis. It also returns default values. It will not return Asset facts that also have other dimensions and adds to a list.

list([covered @Assets @ConsolidationItemsAxis ])

Selects Assets facts that are reconciling items or operating segments in a consolidation and are on the Statement Business Segment axis only.

[@Assets @StatementBusinessSegmentsAxis = * @ConsolidationItemsAxis in list(MaterialReconcilingItemsMember, OperatingSegmentsMember)]

Selects Assets facts that are not MaterialReconcilingItems.

list({covered @concept = Assets @ConsolidationItemsAxis != MaterialReconcilingItemsMember})

Selecting with a WHERE clause

Selects all numeric facts where the fact value is less than 0. Note that $fact is equivalent to the value.

list({covered @concept.is-numeric = true where $fact < 0})

Selects all facts with the OperatingSegmentsMember with a value greater than 0. This could be done more easily in this example with the aspect filter :ConsolidationItemsAxis = OperatingSegmentsMember. This approach can be useful when the taxonomy defined dimension is a a variable.

list({covered @Assets  where $fact > 0 and $fact.dimension(ConsolidationItemsAxis).name == OperatingSegmentsMember})

Selects all facts with the OperatingSegmentsMember without having to know that the fact is on theConsolidationItemsAxis.

list({covered @Assets where $fact.dimensions().values.name.contains(OperatingSegmentsMember)})

Selecting with an Alias

Like SQL XULE allows the use of an alias to make selections easier.

Selects Assets facts on the ConsolidationItemsAxis that are greater than zero using an alias

list({covered @Assets @ConsolidationItemsAxis = * as $lea where $fact > 0 and $lea == OperatingSegmentsMember})

Selecting Factsets with an Evaluation

Factsets can be compared to other factsets in a XULE expression.  When one factset is compared to another factset the values are automatically aligned so that when Liabilities is deducted from Assets it is done with comparable periods. i.e. Liabilities for 2017 is deducted from Assets for 2017 not 2018 or 2019

Returns the value of Assets for the operating segment less the Debt And Capital Lease Obligations for the same operating segment and ignores any facts with other taxonomy defined dimensions.

[@Assets @ConsolidationItemsAxis in list(OperatingSegmentsMember) ] - [@DebtAndCapitalLeaseObligations @ConsolidationItemsAxis in list(OperatingSegmentsMember)]

Returns a list of true or false values. When a numeric item is less zero a true value is returned.

list({covered @concept.is-numeric = true} < 0)

Navigating Networks

Navigation of Children

Returns a list of all children concepts of any relationship in the taxonomy

navigate children

Returns a list of all children concepts of any parent child relationship in the taxonomy.

navigate parent-child children

Returns a list of all children concepts of any parent child relationship in the taxonomy.

navigate 'http://www.xbrl.org/2003/arcrole/parent-child' children

Returns a list of all children concepts of any parent child relationship in the Consolidated Balance Sheet of the taxonomy.

navigate parent-child children role ConsolidatedBalanceSheet

Navigation of Descendants

Returns a list of all descendant relationships from the root element of any tree in the taxonomy.

navigate descendants

Returns a list of all descendant relationships from the root element of any parent child tree in the taxonomy.

navigate parent-child descendants

Returns a list of all descendant relationships from the root element of any parent child tree in the taxonomy. (Same as above)

navigate 'http://www.xbrl.org/2003/arcrole/parent-child' descendants

Returns a list of two descendant relationships from the root element of any parent child tree in the taxonomy.

navigate parent-child descendants 2

Returns a list of two descendant relationships from CashAndCashEquivalentsAtCarryingValue including the CashAndCashEquivalentsAtCarryingValue element for any parent child tree in the taxonomy.

navigate parent-child descendants 2 from CashAndCashEquivalentsAtCarryingValue include start

Navigation of Ancestors

Returns a list of those relationships that are ancestors of the element CashAndCashEquivalentsAtCarryingValue in all networks.

navigate ancestors from CashAndCashEquivalentsAtCarryingValue

Returns a list of those relationships that are ancestors of the element CashAndCashEquivalentsAtCarryingValue in the presentation networks.

navigate parent-child ancestors from CashAndCashEquivalentsAtCarryingValue

Returns a list of two relationships that are the parents and grandparents of the element CashAndCashEquivalentsAtCarryingValue in the presentation networks for the Balance Sheet.

navigate parent-child ancestors 2 from CashAndCashEquivalentsAtCarryingValue role ConsolidatedBalanceSheet