Versioning Primer 1.0

Public Working Draft 19 October 2011

Copyright ©2011 XBRL International Inc., All Rights Reserved.

This version:
<http://www.xbrl.org/WGN/versioning-primer/PWD-2011-10-19/versioning-primer-WGN-PWD-2011-10-19.html>
Editors:
Roland Hommes, Rhocon <roland@rhocon.nl>
Herm Fischer, Mark V Systems <fischer@markv.com>
Paul Warren, CoreFiling <pdw@corefiling.com>
Contributors:
Ian Stokes-Rees, CoreFiling <ijs@corefiling.com>
Haiko Philipp, IFRS Foundation <hphilipp@ifrs.org>
Hugh Wallis, Standard Dimensions <hugh@standarddimensions.com>
Geoff Shuetrim, Galexy <geoff@galexy.net>
Ignacio Hernández-Ros, Reporting Estandar S.L. <ignacio@hernandez-ros.com>
Warwick Foster, SBR Australia <warwick.foster@ato.gov.au>

Status

Circulation of this Public Working Draft is unrestricted. Other documents may supersede this document. Recipients are invited to submit comments to versioning-feedback@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.

Abstract

This primer provides a non-normative introduction to the XBRL Versioning Specification and its extension modules. The purpose of the primer is to inform prospective users of the basic terminology, construction, usage, and limitations of XBRL Versioning as a mechanism to document differences between two taxonomies, typically due to a version update. The central concepts of Assignments, Actions, and Events are explained with XML examples.

Table of Contents

1 Introduction
2 Background
3 Modularity
4 Technical and Semantic Differences
5 Key Concepts
6 Examples
6.1 Statutory change resulting in namespace and concept renaming
6.2 The various uses for the Concept Delete
6.3 Change to dimensional representation of set of concepts
7 Limitations

Appendices

A References
B Intellectual property status (non-normative)
C Acknowledgements (non-normative)
D Document history (non-normative)
E Errata corrections in this document

Figures

1 Changes documented by each module
2 Statutory change resulting in namespace and concept renaming
3 Technical change to the dimensional representation of a set of concepts

Examples

1 Example versioning report
2 Linkbase for example versioning report
3 Old example taxonomy
4 New example taxonomy


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:

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.

Figure 1: Changes documented by each 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.

Figure 2: Statutory change resulting in namespace and concept renaming

Example 1: Example versioning report

<report
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">
<link:linkbaseRef xlink:type="simple" xlink:href="PincusRevenueService-VersioningReport-2009-to-2010-linkbase.xml" xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"/>
<fromDTS>
<link:schemaRef xlink:type="simple" xlink:href="PincusRevenueService-2009.xsd"/>
</fromDTS>
<toDTS>
<link:schemaRef xlink:type="simple" xlink:href="PincusRevenueService-2010.xsd"/>
</toDTS>
<assignment id="asmt-2010-final-budget-update">
<businessCategory/>
</assignment>
<action id="act-2010-satutory-changes">
<assignmentRef ref="asmt-2010-final-budget-update"/>
<namespaceMapping id="evt-2010-namespace-update">
<fromURI value="http://prs.example.com/xbrl/2009"/>
<toURI value="http://prs.example.com/xbrl/2010"/>
</namespaceMapping>
<vercb:conceptRename id="evt-2010-debt-rename">
<vercb:fromConcept name="prs-09:DebtOutstanding"/>
<vercb:toConcept name="prs-10:TotalDebt"/>
</vercb:conceptRename>
</action>
</report>

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.

Example 2: Linkbase for example versioning report

<link:linkbase
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"
>
<link:roleRef roleURI="http://www.xbrl.org/2008/role/link" xlink:href="http://www.xbrl.org/2008/generic-link.xsd#standard-link-role" xlink:type="simple"/>
<link:roleRef roleURI="http://www.xbrl.org/2008/role/label" xlink:href="http://www.xbrl.org/2008/generic-label.xsd#standard-label" xlink:type="simple"/>
<link:arcroleRef arcroleURI="http://xbrl.org/arcrole/2008/element-label" xlink:href="http://www.xbrl.org/2008/generic-label.xsd#element-label" xlink:type="simple"/>
<!-- Label for the assignment -->
<gen:link xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link">
<link:loc xlink:type="locator" xlink:label="target" xlink:href="PincusRevenueService-VersioningReport-2009-to-2010.xml#asmt-2010-final-budget-update"/>
<label:label xml:lang="en" xlink:type="resource" xlink:label="label">
Annual updates following new budget.
</label:label>
<gen:arc xlink:type="arc" xlink:from="target" xlink:to="label" xlink:arcrole="http://xbrl.org/arcrole/2008/element-label"/>
</gen:link>
<!-- Label for the action -->
<gen:link xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link">
<link:loc xlink:type="locator" xlink:label="target" xlink:href="PincusRevenueService-VersioningReport-2009-to-2010.xml#act-2010-satutory-changes"/>
<label:label xml:lang="en" xlink:type="resource" xlink:label="label">
Statutory changes associated with new budget.
</label:label>
<gen:arc xlink:type="arc" xlink:from="target" xlink:to="label" xlink:arcrole="http://xbrl.org/arcrole/2008/element-label"/>
</gen:link>
<!-- Label for the namespace change event -->
<gen:link xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link">
<link:loc xlink:type="locator" xlink:label="target" xlink:href="PincusRevenueService-VersioningReport-2009-to-2010.xml#evt-2010-namespace-update"/>
<label:label xml:lang="en" xlink:type="resource" xlink:label="label">
Namespace mapping from 2009 to 2010.
</label:label>
<gen:arc xlink:type="arc" xlink:from="target" xlink:to="label" xlink:arcrole="http://xbrl.org/arcrole/2008/element-label"/>
</gen:link>
<!-- Label for the concept rename event -->
<gen:link xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link">
<link:loc xlink:type="locator" xlink:label="target" xlink:href="PincusRevenueService-VersioningReport-2009-to-2010.xml#evt-2010-debt-rename"/>
<label:label xml:lang="en" xlink:type="resource" xlink:label="label">
Debt concept renaming.
</label:label>
<gen:arc xlink:type="arc" xlink:from="target" xlink:to="label" xlink:arcrole="http://xbrl.org/arcrole/2008/element-label"/>
</gen:link>
</link:linkbase>

