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.htm

is NON-NORMATIVE. The NORMATIVE version is in the file VERSIONING-REQ-PWD-2007-11-28.rtf.

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. 4

2      Design Principles. 5

3      Technical Requirements. 6

3.1       General Use Cases. 6

3.1.1      Changes on taxonomy level 6

3.1.2      Changes on concept level 6

3.1.3      Changes on relationships. 7

3.1.4      Changes on resources. 7

3.1.5      Documentation of changes. 7

3.1.6      Documentation on the versioning report 8

3.2       Specific use cases for dimensional taxonomies. 9

3.3       Use Cases for potential future implementations of Versioning Specification. 10

3.3.1      Usage of XBRL software. 10

3.3.2      Requirements on the validation of the versioning report 11

3.4       Use cases for future considerations. 11

3.4.1      Changes on the taxonomy header 11

3.4.2      Definition of a validity of a concept 12

A.         References (non-normative) 13

B.         Intellectual Property Status (non-normative) 13

C.         Acknowledgements (non-normative) 14

D.         Approval process (non-normative) 14

E.         Document history (non-normative) 14

 

 

 

 

 

 

 

 

 

 

 

 

 


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