Versioning Specification Requirements
Public Working Draft dated 2007-11-28
Copyright © 2007, XBRL International Inc., All Rights Reserved

This version:
	VERSIONING-REQ-PWD-2007-11-28.rtf
is NORMATIVE. All other versions and formats are NON-NORMATIVE. 
Editors
Sergio Quiroz	sergioquiroz@xbrl.org.es 	XBRL Spain	
Katrin Schmehl	Katrin.Schmehl@bundesbank.de	Deutsche Bundesbank	
Contributors
Paola Maurizi	paola.maurizi@bancaditalia.it 	Banca d’Italia	
Ignacio Hernández-Ros	ignacio@hernandez-ros.com 	Reporting Estandar S.L.	
Camille Dumm	camille.dumm@nbb.be 	National Bank of Belgium	
Eric Jarry	eric@jarrymail.com 	Banque de France	
Jim Richards	jdrassoc@iinet.net.au 	JDR & Associates	

Abstract
This document is the first edition of the XBRL Versioning Specification Requirements as a contribution for Versioning under development by the XBRL Versioning Working Group. This document 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: 
•	Changes on taxonomy level
•	Changes on concept level (items, tuples) 
•	Changes on relations 
•	Changes on resources
•	… 

Status of this document
Circulation of this Public Working Draft is unrestricted. Recipients of this draft are invited to submit comments to the authors and contributors by email, and to submit notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Table of Contents
1	Terminology and Formatting
2	Design Principles
3	Technical Requirements
3.1	General Use Cases
3.1.1	Changes on taxonomy level
3.1.2	Changes on concept level
3.1.3	Changes on relationships
3.1.4	Changes on 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 Versioning Specification
3.3.1	Usage of XBRL software
3.3.2	Requirements on the validation of the versioning report
3.4	Use cases for future considerations
3.4.1	Changes on the taxonomy header
3.4.2	Definition of a validity of a concept
A.	References (non-normative)
B.	Intellectual Property Status (non-normative)
C.	Acknowledgements (non-normative)
D.	Approval process (non-normative)
E.	Document history (non-normative)

1	
Terminology and Formatting
Terminology used in XBRL frequently overlaps with terminology from other fields.  Refer to the XBRL 2.1 Specification [XBRL] for definitions of specific terms. The terminology used in this document is summarised in the following table.
abstract element, bind, concept, concrete element, context, Discoverable Taxonomy Set (DTS), duplicate items, duplicate tuples, element, entity, equal, essence concept, fact, instance, item, least common ancestor, linkbase, period, taxonomy, tuple, unit, taxonomy schema, child, parent, sibling, grandparent, uncle, ancestor, XBRL instance, c-equal, p-equal, s-equal, u-equal, v-equal, x-equal, minimally conforming XBRL processor, fully conforming XBRL processor.	As defined in XBRL 2.1 Specification [XBRL].	
must, must not, required, shall, shall not, should, should not, may, optional	See [RFC2119] for definitions of these and other terms.  These include, in particular:
SHOULD	
Conforming documents and applications are encouraged to behave as described.	

MUST	
Conforming documents and consuming applications are required to behave as described; otherwise they are in error.	

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

The following highlighting is used for non-normative examples in this document:
	
Non-normative editorial comments to be removed from final recommendations are denoted as follows:
XY: This highlighting indicates editorial comments about the current draft, prefixed by the editor’s initials.
Italics are used for rhetorical emphasis only and do not convey any special normative meaning.
2	
Design Principles
ID	PRINCIPLE	MEANING	
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 the most current edition of the XBRL 2.1 specification.	
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 the new taxonomy versions. If something in the design were in conflict between the two groups defined above the point of view that should prevalence 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 the Dimensions Specification 1.0 and the Formula Linkbase Specification.	

