1 Introduction

This document describes the requirements for a versioning report.

1.1 Background

A number of projects have made significant contributions to this specification. These include the IASC Foundation which has contributed a methodology on which this specification is based, and the National Taxonomy Project ("NTP") initiated by the Dutch government, which has contributed the first initial documentation of a standardisation for a Versioning report. Several other initiatives such as the Committee of European Banking Supervisors have joined efforts together in order to help the XBRL Consortium and the XBRL industry to adopt a single common solution that satisfies the most critical business requirements in all those projects.

1.2 Language independence

The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.

1.3 Terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, in this specification, are to be interpreted as described in [IETF RFC 2119].

The word taxonomy refers to an XBRL taxonomy as it is defined in [XBRL 2.1]. For the purposes of this document a taxonomy represents the whole DTS rooted at that taxonomy schema file.

2 Design Principles

Table 1: Design Principles

Identifier	Principle	Explanation
P1	Consistency	XBRL concepts and terminology should be used to describe the solution. In particular, versioning components should be described using XBRL related technologies as taxonomies, linkbases, XLink, XML Schema and others.
P2	No Redundancy	The solution should not require instances, schemas or linkbases to encode the same information in multiple places.
P3	Simplicity	The solution must not include features for which there is no documented need.
P4	Priority	An implementation of these requirements must not violate [XBRL 2.1].
P5	Usability	It must be possible to implement the solution in software in a user friendly manner for both the taxonomy authors who want to create new versions of their taxonomies and for instance document authors who must adapt their systems to produce documents according to new taxonomy versions. If something in the design were in conflict between the two groups defined above the point of view that should prevail is the one that gives more simplicity to the instance document authors.
P6	Compatibility	The solution SHOULD be compatible with current XBRL Taxonomies and Taxonomies that are using XBRL modules that are based on XBRL technology, such as [DIMENSIONS] and [FORMULA].

3 Technical Requirements

3.1 General Use Cases

3.1.1 Changes at the taxonomy level

Changes at the taxonomy level MUST be recognised and documented.

Table 2: Changes at the taxonomy level

U1101	New XBRL concept	The syntax of the Versioning Report MUST support documentation of the addition of a new item or a new tuple.
U1102	Deletion of an XBRL concept	The deletion of an item or a tuple MUST be documented.

3.1.2 Changes at the concept level

The syntax of the Versioning Report MUST support documentation of changes at the concept level for XBRL items as well as tuples.

Table 3: Changes at the concept level

