Getting Started for Developers

Need to work out where to start?

Software developers tend to do one of two things when first approaching XBRL. They make an assumption that it’s “just” XML and consequently underestimate the size of the task they have. Or, they get bogged down in the formal specifications and overestimate the size of the task.

This page provides some very basic pointers that should help developers understand how to avoid these two common mistakes.

Generally, integrate third party software.

XBRL deals with a very complex set of problems. It allows the representation of entire financial statements, multi-dimensional financial risk and exposure reports, tightly inter-related disclosure data and infinitely variable reports. In order to do so, the specifications that create the standard are relatively complex. In particular, developers need to understand that the structure and validation of data contained in XBRL instances is subject to multiple layers of machine readable metadata contained in interconnected XBRL schema and linkbase documents. Developers should also understand that every aspect of an XBRL document (data and metadata) are subject to multiple layers of validation.

For these reasons, the strong recommendation of the XBRL consortium is that developers coming to use the standard for the first time should integrate third party libraries to deal with XBRL data and metadata (whether producing or consuming that information) rather than attempting to implement the XBRL specifications themselves, from scratch. Of course, this assumes that the developer’s interest is in adding XBRL support onto an existing system, for example, creating an XBRL mapping and export function, or an XBRL import function, or an XBRL analysis capability as part of a larger system. Once developers become familiar with XBRL, then it might very well be sensible to replace or enhance that third party component with a native code base.

There are both commercial and open source libraries available today. Explore some of the options in the Tools and Services section.

Understanding the very basics.

Developers need to understand a few of the basics of XBRL: Concepts, Taxonomies, Values, Contexts, Facts, Instances and Dimensions.

Definitions or Metadata

The foundation of XBRL is the idea of a concept, which is the definition of a term that needs to be, or might be, disclosed in a particular domain. Profit is a concept that is often disclosed in a business domain.

Concepts are made more meaningful with a range of supporting information as well as explicit creation of the relationships between different concepts. Profit is what’s left after Expenses are taken from Income. The concept Profit has a number of labels, for different purposes. For example, it should be displayed as “loss” when there were more expenses than income. Labels in XBRL often  appear in multiple languages. And concepts are defined by — and reference — relevant authoritative standards, rules or legislation.

Collections of related concepts are held in an XBRL taxonomy. XBRL taxonomies are the metadata framework against which information can be reported. Major accounting and risk domains are modelled as XBRL taxonomies, including IFRS, US GAAP, Chinese GAAP, Japanese GAAP, and the European Basel III bank reporting framework CRD IV and insurance reporting framework, Solvency II amongst many others.

Data

From an XBRL perspective, the values reported against this metadata are just that – a value, be it a numeric, monetary, boolean, text value – or occasionally even an encoded value like a picture or a chart. The value 1000 can be associated with the concept Profit.

But that value-concept pairing isn’t meaningful unless the data is provided with additional information that provides some context. Who made the profit? What period did that profit relate to? In what currency was the profit reported in?

By combining a concept (profit) from a taxonomy (say Canadian GAAP) with a value (1000) and the needed context (Acme Corporation, for the period 1 January 2015 to 31 January 2015 in Canadian Dollars) we arrive at a fact. Collections of facts in XBRL are contained in documents called instances. Instance documents are XBRL based reports about performance, risk, compliance or some other set of logically consistent information that needs to be communicated internally or externally.

Individual organisations (public sector, private sector, voluntary sector – anyone that needs to report information) will typically prepare a new instance document every reporting period. Each report (instance) will contain different values, (the profit in February will be different to the profit in January) associated with different contexts (ie: at least the dates will change) against concepts that are unlikely to change very often, but will do so from time to time. Acme Corporation might report profit every month, but it might only have to disclose “restructuring costs” once every ten years.

Dimensions

Most XBRL environments also allow organisations to report multiple values against the same concept, for various kinds of repeating values. For example, Acme Corporation might have a different operation in several different Canadian provinces, and multiple stores in each province. XBRL provides dimensions to cater for this kind of tightly related information. Dimensions are an additional kind of metadata, that can be defined in taxonomies and then applied to instances as an additional piece of context. Instances that report dimensionally will have multiple contexts that reference different dimension members, applied to multiple facts. So if Acme has profit to report in Alberta, British Columbia and Ontario, but a loss in Manitoba, it will have 5 different facts to report, a profit value against each of the four provinces, and another, overall profit value for the company as a whole. Dimensions can be rolled up (so that sum of the values in the stores in Alberta contribute to the value for that province). They are a very common aspect of financial and particularly risk reporting.

Extensions

The last fundamental point to understand is the idea of the XBRL extension.

Taxonomies can be extended in order to modify the relationships between existing concepts, or to add new concepts to an existing taxonomy. Extension taxonomies are separate documents that import the base taxonomy and override certain aspects of the original. Acme Corporation might report information about share buy backs that the official Canadian GAAP taxonomy doesn’t provide, so in order to report that information in the way that it appears in the old style printed report, Acme can define that new concept and include it in an extension taxonomy. Done right, extensions provide richer and more informative information about specific reporting arrangements carried out by different organisations. Done wrong they can hinder comparability. Many XBRL reporting environments either don’t allow their use or severely restrict their use. It is fair to say that they are a very powerful two edged sword.

XBRL is based on metadata. Your design needs to take this into account.

XBRL taxonomies are the fundamental building blocks of XBRL. Building blocks that can and will change over time. Hard coding data mapping or data transformation against taxonomies will result in significant maintenance challenges. Develop mechanisms that allow data sourcing and loading to take account of changing taxonomies, whether you are working on data preparation or data consumption.

Always use a test-driven approach.

The use of both syntactic and semantic rules are a fundamental part of most regulatory environments. These rules are published and can be automatically executed against draft instance documents before they are filed. Corporate and supply chain environments can (and should) use the same mechanisms to ensure the quality, consistency and interoperability of the data.

In addition, the specifications utilise extensive conformance suites that provide pass and fail conditions to check whether or not specific code is dealing with XBRL information correctly.

The lesson? Always validate your XBRL documents throughout the process of their preparation. And always validate your XBRL software while it is under development or being integrated into your system.

Extremely significant capabilities.

Developers should be aware of some of the breadth of capabilities of XBRL.

It can:

• be used to create fixed and extensible reports for a huge range of reporting.
• be used to create on-the-fly forms based on taxonomies and the table linkbase to collect and validate very complex information.
• be used to present financial statements and reports with the exact look and feel that the preparer chooses, in HTML, via the iXBRL specification. Inline XBRL or iXBRL provides a straightforward and verifiable way to convert values set out on a web page into facts in a generated XBRL document.
• be used to develop business logic validation rules as well as entirely new business facts, via the formula linkbase.
• be used to capture ledger and transaction level data, with links back to relevant reporting concepts for audit purposes, later aggregation, exchange and consolidation of information across disparate systems. These capabilities are enabled by XBRL Global Ledger.

Membership saves money and time.

XBRL is a powerful and sophisticated framework for digital reporting and more and more accounting, reporting, analytical, audit and supply chain software professionals need to become expert in its use. Developing the requisite levels of knowledge outside the XBRL consortium is harder than doing so within it, where there is a large community of experts that are very happy to help answer questions, provide examples, connections and ideas. Joining and participating in the XBRL consortium is a straightforward way to rapidly learn, avoid mistakes, avoid reinventing wheels and accelerate development efforts. Not to mention the fact that it opens up the opportunity to help with the ongoing work to simplify the standard. You can find information about the benefits of joining XBRL International or your local Jurisdiction in the Consortium pages.