This shows the original From DTS for the 2009 taxonomy:

Example 3: Old example taxonomy

<schema
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">
<import namespace="http://www.xbrl.org/2003/instance" schemaLocation="http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd"/>
<element name="Revenue" id="dts_Revenue" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
<element name="Payroll" id="dts_Payroll" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
<element name="Capital" id="dts_Capital" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
<element name="DebtOutstanding" id="dts_DebtOutstanding" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
</schema>

This shows the target To DTS for the 2010 taxonomy:

Example 4: New example taxonomy

<schema
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">
<import namespace="http://www.xbrl.org/2003/instance" schemaLocation="http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd"/>
<element name="Revenue" id="dts_Revenue" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
<element name="Payroll" id="dts_Payroll" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
<element name="Capital" id="dts_Capital" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
<element name="TotalDebt" id="dts_TotalDebt" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="instant"/>
</schema>

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)
Figure 3: Technical change to the dimensional representation of a set of concepts

7 Limitations

Appendix A References

DIMENSIONS
XBRL International Inc.. "XBRL Dimensions 1.0"
Ignacio Hernández-Ros
, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XDT-REC-2006-09-18.htm)
XBRL 2.1
XBRL International Inc.. "Extensible Business Reporting Language (XBRL) 2.1 Includes Corrected Errata Up To 2008-07-02"
Phillip Engel
, Walter Hamscher, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XBRL-RECOMMENDATION-2003-12-31+Corrected-Errata-2008-07-02.htm)
XLINK
W3C (World Wide Web Consortium). "XML Linking Language (XLink) Version 1.0"
Steve DeRose
, Eve Maler, and David Orchard.
(See http://www.w3.org/TR/xlink/)
XML Base
W3C (World Wide Web Consortium). "XML Base"
Johnathan Marsh.

(See http://www.w3.org/TR/xmlbase/)
XML Names
W3C (World Wide Web Consortium). "Namespaces in XML 1.0 (Second Edition)"
Tim Bray
, Dave Hollander, Andrew Layman, and Richard Tobin.
(See http://www.w3.org/TR/REC-xml-names/)
XML Schema Structures
W3C (World Wide Web Consortium). "XML Schema Part 1: Structures Second Edition"
Henry S. Thompson
, David Beech, Murray Maloney, and Noah Mendelsohn.
(See http://www.w3.org/TR/xmlschema-1/)

Appendix B Intellectual property status (non-normative)

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to XBRL International or XBRL organizations, except as required to translate it into languages other than English. Members of XBRL International agree to grant certain licenses under the XBRL International Intellectual Property Policy (www.xbrl.org/legal).

This document and the information contained herein is provided on an "AS IS" basis and XBRL INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

The attention of users of this document is directed to the possibility that compliance with or adoption of XBRL International specifications may require use of an invention covered by patent rights. XBRL International shall not be responsible for identifying patents for which a license may be required by any XBRL International specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. XBRL International specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents. XBRL International takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Members of XBRL International agree to grant certain licenses under the XBRL International Intellectual Property Policy (www.xbrl.org/legal).

Appendix C Acknowledgements (non-normative)

This document could not have been written without the contributions of many people.

Appendix D Document history (non-normative)

DateAuthorDetails
20 June 2010Ian Stokes-Rees

Created primer document from existing base specification.

12 September 2010Herm Fischer

Initial merge of overview material for instance-aspects and dimensional issues of relationship-sets.

23 January 2011Herm Fischer

Updated examples for QName concept identifier and to correct validation issues.

01 February 2011Warwick Foster

Added explanation of Concept Delete.

18 October 2011Hugh Wallis

Various editorial changes to improve clarity and correct grammatical and spelling errors.

Appendix E Errata corrections in this document

This appendix contains a list of the errata that have been incorporated into this document. This represents all those errata corrections that have been approved by the XBRL International Versioning Working Group up to and including 19 October 2011. Hyperlinks to relevant e-mail threads may only be followed by those who have access to the relevant mailing lists. Access to internal XBRL mailing lists is restricted to members of XBRL International Inc.

No errata have been incorporated into this document.