1 Introduction
XBRL [XBRL 2.1] enables the capture of structured meta-data for a particular reporting scenario in the form of an XBRL taxonomy. Taxonomies are rarely static objects, and will need to be updated periodically for a range of reasons, including changes in the business requirements upon which they are built (for example, a change to an accounting standard), changes to the technical design of the taxonomy, or simple error corrections. When a new version of a taxonomy is released this has an impact on all users of the taxonomy including:
- Instance document creators, and developers of instance creation software;
- Creators of taxonomies that extend the taxonomy in question, and developers of extension taxonomy creation software; and
- Instance document consumers, who wish to be able to compare instance documents prepared against the different taxonomy versions.
The XBRL Versioning specification defines an XML syntax for a Versioning Report that is designed to allow taxonomy creators to communicate information about the changes between two taxonomy versions in a structured format that will minimise the impact of the update on the users of the taxonomy. Versioning Reports concern only DTSes and related XBRL instances.
A Versioning Report is distinct from a simple difference report in that a Versioning Report includes information that cannot be obtained from an automated comparison of two DTSes such as identifying concepts with different names that are otherwise equivalent, and communicating information about the motivation behind changes. It is this ability to communicate additional information that yields value in creating a standardised Versioning Report. The goal is to facilitate DTS and related XBRL instance users/consumers in adapting existing systems to accommodate a different DTS and XBRL instance structure.
It should be noted that whilst the primary use case considered in the creation of this specification is the provision of versioning information between two versions of the same taxonomy, the specification makes no assumptions about the relationship between taxonomies involved, and a Versioning Report can be prepared for any pair of DTSs. Furthermore, the specification makes no assumptions that a Versioning Report provides complete documentation of differences between the From DTS and To DTS.
The instance-aspects extension module specifies how to map and address changes to the aspects of fact items of a set of concepts, including dimensional and other aspects, specifying that changes have occurred between different DTSes to items that may be a primary item and its dimensions and domain-members, or other aspects that may distinguish the fact item.
Although the concept of versioning may be thought of to relate to consecutive versions of the same taxonomy, it applies as well to documenting the difference between unrelated taxonomies describing the same business fact, such as between independent Financial Reporting representations that can report equivalent facts or between Global Ledger an Financial Reporting representations.
This primer is non-normative. All normative definitions, formats, and validation rules are contained in the various modules that make up the Versioning Specification.
2 Background
In order to understand the XBRL Versioning Specification it is necessary to have a suitable background in XML[XML Base], XML Schemas[XML Schema Structures], Linkbases[XLINK], XML Namespaces [XML Names], and XBRL[XBRL 2.1]. In particular, it is necessary to understand specific XBRL concepts around taxonomies, DTSes, XBRL facts, and XBRL dimensions [DIMENSIONS].
3 Modularity
The XBRL Versioning Specification is a modular specification designed to allow the author of a Versioning Report to select the level of detail at which changes are documented. The modular approach allows for versioning information on extensions to the XBRL Specification [XBRL 2.1], such as the XBRL Dimensions Specification [DIMENSIONS], to be addressed as extension modules. Extension specifications also provide finer levels of versioning information.
Versioning Reports may use one or more extension specifications in addition to the Base Specification, which is always required. Other module dependencies may also exist.
4 Technical and Semantic Differences
XBRL Versioning supports both technical differences and
semantic differences between DTSes. Technical
differences are those that can be automatically identified by software
comparing the properties of the pair of information items under observation
(e.g. "element <netValue> has been removed"). Semantic
differences are the explanations of the technical
differences made by the authors of a versioning report (e.g. "Net Value,
as represented by the <netValue> element, has been replaced by three
new line items ..."). Given two DTSs and some rules to match
information items from one DTS to the other, the technical
differences are fixed and well defined, however the semantic
differences are unlimited since a DTS does not embed detailed semantic
background for individual XBRL concepts or the association of differences
between two taxonomies. An XBRL Versioning Report provides a mechanism to
capture and document both, including human-readable documentation that may be
useful input to users migrating an application from using one DTS
to another.
5 Key Concepts
A Versioning Report describes the technical and semantic differences between an origin DTS, named the From DTS, and a destination DTS, named the To DTS. It does this using a standard format XML instance document that conforms to the structure described in the various XBRL Versioning Report specification modules, as well as a set of linkbase documents. The XBRL Versioning Report document contains the technical differences between the From DTS and To DTS, and references to the associated linkbase documents that describe the semantic differences.
The partitioning of changes documented into versioning modules is shown in Figure 1. A simple Versioning Report that documents only a change of namespace between two DTSes would only require the versioning syntax defined by the Base module. A more advanced Versioning Report that also documented the addition, removal or renaming of concepts would need to include features from the Concept Basic module in the same report. Changes to the concepts, such as type, period, or label, are documented using the Concept Extended module. Changes to the identification of facts in XBRL instances, such as to dimensions, segment, scenario, and tuple location, are documented with the Instance Aspects module. Changes to the relationship sets for presentation, calculation, and structure of dimensional syntax, are documented with the Relationship Sets module.
Structurally, a Versioning Report has a simple three-tier hierarchy. This is used to group changes at both the semantic and technical levels. At the highest level there are Assignments which document business level changes. Semantics associated with such changes can then refer to a single Assignment, which may in turn capture many Actions. These provide the middle tier of logical changes between DTSes. The lowest-level tier is Events which represent the specific technical changes to map one DTS to another. Independently, the set of all Events provides as much information as the entire Versioning Report regarding the technical changes, however they lack the structure that enables a semantic interpretation and understanding of the reasons for those changes. Generic Events don't directly appear in a versioning report. Instead they are abstract place holders for which each module specification defines specific syntax for change events, such as "add" or "remove".
The base, concept, and relationship-set modules focus on documenting issues of change between two DTSes, such as schema file changes of namespace, concept name or attribute, and linkbase relationships, and the instance aspects module focuses on how facts representing the same reported business item are modelled differently in instances of the respective DTSes in terms of aspects such as the concept and dimension.
The utility of documenting aspect identification changes is for preparation and consumption of an instance document. Mapping software that may convert source data into XBRL, and analytic software that may analyse reported business facts, both need this sort of versioning information, which is from the instance perspective instead of the taxonomy perspective.
Simple extension of this issue also handles cases where other aspects of business fact identification change, such as segment and scenario identification that becomes dimensional, and tuple located facts that are identified by tuple siblings, cousins, and such, become dimensional facts (or the converse).
6 Examples
6.1 Statutory change resulting in namespace and concept renaming
The simple example of Figure 2 illustrates a Versioning Report for a statutory change resulting from a new tax year. The base taxonomies contain only four concepts each, and there are only two changes between the 2009 and 2010 versions: the namespace changes (to reflect the change of year and a new taxonomy version), and one concept is renamed (from DebtOutstanding to TotalDebt). The namespace mapping can be done using the Base module. The concept renaming event requires events defined in the Concept Basic module, illustrating the use of modules in a Versioning Report. Using the Mapping rules, all concepts in the new taxonomy that have the same localname as the old taxonomy are considered Equivalent.
xmlns:veria="http://xbrl.org/2010/versioning-instance-aspects"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xbrli="http://www.xbrl.org/2003/instance"
xmlns:prs-09="http://prs.example.com/xbrl/2009"
xmlns:xbrldt="http://xbrl.org/2005/xbrldt"
xmlns:prs-10="http://prs.example.com/xbrl/2010"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ver="http://xbrl.org/2010/versioning-base"
xmlns:verrels="http://xbrl.org/2010/versioning-relationship-sets"
xmlns:vercb="http://xbrl.org/2010/versioning-concept-basic"
xmlns:link="http://www.xbrl.org/2003/linkbase"
xmlns="http://xbrl.org/2010/versioning-base" xsi:schemaLocation="http://xbrl.org/2010/versioning-base ./../../../schema/versioning-base.xsd http://xbrl.org/2010/versioning-concept-basic ../../../../schema/versioning-concept-basic.xsd">
As mentioned earlier, the XBRL Versioning Report primarily details technical differences. Semantic differences and interpretation of changes are described via linkbases. The following illustrates a linkbase that documents each Assignment, Action, an Event in the Versioning Report.
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:gen="http://xbrl.org/2008/generic"
xmlns:label="http://xbrl.org/2008/label"
xmlns:link="http://www.xbrl.org/2003/linkbase">
This shows the original From DTS for the 2009 taxonomy:
xmlns:prs="http://prs.example.com/xbrl/2009"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:link="http://www.xbrl.org/2003/linkbase" targetNamespace="http://prs.example.com/xbrl/2009" elementFormDefault="qualified" attributeFormDefault="unqualified">
This shows the target To DTS for the 2010 taxonomy:
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:prs="http://prs.example.com/xbrl/2010"
xmlns:link="http://www.xbrl.org/2003/linkbase" targetNamespace="http://prs.example.com/xbrl/2010" elementFormDefault="qualified" attributeFormDefault="unqualified">
6.2 The various uses for the Concept Delete
The Concept Delete in its simplest form is used to represent the fact that a Concept has been physically removed from a taxonomy. But there are various variations on this idea that result in the Concept Delete being a little broader than it appears at first glance. The Concept Delete is used to convey the business usage of a concept, not its technical implementation. This means that an element could be in the schema but be "deleted" as if to say it is no longer to be used.
As well as being for a removal from a taxonomy the Concept Delete can be for the removal in a DTS that is not the entry point of the whole taxonomy but a sub part. If, say, a concept was imported into a schema from an external taxonomy and is no longer referenced by the schema it has been deleted from this schema but not from the external taxonomy.
It could be that the concept is still in the schema but the business use of the concept has been deprecated. A deprecation could be implemented without change to the schema just by publishing an errata statement on the taxonomy website. The Concept Delete could communicate this change technically from the business content on the website and would communicate to the technical consumers not to value the content of the concept.
More detailed examples of this will be provided in the overview document.
6.3 Change to dimensional representation of set of concepts
The example of Figure 3 illustrates a Versioning Report for a technical change resulting from the introduction of dimensions to a replace a hierarchy of concepts. In this case facts representing the same reported business item are modelled differently in instances of the respective DTSes in terms of aspects such as the concept and dimension. The Versioning Report includes a description of the assignment, using the Base module, a description of the deleted concepts of the hierarchical representation and the addition of new concepts in the dimensioned instance. (It is assumed that the dimensions themselves were either in existence or documented separately.)
- Change to dimensional representation of set of concepts
- Unchanged from business perspective
- Concept and dimensions aspects changed
Version 1 Version 2 A X (dim D, mbr d1) B X (dim D, mbr d2) C X (dim D, mbr d3) - A, B, C and X are primary items
- D is a dimension (dim)
- d1, d2 and d3 are domain members (mem)
7 Limitations
- XBRL Versioning Reports are designed to support exactly one origin From DTS and one destination To DTS. In cases where a From DTS is being split into multiple To DTSs, or when multiple From DTSs are merged into a single To DTS it is necessary to create multiple Versioning Reports.
- An XBRL Versioning Report may not be capable of documenting every difference between two DTSes. Furthermore, there is no requirement that a Versioning Report author must document every difference. As such, it is not possible in general to reliably reproduce the To DTS given the From DTS and a Versioning Report (or vice versa).