Versioning Specification Requirements 1.0

Public Working Draft 17 March 2010

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

This version:
<http://www.xbrl.org/REQ/versioning-requirements/PWD-2010-03-17/versioning-requirements-REQ-PWD-2010-03-17.html>
Editors:
Katrin Schmehl , Deutsche Bundesbank <Katrin.Schmehl@bundesbank.de>
Hugh Wallis, XBRL International Inc. <hughwallis@xbrl.org>
Contributors:
Paola Maurizi, Banca d’Italia <paola.maurizi@bancaditalia.it >
Ignacio Hernández-Ros, Reporting Estandar S.L. <ignacio@hernandez-ros.com>
Roland Hommes, NTCA <r.hommes@belastingdienst.nl>
Camille Dümm, National Bank of Belgium <camille.dumm@nbb.be>
Eric Jarry, Banque de France <eric@jarrymail.com>
Sergio Quiróz, XBRL Spain <sergioquiroz@xbrl.org.es>
Jim Richards, JDR & Associates <jdrassoc@iinet.net.au>
Paul Warren, CoreFiling Ltd. <pdw@corefiling.com>

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 document details the Requirements for the Versioning Report Specification. It describes the use-cases that are recognized as important to be documented in the versioning of an XBRL taxonomy as well as a taxonomy framework that contains a set of independent taxonomies as entry points.

The members of the XBRL Versioning WG have a common view that metadata for an XBRL taxonomy as well as for a modular set of an XBRL framework for the definition of the entry point(s) is useful. As long there is no specification for metadata that contains the summary information of XBRL taxonomies, this document uses the term taxonomy header. This taxonomy header should give information about the entry point(s) as well as a possible set of underlying base taxonomies; IFRS, COREP etc.

The use-cases that describe the changes in an XBRL taxonomy or an XBRL framework that should be documented in a versioning report will be categorized as follows:


Comment

1 Paul Warren:The wording of this requirement is under review.

Table of Contents

1 Introduction
1.1 Background
1.2 Language independence
1.3 Terminology
2 Design Principles
3 Technical Requirements
3.1 General Use Cases
3.1.1 Changes at the taxonomy level
3.1.2 Changes at the concept level
3.1.3 Changes to relationships
3.1.4 Changes to resources
3.1.5 Documentation of changes
3.1.6 Documentation on the versioning report
3.2 Specific Use Cases for Dimensional Taxonomies
3.3 Use Cases for potential future implementations of the Versioning Specification
3.3.1 Usage of XBRL software
3.3.2 Validation of the versioning report
3.4 Use cases for future consideration
3.4.1 Changes to the taxonomy header
3.4.2 Definition of the validity of a concept
4 Mapping between requirements and Versioning modules

Appendices

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

Tables

1 Design Principles
2 Changes at the taxonomy level
3 Changes at the concept level
4 Changes to relationships
5 Changes to resources
6 Documentation of changes
7 Documentation on the versioning report
8 Specific Use Cases for Dimensional Taxonomies
9 Usage of XBRL software
10 Use cases that have special requirements for versioning
11 Validation of the versioning report
12 Changes to the list of entry points
13 Changes to base taxonomie(s)
14 Changes to information in the taxonomy header
15 Definition of the validity of a concept

Figure

1 Mapping between the requirements and the Versioning modules

Definition

Taxonomy

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.
P2No Redundancy The solution should not require instances, schemas or linkbases to encode the same information in multiple places.
P3Simplicity The solution must not include features for which there is no documented need.
P4Priority An implementation of these requirements must not violate [XBRL 2.1].
P5Usability 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.
P6Compatibility 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.
U1102Deletion 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
U1201Change 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.
U1206Change 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.
U1214Change 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.
U1215New 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.
U1216Deletion of a relationship The syntax of the Versioning Report MUST support documentation of any removal of a relationship referring to a concept.
U1217New 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.
U1218Deletion 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.
U1303Change 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).
U1307Change 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.
U1403Change 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
U1501Add 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".
U1504Add 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.
U1506Multi-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.
U1602Information about compatibility It SHOULD be possible to add information about the backward and forward compatibility of the old and new version of a taxonomy.
U1603Additional 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.
U1705 Change to the typedDomainRef element The syntax of the Versioning Report MUST support documentation of any change to the typedDomainRef element.
U1706 Change in the @closed attribute value The syntax of the Versioning Report MUST support documentation of any change in the @closed attribute value on has-hypercube networks.
U1707 Change in the @contextElement attribute value The syntax of the Versioning Report MUST support documentation of any change in the @contextElement attribute value on has-hypercube networks.
U1708 Change in the @usable attribute value The syntax of the Versioning Report MUST support documentation of any change in the @usable attribute value on has-hypercube networks.
U1709 Change in the definition of the default dimension The syntax of the Versioning Report MUST support documentation of any change in the definition of the default dimension.

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
U2101Choose 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.
U2102Creation 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.
U2103Change documentation XBRL software that includes versioning SHOULD be able to add documentation on both individual changes and grouped changes in a combined manner.
U2104Processing a versioning report A versioning report SHOULD be technically readable to enable, whenever possible, dynamic processing of the changes.
U2105Changes 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.
U2107Change 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.[Paul Warren: The wording of this requirement is under review.]
U2109Impact 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.
U2121Process 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
U3101New entry point An additional entry point SHOULD be documented; for example, when a new taxonomy has been added to the XBRL framework.
U3102Entry 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)
U3104New base taxonomy An additional base taxonomy SHOULD be documented.
U3105Base 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.
U3107Changes 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.
U3109Version numbering It SHOULD be possible to add a numbering for versions.
U3110Validity 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.
U3202Define 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".

4 Mapping between requirements and Versioning modules

Figure 1 shows how the requirements are mapped to the different modules of the XBRL Versioning Specification.

Figure 1: Mapping between the requirements and the Versioning modules
Mapping between requirements and modules

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)

DateAuthorDetails
03 August 2007Sergio Quiróz

First draft on basis of the confidential WIKI

13 August 2007Katrin Schmehl

Editorial changes, table of content, list of contributors

23 August 2007Katrin Schmehl

Deletion of the use-cases 1302, 1304; Update of the references to the XIS (dated 2007-08-07)

28 August 2007Katrin Schmehl

Update of references to the XIS (dated 2007-08-07)

14 September 2007Katrin Schmehl

Update of the table “Terminology and Formatting’

17 October 2007Katrin 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 2007Katrin Schmehl

The status of the document has been changed from Internal Working Draft to Draft Public Working Draft.

28 November 2007Hugh Wallis

Editorial for publication as PWD

05 March 2008Katrin Schmehl

The use case U1606 has been added.

21 July 2008Hugh Wallis

Converted to S4S format

Changed to WGWD for review by the WG

Various editorial changes and comments inserted

31 July 2008Hugh Wallis

Changed markup for principles and requirements to make them referenceable

29 September 2008Hugh 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 2008Hugh Wallis

Editorial for publication

19 May 2009Roland Hommes

Incorporated requirement 1403 as agreed to by the working group at the 2009-05-19 teleconference.

27 May 2009Hugh Wallis

Editorial for publication as 4th PWD.

03 March 2010Katrin Schmehl

The use cases U1705 to U1709 have been added to reflect the additional dimensional requirements.

10 March 2010Hugh Wallis

Editorial for Candidate Recommendation

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 17 March 2010. 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.