3	
Technical Requirements
3.1	General Use Cases 
3.1.1	Changes on taxonomy level 
Changes on taxonomy level MUST be recognized and documented
U1101	New XBRL concept	The adding of a new item [XIS 2.2.8 + XIS 2.2.9] or a new tuple [XIS 2.2.8 + XIS 2.2.10] MUST be documented.	
U1102	Deletion of an XBRL concept	The deletion of an item [XIS 2.2.8 + XIS 2.2.9] or a tuple [XIS 2.2.8 + XIS 2.2.10] MUST be documented.	
3.1.2	Changes on concept level
Changes on concept level for XBRL items as well as tuples should be recognized and documented.
U1201	Change in the QName	If a concept QName [XIS 2.2.3.2 + XIS 2.2.8.2] has changed, this change MUST be documented.	
U1202	Change in the ID attribute value	If an element ID has changed may be to correspond with the element name, this change should NOT be documented. 	
U1203	Change in the substitutionGroup attribute value	A change in the substitutionGroup [XIS 2.2.8.4] MUST be documented.	
U1204	Change in the abstract attribute value	If the abstract attribute value [XIS 2.2.8.6] has changed, this change MUST be documented.	
U1205	Change in the nillable attribute value	If the nillable attribute value [XIS 2.2.8.5] has changed, this change MUST be documented.	
U1206	Change in the type definition	If the type definition [XIS 2.2.8.3] has changed, this change MUST be documented.	
U1207	Change in the periodType attribute value	If the periodType attribute value [XIS 2.2.9.2] has changed, this change MUST be documented.	
U1208	Change in the balance attribute value	If the balance attribute value [XIS 2.2.9.3] has changed, this change MUST be documented.	
U1209	Change in the block attribute value	If the block attribute value [XIS 2.2.8.7] has changed, this change MUST be documented.	
U1210	Change in the default attribute value	If the default attribute value [XIS 2.2.9.4] has changed, this change MUST be documented.	
U1211	Change in the fixed attribute value	If the fixed attribute value [XIS 2.2.8.8] has changed, this change MUST be documented.	
U1212	Change in the final attribute value	If the final attribute value [XIS 2.2.8.9] has changed, this change MUST be documented.	
U1213	Change of a child element	If a new child [XIS 2.2.8.13] has been added, deleted or changed inside a tuple element, this change MUST be documented.	
U1214	Change in additional attributes	Changes on additional attributes [XIS 2.2.8.12] MUST be documented.	
U1215	New relationship	If a new relationship [XIS 2.2.8.10 + XIS 2.2.8.11] has been added to a concept where the concept acts as source or target, this change MUST be documented.	
U1216	Deletion of a relationship	If a relationship [XIS 2.2.8.10 + XIS 2.2.8.11] refering to a concept does no longer exist, this change MUST be documented.	
U1217	New resource	The addition of a new resource [XIS 2.2.15] linked to a concept i.e. a label or a reference MUST be documented.	
U1218	Deletion of a resource	If a resource [XIS 2.2.15] referenced by a concept has been deleted, this change MUST be documented.	
U1219	New attribute 	If an attribute has been added to a concept, this change MUST be documented.	
U1220	Deletion of an attribute	The deletion of an attribute of a concept MUST be documented.	
3.1.3	Changes on relationships
Changes on relationships between XBRL items as well as tuples should be recognized and documented. Relationships are defined by arcs.
U1301	Change in the URI of an extended link role	A change in the URI of an extended link role MUST be documented.	
U1303	Change in the arcrole type	If the arcrole type [XIS 2.2.14.5] has changed, this change MUST be documented.	
U1305	Change in the order attribute value	If the order attribute value [XIS 2.2.14.6] has changed, this change should only be documented when the ordering of the concepts has changed.	
U1306	Change in the highest priority relationship(s)	When the highest priority relationship(s) [XIS 2.2.14.8] has changed, this change MUST be documented. Changes on relationship(s) with lower priority should not be documented.	
U1307	Change in additional attributes	Changes on additional attributes [XIS 2.2.14.9] MUST be documented.	
U1308	Addition of an attribute	If an attribute has been added to a relationship, this change MUST be documented.	
U1309	Deletion of an attribute	The deletion of an attribute of a relationship MUST be documented.	
3.1.4	Changes on resources
Changes on resources like labels that refer to an item or a tuple should be recognized and documented.
U1401	Change in the role attribute	If there is a change in the definition of a role attribute [XIS 2.2.15.3] of a resource, this change MUST be documented.	
U1402	Change of the content of a resource	If the content of a resource [XIS 2.2.15.8] has changed, this change MUST be documented.	
3.1.5	Documentation of changes
Changes on documentations and definitions in plain text should be recognized and listed in a version report.
U1501	Add a 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 a documentation of a group of changes	If changes can be grouped, it should be possible to add documentation for a summary of changes: examples include splitting of concepts, collapsing of concepts etc.	
U1503	Additional information for change documentation	The following information should be possible to include in the change documentation: Error description, change description, found by, severity, change date. It would be preferable to have a structural and extensible documentation.	
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, change that affect automated processing or do not affect automated processing etc. A short list of predefined change categories should be provided but also a possibility to add new categories.	
U1505	No documentation of syntactical changes	If the changes have no semantics so that they are only syntactical, these changes should no be documented. For example a resource like a label moves from one linkbase file to another.	
U1506	Multi-lingual documentation	It should be possible to add documentation on a change in different languages.	
3.1.6	Documentation on the versioning report
Use-case that refers to 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 unrelevant changes are left out. The versioning report should contain information 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 the mapping rules	A version report should also list the mapping rules that are the basis of the generated report.	

3.2	
Specific Use Cases for dimensional taxonomies
Uses cases that contain requirements for taxonomies using XBRL Dimension Specification [DIM].
U1701	Detect equivalent dimensional relationships	If a dimensional relationship has only syntactical changes, these changes should not be reported (i.e. the composition of a hypercube has changed or it is divided but the relationships between primary and dimensional elements are the same).	
U1702	Change on the dimensional representation of a set of concepts	Changes on the dimensional representation of a concept: a concept doesn't change from a business perspective, but it's XBRL dimensional representation does. I.E:
      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 this kind of equivalences so that ETL tools and others would be able to update mappings according to this information	
