Copyright ©2010 XBRL International Inc., All Rights Reserved.
Circulation of this Candidate Recommendation is unrestricted. This document is normative. 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 specification is the base specification in the modular XBRL Versioning Specification. It defines an XML syntax for an XBRL Versioning Report. A Versioning Report can be used by the authors of XBRL taxonomies to provide documentation of the changes between two taxonomies. The base specification primarily defines the framework for Versioning Reports, with the core based on a three-tier hierarchy of Assignments, Actions, and Events which are used in the modular extension specifications. The base specification only defines two types of Event: Namespace Rename and Role Change. Other Event types are defined in the extension specifications.
1 Introduction
1.1 Relationship to other work
1.2 Namespaces and namespace prefixes
1.3 URI resolution
1.4 Language independence
1.5 Document conventions
1.5.1 Typographic conventions
1.5.1.1 Definition notation
1.5.1.2 Footnote notation
1.5.1.3 Element and attribute notation
1.5.2 Formatting conventions
1.6 Terminology
2 Versioning Report Structure
2.1 Versioning Report
2.1.1 XML Representation
2.2 Assignments
2.2.1 XML Representation
2.3 Assignment Categories
2.3.1 Custom Assignment Categories
2.3.2 XML Representation
2.4 Actions
2.4.1 XML Representation
3 Mappings
3.1 Namespace Mappings
3.2 Role Mappings
4 Events
4.1 XML Representation
4.2 Namespace Rename Event
4.2.1 XML Representation
4.3 Role Change Event
4.3.1 XML Representation
5 Identifiers
5.1 URI Reference
5.1.1 XML Representation
5.2 DTS identifiers
5.2.1 XML Representation
5.2.2 Validation Rules
5.2.3 From DTS identifier
5.2.4 To DTS identifier
5.3 Namespace Name Identifier
5.3.1 Validation Rules
5.4 Role Identifier
5.4.1 Validation Rules
6 Labels and References
7 Related Versioning Reports
7.1 Versioning Report References
7.1.1 XML Representation
7.1.2 Validation Rules
A Normative schema
B References
C Intellectual property status (non-normative)
D Acknowledgements (non-normative)
E Document history (non-normative)
F Errata corrections in this document
1 Namespaces and namespace prefixes
2
XML representation summary: ver:report
3
XML representation summary: ver:assignment
4
XML representation summary: ver:category
5
XML representation summary: ver:action
6
XML representation summary: ver:event
7 Base events
8
XML representation summary: ver:namespaceRename
9
XML representation summary: ver:roleChange
10
XML representation summary: ver:fromURI and ver:toURI
11
XML representation summary: ver:dts.identifier
12
XML representation summary: ver:reportRef
1 A normative example
2 A non-normative example
3 An example of poor usage
4 Custom assignment categories
5 Related Versioning Reports
Action
Assignment
Assignment Category
DTS Identifier
Event
From DTS
From DTS Identifier
From Identifier
From Namespace
From Role URI
Identifier
Namespace Mapping
Namespace Name Identifier
Namespace Rename
Related Report
Role Change
Role Mapping
Role URI Identifier
To DTS
To DTS Identifier
To Identifier
To Namespace
To Role URI
URI Reference
Versioning Report
Versioning Report Reference
vere:invalidAssignmentRef
vere:invalidDTSIdentifier
vere:invalidNamespaceMapping
vere:invalidReferencedVersioningReport
vere:invalidRoleChange
vere:invalidXlinkArcrole
vere:invalidXlinkType
vere:missingXlinkArcrole
This specification defines the base syntax and semantics for an XBRL Versioning Report.
This specification depends upon the following XBRL specifications:
In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
Namespace prefixes [XML Names] will be used
for elements and attributes in
the form ns:name where ns is the
namespace prefix and name is the local name.
Throughout this specification, the mappings
from namespace prefixes to actual namespaces is consistent
with
Table
1.
The prefix column in Table 1 is non normative. The namespace URI column is normative.
| Prefix | Namespace URI |
|---|---|
ver
|
http://xbrl.org/2010/versioning-base
|
vere
|
http://xbrl.org/2010/versioning-base/error
|
xs
|
http://www.w3.org/2001/XMLSchema
|
xlink
|
http://www.w3.org/1999/xlink
|
link
|
http://www.xbrl.org/2003/linkbase
|
This specification requires Uniform Resource Identifier (URI) [IETF RFC 3986] resolution to honor xml:base attributes.
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
Comments which are informative, but not essential to the understanding of the point at hand, are provided in footnotes. All footnotes are non-normative.
When referring to a specific element, it will be identified by
its namespace prefix and local name. For example, the root
element for a specification container element would be referred to as
<variable:generalVariable>
.
Attributes are also identified by their local name and, where
appropriate, their namespace prefix. Attributes are
distinguished from elements by prefixing them by an
@
symbol. Thus,
@id
refers to the attribute with the name id.
When referring to any attribute, so long as it has a specific
namespace, the local name is replaced by an asterisk (
*).
Thus, the notation
@xml:* specifies any attribute
in the namespace
http://www.w3.org/XML/1998/namespace.
The following highlighting is used for normative technical material in this document:
Text of the normative example.
The following highlighting is used for non-normative examples in this document:
Text of the helpful example.
Next paragraph of the helpful example.
Example 3 shows the formatting for non-normative examples of poor, discouraged or disallowed usage.
The example itself.
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 key words schema, substitution group, substitution group affiliation, target namespace, element declaration, content model and actual value in this document are to be interpreted as described in the XML Schema Structures Specification [XML Schema Structures].
The key words element, attribute, local name, namespace name and namespace prefix in this document are to be interpreted as described in the XML Names Specification [XML Names].
The key words arc, base set, concept, DTS, fact, instance, item, linkbase, DTS discovery, roleURI, role type definition, taxonomy and taxonomy schema in this document are to be interpreted as described in the XBRL Specification [XBRL 2.1].
The key words label and generic label in this document are to be interpreted as described in the Generic Labels Specification [GENERIC LABELS].
The key words reference and generic reference in this document are to be interpreted as described in the Generic References Specification [GENERIC REFERENCES].
The key word XLink simple link in this document is to be interpreted as described in the XLink Specification [XLINK].
A Versioning Report provides information about the differences between two DTSs, the From DTS and the To DTS, according to the validation rules and schema constraints described in this specification and the associated Versioning Modules. It is comprised of a Versioning Report XML instance document, and a set of referenced linkbases.
A Versioning Report is comprised of the following components:
A Versioning Report is represented by the
<ver:report>
element.
<ver:report
id = Content:
</ver:report>
|
|
| Property | Representation |
|---|---|
| {linkbases} |
The set of linkbases identified by by the
<link:linkbaseRef>
children of the
<ver:report>
element.
|
| {related reports} |
The set of Versioning Reports
identified by the
<ver:reportRef>
children of the
<ver:report>
element.
|
| {from DTS} |
The From DTS Identifier
represented by the
<ver:fromDTS>
child of the
<ver:report>
element.
|
| {to DTS} |
The To DTS Identifier
represented by the
<ver:toDTS>
child of the
<ver:report>
element.
|
| {all assignments} |
The set of all Assignments
represented by the
<ver:assignment>
children of the
<ver:report>
element.
|
| {actions} |
The set of all Actions represented by the
<ver:action>
children of the
<ver:report>
element.
|
An Assignment is a grouping of related Actions.
The grouping of Actions provided by an Assignment allows common documentation (see Section 6) or categorisation (see Section 2.3) to be associated with a set of related Actions .
An Assignment is represented by a
<ver:assignment>
element.
<ver:assignment
id = Content: </ver:assigment>
Any element in the |
|
| Property | Representation |
|---|---|
| {categories} |
The set of Assignment
Categories represented by elements
in the
<ver:category>
substitution
group present as children of the
<ver:assignment>
.
|
The specification provides an extensible mechanism for categorising Assignments. This mechanism MAY be used to group Assignments according to the motivation behind the change.
An Assignment Category is a category that may be associated with an Assignment.
This specification defines three standard Assignment Categories:
| Name | Element | Description |
|---|---|---|
| Business |
<ver:businessCategory>
|
Indicates that the Assignment is intended to bring the taxonomy into closer alignment with current business requirements. |
| Technical |
<ver:technicalCategory>
|
Indicates that the Assignment is driven by technical requirements. |
| Errata |
<ver:errataCategory>
|
Indicates that the Assignment is intended to correct errors in the taxonomy. |
In addition to the three pre-defined Assignment Categories, a Versioning Report MAY use custom categories.
Custom categories are defined by an XML Schema element declaration that has either directly,
or indirectly through a chain of substitution group affiliations, a substitution group of
<ver:category>
. If a custom category has substitution
group that is another category element, it represents a sub-class of that category.
For example, an element declared with a substitution group of
<ver:category>
would
be considered to be a custom Assignment Category that
sits alongside the three predefined categories. An element declared with a substitution
group of
<ver:businessCategory>
would
represent a specific type of business change.
An Assignment Category is represented by an element in
the
<ver:category>
substitution group.
<ver:category
id = Content: none </ver:category>
|
An Action is a grouping of related Events to represent a single, discrete change to the taxonomy.
The group of related Events is used to represent a replacement or renaming relationship, by grouping deleted components in the From DTS with added components in the To DTS. The semantics to be understood from such groupings are defined on the indivdual event types, where applicable.
An Action is represented by a
<ver:action>
element.
<ver:action
id = Content: </ver:action>
|
|
<ver:assignmentRef
ref = xs:IDREF Content: none </ver:assignmentRef>
|
|
| Property | Representation |
|---|---|
| {assignments} |
The set of Assignments identified by the
@ref
attributes of
<ver:assignmentRef>
children of the
<ver:action>
element.
|
| {events} |
The set of Events represented by elements
in the
<ver:event>
substitution group present as children of the
<ver:action>
element.
|
The
@ref attribute of a
<ver:assignmentRef>
element MUST identify
a
<ver:assignment>
element.
Error code vere:invalidAssignmentRef is raised otherwise.
A Namespace Mapping is the association of a From Namespace with a corresponding To Namespace.
A Namespace Mapping is defined by a Namespace Rename Event. A single namespace name MAY be involved in more than one Namespace Mapping.
A Role Mapping is the association of a From Role URI with a corresponding To Role URI.
A Role Mapping is defined by a Role Change Event. A single roleURI MAY be involved in more than one Role Mapping.
An Event is an individual difference between the From DTS and the To DTS , using Identifiers .
Events to represent specific types of difference are defined by this specification and by modular extensions to it. An Event will typically include one or more Identifiers for components in the From DTS or To DTS that are affected by the Event .
An Event is represented by an
element in the
<ver:event>
substitution group . The
<ver:event>
element has an open content model; specific
Events are represented by non-abstract
elements defining specific content models.
<ver:event
id = Content:
</ver:event>
|
This specification defines a number of Events that may be used by all Versioning Reports. These are documented below.
| Code | Element | From Identifier | To Identifier |
|---|---|---|---|
| [NamespaceRename] |
<ver:namespaceRename>
|
Namespace Name Identifier | Namespace Name Identifier |
| [RoleChange] |
<ver:roleChange>
|
Role URI Identifier | Role URI Identifier |
A Namespace Rename Event associates a namespace name in the From DTS with a namespace name in the To DTS via From Namespace and To Namespace identifiers.
A single namespace name MAY be involved in more than one Namespace Mapping.
A Role ChangeEvent associates a roleURI in the From DTS with a roleURI in the To DTS via From Role URI and To Role URI identifiers.
An Identifier identifies a component in either the From DTS or the To DTS.
A From Identifier is an Identifier that identifies a component in the From DTS.
A To Identifier is an Identifier that identifies a component in the To DTS.
Individual Identifier types will specify their own XML representations.
A URI Reference is an abstract Identifier for any URI.
A URI Reference is represented by:
<ver:fromURI>
element, if it
is used as a From Identifier; or
<ver:toURI>
element, if it is
used as a To Identifier.
<ver:fromURI
value = Content: None </ver:fromURI>
|
|
<ver:toURI
value = Content: None </ver:toURI>
|
|
| Property | Representation |
|---|---|
| {URI} |
The actual value of the
@value attribute of the
<ver:fromURI>
or
<ver:toURI>
element.
|
A DTS Identifier is a specific Identifier , consisting of a set of one or more URIs that are the starting point for DTS discovery for the identified DTS .
A DTS Identifier is
represented by an element in the
<ver:dts.identifier>
substitution group.
<ver:dts.identifier
id = Content:
( </ver:dts.identifier>
|
|
| Property | Representation |
|---|---|
| {identified DTS} |
The DTS is that formed by starting DTS discovery from the set of linkbases and
schemas referenced by
<link:linkbaseRef>
and
<link:schemaRef>
elements respectively.
|
The
<link:linkbaseRef>
and
<link:schemaRef>
elements are defined in the XBRL
Specification [XBRL 2.1].
A DTS Identifier MUST identify a DTS that is XBRL valid, according to the rules described in the XBRL Specification [XBRL 2.1]. Error code vere:invalidDTSIdentifier is raised otherwise.
The From DTS is the DTS that forms the base of the Versioning Report. Typically this will be the DTS with lower version number or earlier release date.
A
From DTS Identifier is a DTS
Identifier that identifies the From
DTS.
It is represented by the
<ver:fromDTS>
element . See XML Representation for DTS Identifier .
The To DTS is the DTS that forms the target of the Versioning Report. Typically this will be the DTS with the higher version number or later release date.
A
To DTS Identifier is a DTS
Identifier that identifies the To DTS
.
It is represented by the
<ver:toDTS>
element . See XML Representation for DTS Identifier .
A Namespace Name Identifier is a URI Reference that identifies a Namespace Name.
A From Namespace is a namespace name that is the target namespace of a schema in the From DTS.
A To Namespace is a namespace name that is the target namespace of a schema in the To DTS.
The {URI} property of the URI Reference MUST be equal to the target namespace of a schema in:
Error code vere:invalidNamespaceMapping is raised otherwise.
A Role URI Identifier is a URI Reference that identifies a roleURI.
A From Role URI identifies a roleURI that is defined by a role definition in the From DTS.
A To Role URI identifies a roleURI that is defined by a role definition in the To DTS.
The {URI} property of the URI Reference MUST be equal to the roleURI of a role type definition in:
The specification allows for human-readable documentation to be associated with
both Assignments and Actions . Labels and
references MAY be provided for components in a
Versioning Report using
generic labels and generic references using an XBRL
Linkbase[XLINK]. The linkbases are associated with the Versioning Report by a Linkbase
Reference, represented by the <link:linkbaseRef> child element
of the <ver:report> element.
Labels and References SHOULD be provided for the Versioning Report , and all Assignments and Actions.
A Related Report is a Versioning Report that may be of relevance to the consumer of another Versioning Report.
A Versioning Report MAY include references to Related Versioning Reports. Such references are included as Versioning Report References.
No constraints are placed on the relationship between a Versioning Report and a Related Versioning Reported. In particular, there are no constraints requiring that the From DTS and To DTS coincide, or even that they overlap.
For example, where a Versioning Report is provided for a taxonomy that is an extension of some other taxonomy (the "base taxonomy"), the Versioning Report for the extension taxonomy may reference the Versioning Report of the base taxonomy as a Related Versioning Report
A Versioning Report Reference is an XLink simple link to a Related Versioning Report.
A Versioning Report Reference is represented by
the
<ver:reportRef>
element.
The
<ver:reportRef>
element is an XLink simple
link.
<ver:reportRef
id = Content: none </ver:reportRef>
|
|
| Property | Representation |
|---|---|
| {related versioning report} |
The Versioning Report obtained by resolving the value of the
@xlink:href attribute. Relative URLs are resolved as specified by XML Base [XML Base].
|
The
@xlink:type attribute MUST have a value of "simple".
Error code vere:invalidXlinkType is raised otherwise.
All {related versioning reports} MUST be a valid Versioning Report, as defined by this specification. If they are resolved and are found to be invlaid, Error code vere:invalidReferencedVersioningReport is raised.
The
@xlink:arcrole attribute MUST be present.
Error code vere:missingXlinkArcrole is raised otherwise.
The
@xlink:arcrole attribute MUST have the
value "http://xbrl.org/arcrole/2010/versioning/related-report"
Error code vere:invalidXlinkArcrole is raised otherwise.
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 including the participants in the Versioning Working Group.
| Date | Author | Details |
|---|---|---|
| 06 October 2009 | Roland Hommes |
Merged PWD-2009-05-27 on Context and Syntax into one document, and split the result into modules, this being the 'base' module which enables Versioning Report containers but without events. |
| 22 October 2009 | Roland Hommes |
Updates as per comments from Fujitsu's Suguru Washio: URI resolution of the DTS is no longer supporting entrance through an instance.
'Complete' Versioning Reports explained, extra text to support |
| 28 October 2009 | Roland Hommes |
Updates as per comments from Haiko Philipp. Definitions: categories tag assignments (not events). Made reference to other modules when validating the Versioning Report. |
| 24 November 2009 | Paul Warren |
Updates based on comments from Dan Bromley: Introduced definitions for "paired namespace" and "paired role URI". Various formatting and wording changes. |
| 31 January 2010 | Roland Hommes |
Updates based on comments from Walter Hamscher, 6 discussion items remain listed as comment in this document. |
| 25 February 2010 | Paul Warren |
Deleted unused definitions of Paired Namespace and Paired Role URI. |
| 04 March 2010 | Paul Warren |
Substantial editorial review. More precise specification of Related Report References. Re-cast role and namespace mappings as events for consistency. |
| 04 March 2010 | Paul Warren |
Renamed F-DTS and T-DTS to From DTS and To DTS, respectively. Renamed fromDts and toDts elements to fromDTS and toDTS, respectively. |
| 04 March 2010 | Paul Warren |
Renamed aTag to actionRef. |
| 04 March 2010 | Paul Warren |
Consolidated Assignment Categories text. |
| 05 March 2010 | Paul Warren |
Removed cTag element, replaced with direct use of category elements. Added XML Representation for ver:report. |
| 05 March 2010 | Paul Warren |
Minor editorial changes. |
| 05 March 2010 | Paul Warren |
Combined ver:revision and ver:event into ver:event. Other minor editorial changes. |
| 10 March 2010 | Hugh Wallis |
Editorial for Candidate Recommendation |
| 23 April 2010 | Hugh Wallis |
Incorporation of comments from Suguru Washio, including rename of actionRef to assignmentRef, and update to versioning-label and versioning-reference arc role URIs. |
| 17 May 2010 | Ian Stokes-Rees |
Several schema corrections and updates, and corrections to specification text to make consistent with schema. These primarily corresponded to content model corrections for the addition of @id attributes or cardinality corrections. |
| 20 June 2010 | Ian Stokes-Rees |
Removed much of the introductory material into a non-normative Primer. Changed cardinality rules for content model of Action. Removed duplicate property definitions. Simplified text and removed unnecessary tables, text, examples, and headings. Re-ordered content to flow from most to least important concepts, including folding specific concrete identifiers into the various sections where they are actually used, and merging "Mappings" into the "Events" section. Added error codes for all MUST statements. |
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 31 July 2010. Hyperlinks to relevant e-mail threads may only be followed by those who have access to the relevant mailing lists. Access to internal XBRL mailing lists is restricted to members of XBRL International Inc.
No errata have been incorporated into this document.