1 Introduction
XBRL [XBRL 2.1] enables the capture of structured meta-data for a particular reporting scenario in the form of an XBRL taxonomy. Taxonomies are rarely static objects, and will need to be updated periodically for a range of reasons, including changes in the business requirements upon which they are built (for example, a change to an accounting standard), changes is the technical design of the taxonomy, or simple error corrections. When a new version of a taxonomy is released, this has an impact on all users of the taxonomy, including:
- Instance document creators, and developers of instance creation software;
- Creators of taxonomies that extend the taxonomy in question, and developers of extension taxonomy creation software; and
- Instance document consumers, who wish to be able to compare instance documents prepared against the different taxonomy versions.
This specification defines an XML syntax for an XBRL Versioning Report that is designed to allow taxonomy creators to communicate information about the changes between two taxonomy versions in a structured format that will minimise the impact of the update on the users of the taxonomy.
A Versioning Report is distinct from a simple difference report in that a Versioning Report includes information that cannot be obtained from an automated comparison of the DTS such as identifying concepts with different names in the two DTSs that are equivalent, and communicating information about the motivation behind changes. It is this ability to communicate additional information that yields value in creating a standardised Versioning Report .
It should be noted that whilst the primary use case considered in the creation of this specification is the provision of versioning information between two versions of the same taxonomy, the specification makes no assumptions about the relationship between taxonomies involved, and a Versioning Report can be prepared for any pair of DTSs.
1.1 Modularity
The XBRL Versioning Specification, of which this specification is a part, is a modular specification designed to allow the author of a Versioning Report to select the level of detail at which changes are documented. The modular approach allows for versioning information on extensions to the XBRL Specification [XBRL 2.1], such as the XBRL Dimensions Specification [DIMENSIONS], to be addressed as extension modules.
This specification is the base specification, and defines the base syntax that will be used by all Versioning Reports. It is expected that all Versioning Reports will use at least one module in addition to this specification.
1.2 Background
Versioning is a term with several meanings. Different people have different interpretations of this term. XBRL Versioning is about standardising the content of a report of "information about the changes made to a DTS" in order for DTS users to save time in adapting their applications to a new DTS version.
This specification distinguishes between "technical differences" and "semantic differences". "Technical differences" are those that can be automatically identified by software comparing the properties of the pair of information items under observation. "Semantic differences" are the interpretation of the "technical differences" made by the author of the versioning report. Given two DTSs and some rules to match information items from one DTS to the other, the set of "technical differences" is unique, but the set of "semantic differences" is unlimited because they are just an interpretation of the "technical differences". A "semantic difference" contains an aggregation of "technical differences" and human readable documentation that may be useful input to users migrating an application from using the previous DTS version to the next.
Figure 1 represents the different layers in the information of a Versioning Report.
There are many examples that show how the information in a DTS can be written in one or many different files without any impact on applications using the DTS. An example:
-
A taxonomy schema "A.XSD" for the namespace
http://foodefining two conceptstx:Oneandtx:Twomay reference one presentation linkbase with one parent-child arc in thehttp://www.xbrl.org/2003/roleconnecting the two concepts wherebytx:Oneis the parent oftx:Two. -
A different taxonomy schema "B.XSD" for the same
namespace
http://fooand defining the same concepts (tx:Oneandtx:Two), may have two embedded presentation linkbases in the samehttp://www.xbrl.org/2003/rolerole - one saying thattx:Twois the parent of tx:One and the other linkbase with relationship prohibiting the previous relationship and creating another one saying thattx:Oneis the parent oftx:Two.
Both DTSs are equivalent from the DTS consumer perspective because, even though taxonomy "A.XSD" and "B.XSD" are completely different in their syntax, both define the same concepts and the same resulting relationship between the concepts. Both DTSs define the same information set as it is used by applications consuming XBRL metadata other than, perhaps, XBRL DTS editors that have more strict requirements about representing prohibited relationships to the user.
1.3 Relationship to other work
This specification depends upon the following XBRL specifications:
- XBRL 2.1 Specification [XBRL 2.1]
- Generic Link Specification [GENERIC LINKS]
- Generic Label Specification [GENERIC LABELS]
- Generic Reference Specification [GENERIC REFERENCES]
In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
1.4 Language independence
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
1.5 Document conventions
1.5.1 Typographic conventions
1.5.1.2 Footnote notation
Comments which are informative, but not essential to the understanding of the point at hand, are provided in footnotes. All footnotes are non-normative.
1.5.1.3 Element and attribute notation
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.
1.5.2 Formatting conventions
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 4 shows the formatting for non-normative examples of poor, discouraged or disallowed usage.
The example itself.
1.6 Terminology
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 REFERENCES].
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].
1.7 Namespaces and namespace prefixes
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
|
gen
|
http://xbrl.org/2008/generic
|
xlink
|
http://www.w3.org/1999/xlink
|
1.8 URI resolution
This specification requires relative Uniform Resource Identifiers (URI) [IETF RFC 3986] to be converted to an absolute URI. In all cases, the absolute URI MUST be obtained in accordance with the XML Base Specification [XML Base].
2 Overview
This specification defines syntax and semantics for an XBRL Versioning Report.
A Versioning Report is an XML document that provides, according to the rules prescribed in this specification, information about the changes between two DTSs, the From-DTS and the To-DTS.
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.
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.
Individual changes between the From-DTS and the To-DTS are represented by Events. Events are grouped into logical changes by Actions which in turn are grouped into business level changes by Assignments.
The grouping of Events into Actions allows deletion Events to be associated with addition Events in order to represent a replacement relationship. The details of the mechanism by which such a replacement relationship is represented are defined in the specification modules for the relevant Events, but an example is given in Example 5.
The specification allows for human-readable documentation to be associated with both Assignments and Actions. In addition, the specification provides an extensible mechanism for the categorisation of Assignments.
For example, a concept in the From-DTS may be replaced by a pair of concepts in the To-DTS. This is represented by three Events:
In order for these to be understood as a replacement, rather than a deletion and two additions, the Events are grouped into a single Action.The replacement of this single concept by two other concepts may be part of a larger business level change that involves related changes to other concepts. These changes would be represented by other Actions that would be grouped into a single Assignment.
Typically, the documentation attached to the Assignment would document the motivation for the associated changes, for example, a change in the legislation or standard underpinning the taxonomy. The documentation attached to individual Actions may provide additional details on each change. For example, explaining in more detail how the two replacement concepts relate to the original concept.
3 Versioning Report Structure
A Versioning Report is comprised of the following components:
3.1 Versioning Report
3.1.1 XML Representation
A Versioning Report is represented by the
<ver:report>
element.
<ver:report
id = Content: </ver:report>
|
|
| Property | Representation |
|---|---|
| {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>
children of the
<ver:report>
element.
|
| {to-DTS} |
The To-DTS Identifier represented by the
<ver:toDTS>
children of the
<ver:report>
element.
|
| {assignments} |
The set of Assignments represented by the
<ver:assignment>
children of the
<ver:report>
element.
|
| {actions} |
The set of Actions represented by the
<ver:action>
children of the
<ver:report>
element.
|
| {events} |
The set of Events represented by the
<ver:event>
children of the
<ver:report>
element.
|
3.1.2 Validity
A Versioning Report is valid only if:
- it is valid according to the rules defined by the normative schema (see Appendix A); and
- it conforms to all validation rules defined in this specification.
3.2 DTS identifiers
A DTS Identifier is a set of one or more URIs that are the starting point for DTS discovery for the identified DTS.
3.2.1 XML Representation
A DTS Identifier is
represented by an element in the
<ver:dts.identifier>
substitution group.
<ver:dts.identifier>
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.
|
3.2.2 Validation Rules
A DTS Identifier MUST identify a DTS that is XBRL valid, according to the rules described in the XBRL Specification [XBRL 2.1].
The
<link:linkbaseRef>
and
<link:schemaRef>
elements are defined in the XBRL
Specification [XBRL 2.1] and instances of them MUST comply with the rules and
schema definitions defined in that specification.
3.2.3 From-DTS identifier
A From-DTS Identifier is a DTS Identifier that identifies the From-DTS.
3.2.3.1 XML Representation
A From-DTS Identifier is represented by the
<ver:fromDTS>
element.
See XML Representation for DTS Identifier.
3.2.4 To-DTS identifier
A To-DTS Identifier is a DTS Identifier that identifies the To-DTS.
3.2.4.1 XML Representation
A To-DTS
Identifier is represented by the
<ver:toDTS>
element.
See XML Representation for DTS Identifier.
3.3 Assignments
An Assignment is a grouping of related Actions.
The grouping of Actions provided by an Assignment allows common documentation (see Section 3.8) or categorisation (see Section 3.4) to be associated with a set of related Actions.
3.3.1 XML Representation
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>
.
|
| {actions} | The set of Actions in the Versioning Report with {assigments} properties that contain this Assignment. |
3.4 Assignment Categories
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. |
3.4.1 Custom Assignment Categories
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.
3.4.2 XML Representation
An Assignment Category is represented by an element in
the
<ver:category>
substitution group.
<ver:category
id = Content: none </ver:category>
|
3.5 Actions
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 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.
3.5.1 XML Representation
An Action is represented by a
<ver:action>
element.
<ver:action
id = Content: </ver:action>
|
|
<ver:actionRef
ref = xs:IDREF > Content: none </ver:actionRef>
|
|
| Property | Representation |
|---|---|
| {assignments} |
The set of Assignments identified by the
@ref
attributes of
<ver:actionRef>
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.
|
3.5.2 Validation Rules
The
@ref attribute of a
<ver:actionRef>
element MUST identify a
<ver:assignment>
element.
3.6 Events
An Event is an individual difference between the From-DTS and the To-DTS.
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.
3.6.1 XML Representation
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.
3.7 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.
3.8 Labels and References
Labels and references MAY be provided for certain components in a Versioning Report using generic labels and generic references. The components for which label and reference semantics are defined by this specification, and the corresponding XML elements with which generic labels and generic references are to be associated, are shown in the table below. Labels and references MAY be provided for other elements in a Versioning Report, but the semantics of such labels and references are not defined by this specification.
| Component | Element |
|---|---|
| Versioning Report |
<ver:report>
|
| Assignment |
<ver:assignment>
|
| Action |
<ver:action>
|
| Event |
<ver:event>
|
3.8.1 Label and Reference Linkbase Discovery
A Versioning Report MAY contain references to linkbases defining generic labels and generic references using a Linkbase Reference.
3.8.2 Linkbase Reference
A Linkbase Reference is an XLink simple link to an XBRL linkbase.
3.8.2.1 XML Representation
A Linkbase Reference is represented by a
<link:linkbaseRef>
child of the
<ver:report>
element.
The
<link:linkbaseRef>
is defined by the XBRL Specification [XBRL 2.1].
3.8.2.2 Validation Rules
A Linkbase Reference MUST conform to the rules defined in section 4.3 of the XBRL Specification [XBRL 2.1].
3.9 Related Versioning Reports
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
3.9.1 Versioning Report References
A Versioning Report Reference is an XLink simple link to a Related Versioning Report.
3.9.1.1 XML Representation
A Versioning Report Reference is represented by
the
<ver:reportRef>
element.
The
<ver:reportRef>
element is an XLink simple
link.
<ver:reportRef
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].
|
3.9.1.2 Validation Rules
The
@xlink:type attribute MUST have a value of "simple".
The {related versioning report} MUST be a valid Versioning Report, as defined by this specification.
The
@xlink:arcrole attribute MUST be present and MUST have the
value "http://xbrl.org/arcrole/2010/versioning/related-report"
4 Base Events
This specification defines a number of Events that may be used by all Versioning Reports. These are documented below.
4.1 Namespace Name Event
| Code | Element | From Identifier | To Identifier |
|---|---|---|---|
| [NamespaceName] |
<ver:namespaceMapping>
|
Namespace Name Identifier | Namespace Name Identifier |
The Namespace Name Event associates a namespace name in the From-DTS with a namespace name in the To-DTS. See Mappings ( Section 6).
4.2 Role URI Event
| Code | Element | From Identifier | To Identifier |
|---|---|---|---|
| [RoleURI] |
<ver:roleMapping>
|
Role URI Identifier | Role URI Identifier |
The Role URI Event associates a role URI in the From-DTS with a role URI in the To-DTS. See Mappings ( Section 6).
5 Identifiers
5.1 Namespace Name Identifier
A Namespace Name Identifier is a URI Reference that identifies a Namespace Name.
5.1.1 Validation Rules
The {URI} property of the URI Reference MUST be equal to the target namespace of a schema in:
- the From-DTS, if the Namespace Name Identifier is used as a From Identifier; or
- the To-DTS, if the Namespace Name Identifier is used as a To Identifier.
5.2 Role URI Identifier
A Role URI Identifier is a URI Reference that identifies a Role URI.
5.2.1 Validation Rules
The {URI} property of the URI Reference MUST be equal to the roleURI of a role type definition in
- the From-DTS, if the Role URI Identifier is used as a From Identifier; or
- the To-DTS, if the Role URI Identifier is used as a To Identifier.
5.3 URI Reference
A URI Reference is an abstract Identifier for any URI.
5.3.1 XML Representation
A URI Reference is represented by:
-
a
<ver:fromURI>element, if it is used as a From Identifier; or -
a
<ver:toURI>element, if it is used as a To Identifier.
<ver:fromURI
value = xs:anyURI> Content: None </ver:fromURI>
|
|
<ver:toURI
value = xs:anyURI> Content: None </ver:toURI>
|
|
| Property | Representation |
|---|---|
| {URI} |
The actual value of the
@value attribute of the
<ver:fromURI>
or
<ver:toURI>
element.
|
6 Mappings
6.1 Namespace Mappings
A Namespace Mapping is the association of a From-Namespace with a corresponding To-Namespace.
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.
A Namespace Mapping is defined by a Namespace Name Event. A single namespace name MAY be involved in more than one Namespace Mapping.
6.2 Role URI Mappings
A Role URI Mapping is the association of a From-Role-URI with a corresponding To-Role-URI.
A From-Role-URI is a roleURI that is defined by a role definition in the From-DTS.
A To-Role-URI is a roleURI that is defined by a role definition in the To-DTS.
A Role URI Mapping is defined by a Role URI Event. A single roleURI MAY be involved in more than one Role URI Mapping.