3.3	
Use Cases for potential future implementations of Versioning Specification
3.3.1	Usage of XBRL software
Use-case that contains requirements to the XBRL software that supports versioning.
U2101	Choose the level of detail	It should be possible to choose if the level of detail as well as not to list unrelevant changes in a versioning report.	
U2102	Creation of a version report	The version report should be created in XBRL syntax 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 including versioning techniques should be able to add documentation on individual changes and group changes in a combined documentation.	
U2104	Process of a versioning report	A versioning report should be technically readable to enable, whenever possible, dynamic processing of the changes.	
U2105	Changes on instances	XBRL software including versioning techniques should support users to take into account the taxonomy changes in corresponding instances.	
U2106	Capture versioning information during development	It should be possible to capture versioning information during the development phase of a taxonomy. XBRL software including versioning techniques should provide a set of services for taxonomy change management.	
U2107	Change report	In case of changes on 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 including versioning techniques should be able to make the 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-case that have special requirements on versioning
U2120	Comparison of extension taxonomies	XBRL software including versioning techniques should be able to compare two different extension taxonomies.	
U2121	Process of extension taxonomies	XBRL software should provide support for taxonomy editors to adopt changes in the base taxonomy.	
3.3.2	Requirements on the validation of the versioning report
For quality reasons and consistency, It must be possible to verify if the versioning report contains comments for the differences found between the two taxonomy versions 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 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 considerations
3.4.1	Changes on the taxonomy header
Changes on the list of entry points should be recognized and documented.
U3101	New entry point	An additional entry point should be documented; for example, 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 on the base taxonomie(s) should be recognized 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 on the base taxonomy	If the changes relate to an extension taxonomy, changes in the base taxonomy itself should not be documented.	
Changes on information in the taxonomy header. 
(The taxonomy header is not yet defined, so the following use-case should be discussed.) 
U3108	Changes on documentary information	The changes in documentary information of the taxonomy header should be documented.	
U3109	Version numbering	It should be possible to add a numbering for the versions.	
U3110	Validity period	The taxonomy header should contain information about the validity period of a taxonomy.	

3.4.2	
Definition of a validity of a concept
Definitions of validities should be possible not only on taxonomy level but also on concept level.
U3201	Add a validity to a concept	It should be possible to define a validity 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”. 

 
A.	
References (non-normative)
[PWDVR]	Sergio Quiroz, Katrin Schmehl
XBRL Versioning Requirements, Draft Public Working Draft, 2007-08-06
http://www.xbrl.org/SpecRequirements/ 
	
[XVS]	Ignacio Hernández-Ros
XBRL Versioning Specification 1.0, Public Working Draft, 2007-11-28
	
[XIS]	Ignacio Hernández-Ros
XBRL Infoset Draft Public Working Draft, 2007-11-28
	
[DIM]	Ignacio Hernández-Ros, Hugh Wallis.
XBRL Dimensions 1.0 Recommendation, 2006-09-18.
http://www.xbrl.org/SpecRecommendations/
	
[RFC2119]	Scott Bradner
Key words for use in RFCs to Indicate Requirement Levels, March 1997
http://www.ietf.org/rfc/rfc2119.txt
	
[XBRL]	Phillip Engel, Walter Hamscher, Geoff Shuetrim, David vun Kannon, Hugh Wallis.
Extensible Business Reporting Language (XBRL) 2.1 Recommendation with corrected errata to 2006-12-18.
http://www.xbrl.org/SpecRecommendations/
	
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).

C.	
Acknowledgements (non-normative)
This document is a result of careful consideration by the participants of the XBRL International Versioning Working Group.  The XBRL International Versioning Working Group is chaired by Paul Warren (DecisionSoft) and vice chaired by Katrin Schmehl (Deutsche Bundesbank).
D.	Approval process (non-normative)
This section will be removed from the final recommendation.
This specification is being developed following the XBRL Technical Working Group Processes: http://www.xbrl.org/XSB/XBRL_Technical_Working_Group_Processes-Approved-2007-04-17.htm
E.	Document history (non-normative)
Date	Editor	Remarks	
2007-08-03	Sergio Quiroz	First draft on basis of the confidential WIKI	
2007-08-13	Katrin Schmehl	Editorial changes, table of content, list of contributors	
2007-08-23	Katrin Schmehl	Deletion of the use-cases 1302, 1304; Update of the references to the XIS (dated 2007-08-07)	
2007-08-28	Katrin Schmehl	Update of references to the XIS (dated 2007-08-07)	
2007-09-14	Katrin Schmehl	Update of the table “Terminology and Formatting’	
2007-10-17	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	
2007-11-19	Katrin Schmehl	The status of the document has been changed from Internal Working Draft to Draft Public Working Draft.	
2007-11-28	Hugh Wallis	Editorial for publication as PWD