Versioning Specification Requirements
Public Working Draft dated 2007-11-28
Copyright © 2007,
XBRL International Inc., All Rights Reserved
VERSIONING-REQ-PWD-2007-11-28.htm
is NON-NORMATIVE. The NORMATIVE version is in
the file VERSIONING-REQ-PWD-2007-11-28.rtf.
|
Sergio Quiroz |
XBRL |
|
|
Katrin Schmehl |
Deutsche Bundesbank |
Contributors
|
Paola
Maurizi |
Banca
d’Italia |
|
|
Ignacio
Hernández-Ros |
Reporting
Estandar S.L. |
|
|
Camille
Dumm |
National
Bank of |
|
|
Eric
Jarry |
Banque
de France |
|
|
Jim
Richards |
JDR
& Associates |
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:
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.
3.1.1 Changes
on taxonomy level
3.1.2 Changes
on concept level
3.1.3 Changes
on relationships
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.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
B. Intellectual Property Status
(non-normative)
C. Acknowledgements (non-normative)
D. Approval process (non-normative)
E. Document history (non-normative)
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:
|
||||
|
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.
|
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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 |
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. |
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. |
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. |
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”. |
|
Sergio Quiroz, Katrin Schmehl |
|
|
[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. |
|
Scott Bradner |
|
|
Phillip Engel, Walter Hamscher, Geoff
Shuetrim, David vun Kannon, Hugh Wallis. |
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 |