Copyright ©2011 XBRL International Inc., All Rights Reserved.
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.
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:
1 Paul Warren:The wording of this requirement is under review.
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
A References
B Intellectual property status (non-normative)
C Acknowledgements (non-normative)
D Document history (non-normative)
E Errata corrections in this document
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
1 Mapping between the requirements and the Versioning modules
This document describes the requirements for a versioning report.
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.
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
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.
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]. |
Changes at the taxonomy level MUST be recognised
and documented.
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. |
U1103 | Deletion of a duplicated XBRL concept | The deletion of a duplicated item or tuple MUST be documented. |
The syntax of the Versioning Report MUST support documentation of changes at the concept level for XBRL items as well as tuples.
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. |
Changes to relationships between XBRL items as well as tuples should be recognised and documented. Relationships are defined by arcs.
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. |
Changes to resources such as labels that refer to an item or a tuple should be recognised and documented as follow:.
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. |
Changes in documentations and definitions in plain text should be recognised and listed in a versioning report.
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:
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. |
Requirements on the versioning report
itself
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. |
Use cases that contain requirements for taxonomies using [DIMENSIONS] .
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. |
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
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.[Paul Warren: The wording of this requirement is under review.] |
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
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. |
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.
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. |
Changes to the list of entry points should be recognised and documented.
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.
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.)
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. |
Definitions of validities SHOULD be possible not only on taxonomy level but also on concept level.
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". |
Figure 1 shows how the requirements are mapped to the different modules of the XBRL Versioning Specification.
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).
This document could not have been written without the contributions of many people.
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. |
03 March 2010 | Katrin Schmehl |
The use cases U1705 to U1709 have been added to reflect the additional dimensional requirements. |
10 March 2010 | Hugh Wallis |
Editorial for Candidate Recommendation |
28 April 2011 | Haiko Philipp |
The use case U1103 has been added to reflect the removal of duplicated concepts. |
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 11 May 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.