Draft documentation (v1)
published Sep '19

XULE is an expression syntax that allows the querying of XBRL reports and taxonomies using a XULE processor. The primary purpose of XULE is to provide a user friendly syntax to query and manipulate XBRL data. Unlike XBRL Formula XULE does not have the ability create facts or define new XBRL reports. XULE has been primarily used to validate SEC filings as part of the DQC rules. The DQC rules are published in a XULE format. XULE is also used to query XBRL taxonomies and render them as open API schema's, or as iXBRL forms. XULE is syntax independent and will operate on XBRL reports published in JSON, iXBRL, CSV and XML formats. The language operates on an XBRL data model and ignores the XBRL syntax. For example XULE does not allow a user to query all the XML contexts in an XBRL report in an XML format.

XULE Overview

The XULE syntax has two distinct components. The first is factset selection and the second is taxonomy navigation. Factset Selection A factset is a XULE term that defines the facts in an XBRL report and their associated decimals, units and contexts. Every fact has aspects associated with it that defines what the fact is, how it is disaggregated and the period at which the fact was measured at or the duration it occurred over. Factset searching (also called filtering) is the action of extracting data from an XBRL report based on the aspects of the fact. XULE allows a user to put these values into a set, list or dictionary and manipulate the filtered data. Because all of the data is in sets, lists or dictionaries, basic set manipulation can be performed on the data such as a union or intersection or complement. A XULE rule can search a factset not only using the aspects of a fact, but also the properties of the aspect. For example, this allows a user to return all monetary concepts in a XBRL report, or all fact values with a debit balance. XULE also permits the evaluation of expressions between factsets such as Assets minus Current Assets to derive Non Current Assets. Taxonomy Navigation XULE allows the navigation of XBRL networks across many taxonomies. This means XULE can compare relationships between taxonomies by combining taxonomy navigation with set manipulation features. For example, a rule can compare the structure of the company extension taxonomy against the US GAAP taxonomy. The resulting taxonomy relationship sets can then be combined with a factset to determine where values have been used.

Factset Selections

The XULE syntax allows the user to filter data from an XBRL report. Selecting factsets from an XBRL report is called factset filtering. Data can be filtered in many different ways. The most basic is by XBRL concept. The following example shows a basic concept filter that returns Asset data. @concept = Assets For the Apple Inc. 2019 3rd Quarter filing this will return:
365,275,000,000 322,239,000,000
Note how the keyword @concept is used to indicate that the item to search on is a concept. The @ sign indicates a filter aspect is being defined. Additional filters or search parameters can be added for taxonomy defined dimensions, and built in dimensions such as periods, units and entities. For example to get IPhone sales from the same Apple report filter on the concept "RevenueFromContractWithCustomerExcludingAssessedTax" and the "ProductOrServiceAxis" where it is equal to IPhone. @concept = RevenueFromContractWithCustomerExcludingAssessedTax @ProductOrServiceAxis = IPhoneMember This will return values of:
29,470,000,000 - Q3-2018 128,133,000,000 - 3QCUM-2018 25,986,000,000 - Q3-2019 109,019,000,000 - 3QCUM-2018
By dropping the concept filter all the data relevant to IPhones is returned: @ProductOrServiceAxis = IPhoneMember Factset filtering also supports filtering on attributes of aspects. A dot notation allows attributes of aspects to be used as the filter condition. For example to return all the monetary amounts in a filing the following expression is used: @concept.data-type = xbrli:monetaryItemType The aspect filter concept.data-type identifies all the concepts used in the filing that are a monetaryItemType, and returns all monetary facts. The detailed options available within factset filtering are defined in detail in the XULE guide and the XULE examples page.

Taxonomy Navigation

Navigation is used to traverse the relationships in a taxonomy. A navigation returns a set. The items in the set are determined by what is provided in the navigation expression. In its simplest form, navigation requires a direction. navigate descendants This will return all the descendent concepts across all networks in the taxonomy referenced by the XBRL report. To limit the results to a specific relationship type the user can specify this following the the navigate keyword. navigate parent-child descendants This will return all descendant concepts in the presentation parent-child relationships of the taxonomy referenced by the XBRL report. The taxonomy navigation feature allows a user to navigate presentation, calculation and dimensional networks, independent of the facts reported in an XBRL report. XULE navigation allows the following:
  1. Define the start point for navigation
  2. Define the direction of travel
  3. Define the levels of a network tree to navigate
  4. Define a stop point within a network tree
  5. Define specific network trees to navigate such as BalanceSheet
  6. Define network types to navigate such as calculations
  7. Define conditions when navigation should stop
  8. Filter network results based on specified conditions
  9. Navigate Cubes (Tables)
  10. Control the attributes that are returned.
  11. Specify the taxonomy to navigate
Taxonomy navigation is explained in more detail in the XULE guide and the XULE examples.  

Filed as: Using XBRL DataAll Domainsdraft