U1201	Change in the QName	The syntax of the Versioning Report MUST support documentation of any change in a concept QName has changed.
U1202	Change in the `@id` attribute value	If an element ID has changed (maybe to correspond with the element name), this change MUST NOT be documented.
U1203	Change in the `@substitutionGroup` attribute value	The syntax of the Versioning Report MUST support documentation of a change in the `@substitutionGroup`.
U1204	Change in the `@abstract` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@abstract` attribute value.
U1205	Change in the `@nillable` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@nillable` attribute value.
U1206	Change in the type definition	The syntax of the Versioning Report MUST support documentation of of any change in the type definition.
U1207	Change in the `@periodType` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@periodType` attribute value.
U1208	Change in the `@balance` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@balance` attribute value.
U1209	Change in the `@block` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@block` attribute value.
U1210	Change in the `@default` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@default` attribute value.
U1211	Change in the `@fixed` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@fixed` attribute value.
U1212	Change in the `@final` attribute value	The syntax of the Versioning Report MUST support documentation of any change in the `@final` attribute value.
U1213	Change of child element of a tuple	The syntax of the Versioning Report MUST support documentation of any change, deletion or addition of a child of a tuple.
U1214	Change in additional attributes	The syntax of the Versioning Report MUST support documentation of any change in additional attributes. This includes addition and deletion of such attributes.
U1215	New relationship	The syntax of the Versioning Report MUST support documentation of any addition of a new relationship to a concept where the concept acts as source or target.
U1216	Deletion of a relationship	The syntax of the Versioning Report MUST support documentation of any removal of a relationship referring to a concept.
U1217	New resource	The syntax of the Versioning Report MUST support documentation of any addition of a new resource linked to a concept i.e. a label or a reference.
U1218	Deletion of a resource	The syntax of the Versioning Report MUST support documentation of any deletion of a resource referenced by a concept.

3.1.3 Changes to relationships

Changes to relationships between XBRL items as well as tuples should be recognised and documented. Relationships are defined by arcs.

Table 4: Changes to relationships

U1301	Change in the URI of an extended link role	The syntax of the Versioning Report MUST support documentation of any change in the URI of an extended link role.
U1303	Change in the arcrole type	The syntax of the Versioning Report MUST support documentation of any change in the arcrole type.
U1305	Change in the order of relationships	The syntax of the Versioning Report MUST support documentation of any change in the order of relationships.
U1306	Change in the highest priority relationship(s)	The syntax of the Versioning Report MUST support documentation of any change in the highest priority relationship(s). Changes to relationship(s) with lower priority SHOULD NOT be documented (because they have no semantic effect).
U1307	Change in additional attributes	The syntax of the Versioning Report MUST support documentation of any change in additional attributes. This includes addition and deletion of such attributes.

3.1.4 Changes to resources

Changes to resources such as labels that refer to an item or a tuple should be recognised and documented as follow:.

Table 5: Changes to resources

U1401	Change in the `@role` attribute	The syntax of the Versioning Report MUST support documentation of any change in a `@role` attribute of a resource.
U1402	Change in the content of a resource	The syntax of the Versioning Report MUST support documentation of any change in the content of a resource.
U1403	Change in additional attributes	The syntax of the Versioning Report MUST support documentation of any change in additional attributes. This includes addition and deletion of such attributes.

3.1.5 Documentation of changes

Changes in documentations and definitions in plain text should be recognised and listed in a versioning report.

Table 6: Documentation of changes

U1501	Add documentation for a change	If an addition, deletion or a change has been made, the taxonomy editor SHOULD be able to add an explanation for this change.
U1502	Add documentation of a group of changes	If changes can be grouped, it SHOULD be possible to add documentation for such a group of changes: examples include splitting of concepts, collapsing of concepts etc.
U1503	Additional information for change documentation	It SHOULD be possible to include the following information in the change documentation: error description, change description, found by, severity, change date. It would be preferable to have a structural and extensible documentation. For example in some projects there is a special structure for the change defintion: one short and one more explanatory including "found by", "severity" and "date".
U1504	Add a change category	It SHOULD be possible to add a change category to distinguish if a change is due to an error, a new requirement, is a change that affects automated processing or does not affect automated processing etc. A short list of predefined change categories should be provided but also the possibility to add new categories.
U1505	No documentation of syntactical changes	If a change has no semantic effect, in other words it is purely syntactic, it MUST NOT be documented. For example a resource such as a label moving from one linkbase file to another.
U1506	Multi-lingual documentation	It SHOULD be possible to add documentation of a change in different languages.

3.1.6 Documentation on the versioning report

Requirements on the versioning report itself

Table 7: Documentation on the versioning report

U1601	Give information about the completeness of a versioning report	If a versioning report contains only a limited number of changes because irrelevant changes are left out, the versioning report SHOULD identify that not all changes are listed.
U1602	Information about compatibility	It SHOULD be possible to add information about the backward and forward compatibility of the old and new version of a taxonomy.
U1603	Additional metadata	It SHOULD be possible to add metadata to document who created the versioning report, including additional contact information.
U1604	Add information about the versioning strategy	It SHOULD be possible to add information about the versioning strategy.
U1605	Give information about mapping rules	A version report SHOULD list the mapping rules that are the basis of the generated report.
U1606	Add information about versioning reports of imported taxonomies of third parties	It SHOULD be possible to list versioning reports from third parties when their taxonomies are applicable to the consecutive versions of the DTS and the changes of those imported taxonomies are not listed in the versioning container itself. i.e. the DTS creator decides not to report changes that refer to an external DTS but to add a reference to the versioning report of this external DTS. A possible interpretation is that this would include referencing externally created reports that are not necessarily in the XBRL defined format. This last aspect of the requirement is "at risk" since it is not certain yet whether this is a real use case.

3.2 Specific Use Cases for Dimensional Taxonomies

Use cases that contain requirements for taxonomies using [DIMENSIONS] .

Table 8: Specific Use Cases for Dimensional Taxonomies

U1701	Detect equivalent dimensional relationships	If a dimensional relationship has only syntactic changes, these changes MUST NOT be reported (e.g.. the composition of a hypercube has changed or it is divided but the relationships between primary and dimensional elements are the same).
U1702	Change to the dimensional representation of a set of concepts	Changes to the dimensional representation of a concept i.e. a concept doesn't change from a business perspective, but its XBRL dimensional representation does. e.g. Version 1 Version 2 A <==> X ( D = d1 ) B <==> X ( D = d2 ) C <==> X ( D = d3 ) Where A, B, C and X are primary items, D is a dimension and d1, d2 and d3 are domain members of a dimension. It SHOULD be possible to express these kind of equivalences so that ETL tools and others would be able to update mappings according to this information
U1703	Change to the dimensional structure of a primary element	The syntax of the Versioning Report SHOULD support documentation on changes to the dimensional structure of a concept, i.e. the addition or deletion of a dimension.
U1704	Change to the domain of a dimension	The syntax of the Versioning Report SHOULD support documentation on changes to the domain of a dimension, i.e. a domain member has been added or deleted.

3.3 Use Cases for potential future implementations of the Versioning Specification

3.3.1 Usage of XBRL software

Use cases that contain requirements applicable to the XBRL software that supports versioning. The following use cases are not addressed by the Versioning Specification. They are applicable to XBRL software

Table 9: Usage of XBRL software

U2101	Choose the level of detail	It SHOULD be possible to choose the level of detail as well as to not list irrelevant changes in a versioning report.
U2102	Creation of a version report	The versioning report MUST be created in a syntax defined by the XBRL Consortium as well as in a human readable form ( i.e. HTML). It should be also possible to extract business-oriented changes for an excerpt report addressed to business people.
U2103	Change documentation	XBRL software that includes versioning SHOULD be able to add documentation on both individual changes and grouped changes in a combined manner.
U2104	Processing a versioning report	A versioning report SHOULD be technically readable to enable, whenever possible, dynamic processing of the changes.
U2105	Changes to instances	XBRL software that provides support for versioning SHOULD be able to report how changes in a taxonomy affect instances based on that taxonomy.
U2106	Capture versioning information during development	It SHOULD be possible to capture versioning information during the development phase of a taxonomy. XBRL software that includes versioning should provide a set of services for taxonomy change management.
U2107	Change report	In the case of changes to existing elements and attributes, the versioning report SHOULD show the old and the new value.
U2108	Business-oriented versioning report	It SHOULD be possible to create a human readable versioning report oriented to business people, for example, based on the change category. It should not include technical changes and not present the changes in an IT-based reporting language like HTML.
U2109	Impact analysis	XBRL software that includes versioning SHOULD be able to make an impact analysis on calculation linkbase, dimensional relationships, formula linkbase (in the future). It should be possible to infer that a change on a concept in a new version has a potential impact on every concept that depends on the changed one.

Use cases that have special requirements for versioning

Table 10: Use cases that have special requirements for versioning

U2120	Comparison of extension taxonomies	XBRL software that includes versioning SHOULD be able to compare two different extension taxonomies.
U2121	Process of extension taxonomies	XBRL software that includes versioning SHOULD provide support for taxonomy editors to adopt changes in the base taxonomy.

3.3.2 Validation of the versioning report

For quality reasons and consistency, it MUST be possible to verify whether the versioning report contains comments for the differences found between the two taxonomy versions about which the versioning report has been created.

Table 11: Validation of the versioning report

U2201

It MUST be possible to assert that a versioning report is complete, and to validate this assertion.

It is important that a versioning report documents all relevant changes. In some cases this will correspond to all the changes in a DTS being documented. In other cases, just a subset will be documented. Where all changes in the DTS are being documented, it would be useful to assert that this is the case so that the completeness of the report can be verified by third parties.

3.4 Use cases for future consideration

3.4.1 Changes to the taxonomy header

Changes to the list of entry points should be recognised and documented

Table 12: Changes to the list of entry points

U3101	New entry point	An additional entry point SHOULD be documented; for example, when a new taxonomy has been added to the XBRL framework.
U3102	Entry point removed	If an entry point has been removed by the taxonomy editor, this change SHOULD be documented.
U3103	Changes in the URI of entry points	If the URI has changed, this change SHOULD be documented.

Changes to base taxonomie(s) should be recognised and documented.

Table 13: Changes to base taxonomie(s)

U3104	New base taxonomy	An additional base taxonomy SHOULD be documented.
U3105	Base taxonomy removed	The deletion of a referenced base taxonomy SHOULD be documented.
U3106	Changes to the URI of the base taxonomy	If the URI has changed (for example, because of a new version that is now used), this change SHOULD be documented.
U3107	Changes to the base taxonomy	If the changes relate to an extension taxonomy, changes in the base taxonomy itself SHOULD not be documented.

Changes to information in the taxonomy header. (The term taxonomy header is not yet defined, so the following use-case should be discussed.)

Table 14: Changes to information in the taxonomy header

U3108	Changes to documentary information	Changes to documentary information in the taxonomy header SHOULD be documented.
U3109	Version numbering	It SHOULD be possible to add a numbering for versions.
U3110	Validity period	The taxonomy header SHOULD contain information about the validity period of a taxonomy.

3.4.2 Definition of the validity of a concept

Definitions of validities SHOULD be possible not only on taxonomy level but also on concept level.

Table 15: Definition of the validity of a concept

U3201	Add a validity period to a concept	It SHOULD be possible to define a validity period for a concept and to validate this restriction.
U3202	Define a dynamic change	It SHOULD be possible to define that changes have a dynamic character and might be valid only for a special period. Explanation: A new version of the taxonomy should be published each time a new requirement has to be included or a "bugs fixing" is needed. If some concepts included in the taxonomy are very changeable (e.g. securities or vital statistics about geography or people), a very frequent update of the taxonomy is needed. Usually regulators do not publish a new version each time "something" has changed, but only with a view to the whole business process, so the validity period of the new version is related to the business scope. This would mean that the information about the actual "life" of dynamic concepts are, usually, lost. In fact, it is possible to assume that: When the concept is included in the new version, then its existence validity is equal to the version validity period. When the concept is not included in the new version, then its "death" agrees with the end-date of the previous version validity period. In both cases, this may be not true for dynamic concepts. Because of it’s important to collect facts considering exactly the "existence" of the related concepts (think about "multidimensional data") so it’s important to properly document dynamic "real world changes".

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)
FORMULA: XBRL International Inc.. "Formula 1.0"
Phillip Engel, Herm Fischer, Victor Morilla, Jim Richards, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
(See http://www.xbrl.org/Specification/formula/PR-2009-03-31/formula-PR-2009-03-31.html)
IETF RFC 2119: IETF (Internet Engineering Task Force). "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels"
Scott Bradner.
(See http://www.ietf.org/rfc/rfc2119.txt)
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)

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 including the participants in the Versioning Working Group.

Appendix D Document history (non-normative)

Date	Author	Details
03 August 2007	Sergio Quiróz	First draft on basis of the confidential WIKI
13 August 2007	Katrin Schmehl	Editorial changes, table of content, list of contributors
23 August 2007	Katrin Schmehl	Deletion of the use-cases 1302, 1304; Update of the references to the XIS (dated 2007-08-07)
28 August 2007	Katrin Schmehl	Update of references to the XIS (dated 2007-08-07)
14 September 2007	Katrin Schmehl	Update of the table “Terminology and Formatting’
17 October 2007	Katrin Schmehl	The use cases U1219, U1220, U1308 and U1309 have been added to reflect additions and deletions of attributes on concepts and relationships. Addition of the dimensional use-case U3302 defined by Victor Morilla
19 November 2007	Katrin Schmehl	The status of the document has been changed from Internal Working Draft to Draft Public Working Draft.
28 November 2007	Hugh Wallis	Editorial for publication as PWD
05 March 2008	Katrin Schmehl	The use case U1606 has been added.
21 July 2008	Hugh Wallis	Converted to S4S format Changed to WGWD for review by the WG Various editorial changes and comments inserted
31 July 2008	Hugh Wallis	Changed markup for principles and requirements to make them referenceable
29 September 2008	Hugh Wallis	Incorporated updates agreed to by the working group at the 2008-08-14 face to face meeting as well as in conference calls thereafter
10 December 2008	Hugh Wallis	Editorial for publication
19 May 2009	Roland Hommes	Incorporated requirement 1403 as agreed to by the working group at the 2009-05-19 teleconference.
27 May 2009	Hugh Wallis	Editorial for publication as 4th PWD.

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 27 May 2009. 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.

Versioning Specification Requirements 1.0

Public Working Draft 27 May 2009

Status

Abstract

Table of Contents

Appendices

Tables

Definitions