1 Introduction
This specification defines an XML syntax for versioning reports. A versioning report is an XML document containing a comparison of two DTSs, documenting changes between XML nodes and/or its aspects. The creator of the versioning report is supported with this specification to communicate both the technical and semantic changes. With these changes documentation or pointers to documentation may be provided by the versioning report creator.
This part of the versioning specification covers the basic elements needed to communicate a versioning report. There will be other modules built on top of this specification to cover specific syntax of XBRL or semantics that can occur in a DTS. A versioning report contains references to two DTSs; the 'from dts' abbreviated in this specification as F-DTS and the 'to dts' abbreviated in this specification as T-DTS.
It is important to recognise that a versioning report does not stand in isolation from the F-DTS or the T-DTS. Thus, it is not possible to use the F-DTS and a versioning report to obtain the information content of the T-DTS. Similarly, it is not possible to use the T-DTS and a versioning report to obtain the information content of the F-DTS. In other words there is no guarantee that a single DTS combined with a versioning report will result in another DTS that is exactly the same as the taxonomy author would have intended.
A versioning report depends on the
F-DTS and the T-DTS
because it records some or all of the information items that differ between the DTSs but they
do not record the substance of those differences. Eg. the values that could be switched
on a specific Boolean attribute between versions of a DTS are NOT communicated in the report,
just the pointer to the attribute is supplied. The only exceptions to this rule are the
@name,
on XML elements and attributes, and the URI on namespaces and linkroles since these are considered
the ´key´ to discovering XML nodes and their content.
This specification does not impose any obligation on taxonomy authors to document changes in a specific way but rather provides a framework to standardise the way the changes are communicated so that applications can consume that information for their purposes.
1.1 Background
A number of projects and people have made significant contributions to this specification. These include:
- the IASC Foundation which has contributed a methodology on which this specification is based,
- the Standard Business Report project ("SBR") initiated by the Dutch government, which has contributed the first initial documentation of a standardisation for a Versioning report,
- Ignacio Hernadez-Ros who designed the XBRL Infoset approach and wrote the first drafts of this specification.
Several other initiatives such as the Committee of European Banking Supervisors have joined efforts together in order to help the XBRL Consortium and the XBRL industry to adopt a single common solution that satisfies the most critical business requirements in all those projects.
1.2 Relationship to other work
This specification depends upon the XBRL 2.1 Specification [XBRL 2.1].
1.3 Language independence
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
1.4 Document conventions
1.4.1 Typographic conventions
1.4.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.4.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.4.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 3 shows the formatting for non-normative examples of poor, discouraged or disallowed usage.
The example itself.
1.5 Terminology
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]
- XBRL Infoset Specification []
- XBRL Versioning Specification Part I []
In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
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].
Where this document refers to an XML schema, it is referring to an XML document [XML] that contains a declaration of a schema that is compliant with XML Schema [XML Schema Structures].
Arc, arcroleRef, base set, child, concept, context, duplicate item, descendant, DTS (discoverable taxonomy set), element, entity, fact, instance, item, linkbase, linkbaseRef, p equal, roleRef, taxonomy, taxonomy schema, u equal, XBRL instance are as defined by [XBRL 2.1].
A versioning report is an XML document containing a comparison of two
DTSs, documenting
events.
A versioning report manifests itself as a
<ver:report>
element.
A DTS identifier is a collection of absolute URIs that are
interpreted as the starting points for discovery of the identified
DTS.
A DTS identifier manifests itself as an element in the
substitution group
for the
<ver:dts.identifier>
element.
The F-DTS is the DTS that forms the base of the comparison, usually this will be the DTS with lowest version number or earliest release date.
The T-DTS is the DTS that is being compared, usually this will be the DTS with the highest version number or latest release date.
An assignment represents a versioning task.
An assignment manifests as a
<ver:assignment>
element.
Assignments are categorised using
category tags.
An assignment can be referred from by an
action.
A category is a classification of a
F-DTS modification
assignment.
A category manifests as an element in the
substitution group
for the abstract
<ver:category>
element.
A category indicates that the containing
assignment is in the
category identified by the
@id on the
category element.
A technical category is a
category, that, when used to tag an
assignment, indicates that the
assignment
is driven by technical requirements such as to distinguish the
T-DTS from the F-DTS.
A technical category manifests itself as a
<ver:technicalCategory>
element.
A business category is a
category, that, when used to tag an
assignment, indicates that the
assignment
is intended to bring the T-DTS into closer
alignment with current business requirements.
A business category manifests itself as a
<ver:businessCategory>
element.
An errata category is a
category, that, when used to tag an
assignment, indicates that the
assignment
is intended to correct errata in the F-DTS.
An errata category manifests itself as a
<ver:errataCategory>
element.
An action is that what initiates changes between the
F-DTS and the
T-DTS.
An action manifests itself as a
<ver:action>
element.
An action can contain one or multiple
events.
A versioning linkbase reference is an
XLink simple link to an XBRL linkbase from within a
versioning report.
A versioning linkbase reference manifests itself as a
<link:linkbaseRef>
element.
A supplementary report is information about the changes between the F-DTS and the T-DTS that is external to the versioning report.
A report reference is an
XLink simple link to a
supplementary report.
A report reference manifests itself as an
<ver:reportRef>
element.
A version information item is the set of XML nodes that documents the changes to XBRL concepts, resources and linkroles between two DTSs.
An URI mapping is global information that identifies an
absolute URI in the F-DTS and associates
that with the absolute URI in the T-DTS
that replaces it.
An URI mapping manifests itself as an element in the
substitution group
for the abstract
<ver:mapping>
element.
A from-URI is an absolute URI in the F-DTS.
A to-URI is an absolute URI in the T-DTS.
A namespace mapping is a mapping from a target namespace URI in the
F-DTS to a target namespace URI in the
T-DTS.
A namespace mapping manifests itself as a
<ver:namespaceMapping>
element.
A role mapping is a mapping from an
XLink link role URI in the
F-DTS to an
XLink link role URI in the
T-DTS.
A role mapping manifests itself as a
<ver:roleMapping>
element.
An event refers to a change to an information item in a
DTS.
An event explicitly identifies the affected information item in the
F-DTS, if any exists, and the affected information item in the
T-DTS, again if any exists.
An event manifests itself as an element in the
substitution group
for the
<vercb:event>
element.
An event is a container of a set of zero or more differences between the
F-DTS and the
T-DTS.
A Difference Event is the representation of something not equivalent found between properties of two corresponding Versioning Information Items being compared. This is equivalent to what is referred to as a "technical difference".
An identifier is a child element of an event that identifies an information item in either the F-DTS or the T-DTS.
A namespace pair refers to an association of a single From namespace and a single To namespace.
The paired namespace of the From namespace is the To namespace defined in the namespace mapping or the same From namespace if none is explicitly defined in the namespace mapping. This relationship is symmetric.
The role URI pair of the From role URI is the To URI defined in the role mapping or the same From URI if none is explicitly defined in the role mapping. This relationship is symmetric.
The paired role URI of the From role URI is the To URI defined in the role mapping or the same From URI if none is explicitly defined in the role mapping. This relationship is symmetric.
A Difference Path is a set of Difference Events. Some of the events contain parameters to identify the concepts, relationships, resources, attributes or XML fragments.
The Starting Event of a path is always the first event in the path.
The Ending Event of a path is always the last event in the path.
1.6 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/2008/versioning-base
|
xbrlvere
|
http://xbrl.org/2008/versioning-base/error
|
xs
|
http://www.w3.org/2001/XMLSchema
|
gen
|
http://xbrl.org/2008/generic
|
eg
|
http://example.com/
|
1.7 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].
Some URIs need to be resolved to obtain the resource that they identify. Some of those URIs MAY include an XPointer expression [XPOINTER].
Error code xbrlvere:invalidXPointerScheme
MUST
be thrown if the XPointer expression in a URI in a versioning report is scheme-based and includes an
XPointer scheme
other than the element() scheme ([ELEMENT-SCHEME]).
2 XBRL Versioning
This specification only provides a textual declaration of syntax constraints when those constraints are not expressed by the normative schema supplied with this specification.
Explanations of elements and attributes are only supplied when explanations are not already provided in other specifications.
Unless explicitly stated otherwise, a reference to a specific element MUST be read as a reference to that element or to any element in its substitution group.
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 taxonomy" in order for taxonomy users to save time in adapting their applications to a new taxonomy 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 taxonomy version to the next.
Figure 1 represents the different layers in which the information of a versioning report is structured.
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 relationship prohibiting the previous relationship and creating another one saying thattx:Oneis the parent oftx:Two.
Both taxonomies 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 Taxonomy editors that have more strict requirements about representing prohibited relationships to the user.
Various terms are defined throughout this specification. For some of those terms, the things that they refer to are said to manifest as particular elements. In such cases, the term will be used to refer to the thing itself and to the element that the thing manifests as.
2.1 Versioning reports
A versioning report manifests as a
<ver:report>
element.
2.1.1 DTS identifiers
DTS identifiers
contain a set of zero or more URIs. Each URI is the content of either the
<link:linkbaseRef>
or
<link:schemaRef>
elements in the DTS identifier.
Each URI in a DTS identifier MAY be absolute or relative. URIs in DTS identifiers MUST be resolved in accordance with Section 1.7.
Note that, because using different sets of URIs as the starting points for discovery of a DTS can result in the same DTS being discovered, it is possible for two DTS identifiers, that contain different sets of URIs, to identify the same DTS.
Versioning reports contain a
DTS identifier for the
F-DTS and a
DTS identifier for the
T-DTS. The
DTS identifier of the
F-DTS manifests as a
<ver:fromDts>
element and the
DTS identifier for the
T-DTS manifests as a
<ver:toDts>
element.
2.1.2 Labels, documentation and references
Labels, documentation and references can be associated with:
that they contain, using generic labels [GENERIC LABELS] and generic references [GENERIC REFERENCES] in generic links [GENERIC LINKS].
Generic labels [GENERIC LABELS] and references [GENERIC REFERENCES] for versioning reports provide information about the versioning report as a whole.
Generic labels [GENERIC LABELS] and references [GENERIC REFERENCES] for categories can provide information about specific categories as it applies to all assignments that have been tagged with it.
Generic labels [GENERIC LABELS] and references [GENERIC REFERENCES] for assignments can provide information about the nature of the assignments.
Generic labels [GENERIC LABELS] and references [GENERIC REFERENCES] for actions can provide information about the nature of the actions.
Generic labels [GENERIC LABELS] and references [GENERIC REFERENCES] for events provide information about the events themself.
A versioning report can include links to XBRL linkbases to assist in their location. However, the generic links [GENERIC LINKS] that MAY be used to augment or document the content of a versioning report are not limited to that set of linkbases that are identified by links in the versioning report.
2.1.3 Supplementary reports
Sometimes it can be useful to augment an XBRL versioning report with references to one or more supplementary reports. For example, an XBRL versioning report for changes to a core DTS might usefully be referenced by a versioning report for an extension to that core. In other cases, it can be useful to provide references to documentation about the differences between the two DTSs that are expressed without using XBRL syntax. This documentation can be provided by linking to them with generic linkbases and including that linkbase as a report reference.
2.1.4 Categories
In a versioning report, all categories are child elements of the
<ver:categories>
element that, itself, is a child of the versioning report.
Each category in a versioning report is uniquely identified
by the value of its
@id attribute.
This specification defines three categories but additional categories can be defined by DTS maintainers should they wish to tag the events between versions of their DTSs with alternative categories.
To define a new category,
versioning report authors
need to create an XML schema that declares
the new category element to be directly or indirectly
in the substitution group for the
<ver:category>
element. The interpretation of the newly defined category
will need to be specified by its creator.
2.1.5 Assignments
Assignments serve three purposes:
- They enable the tasks to be documented using generic labels and references.
- They enable the tasks to be broken down into individual actions, each of which may result in revisions to the F-DTS.
- They enable the tasks to be categorised into one or more of the categories included in the versioning report.
Assignments MAY be categorised using
<ver:categories>
elements which are referenced by the
@ref on the
<ver:cTag>
element.
Assignments are optional.
An assignment with no relationships to actions represents unimplemented but solicited changes to a DTS.
Assignments are grouped. A group of
assignments is expressed with the
<ver:assignments>
element. Each group of
assignments has at least one individual
assignment.
2.1.6 Actions
Actions serve two purposes:
- They support the grouping of related events;
- They enable such groups of related events to be associated with the assignment(s) that motivated them.
An action refers to zero, one or more
assignments using the
@ref on the
<ver:aTag>
element.
An action referencing changes made to concepts or relationships in both the F-DTS and T-DTS indicates that these are in correspondence.
An action referencing changes made to concepts or relationships in only the F-DTS represents concepts or relationships deleted from the F-DTS.
An action referencing changes made to concepts or relationships in only the T-DTS represents concepts or relationships added to the T-DTS.
A single action has zero or more events. If an action contains no events, it plays the role of a container for generic information related to the T-DTS.
2.1.7 Events
Changes can be grouped together in a set to provide semantic meaning to the event. The semantic meaning of different groups of changes is defined in other modules of the versioning specification. This base specification is not dealing with events.
Each kind of event has a corresponding concrete element that is used to represent it in a versioning report. Thus, the element name of each event identifies exactly which kind of event is being documented.
That information is not sufficient, however, to fully document the event. It is also necessary to know which specific information items in the F-DTS and/or T-DTS are affected by the event. This information is provided by identifiers.
2.2 The content model of the versioning report
A versioning report is a set of one or more version information items.
The content of a version information item is represented in Figure 2
Each one of the containers in the figure represents different pieces of information about changes made to a taxonomy.
Assignments can:
- group actions made to a DTS, and
- be categorised in order to allow business users to filter what information they want to access, and
- be documented separately, and
- are optional content in a versioning report.
Actions can:
- group a set of events between the From DTS and the To DTS, and
- provide a semantic meaning for the change, and
- provide specific human readable documentation.
2.2.1 Complete versioning reports
Looking at the information in the versioning report as if it were a database, the in-scope documentation for a change is the result of a query that identifies the set of human readable documentation that satisfies the query conditions.
The query conditions can be completely generic or very explicit to a particular change event or change event path. The in-scope documentation can range from being as extensive as the whole report for generic queries to being as explicit as the documentation related to a specific action for a particular event made to a particular concept.
A complete versioning report could be viewed upon from a technical perspective which would result in a report that could be made by various XML 'diffing' tools on the market. The problem with these kind of results is that it ignores the semantics of the change. The instance creator or DTS extender is ultimately interested in the semantics of the changes. This specification does NOT impose any requirement that versioning reports be complete. The versioning report creator is the one who decides which changes make it to the report and how extensive the documentation will be on these changes.
2.2.2 Validity of a versioning report
A versioning report is valid if it validates against the normative XML schema in Appendix A and if the content of the versioning report does not require any of the errors defined in this specification to be thrown.
Since this base module is only able to communicate URL mappings it is unlikely that it will be used without the aid of other versioning modules. In doing so the versioning report should also validate against any normative schema from the modules used to create the report.
2.2.3 The differences between two DTSs
This specification defines the equivalency operation between two DTSs, the F-DTS and the T-DTS. The equivalency operation is independent of the syntax and modularisation strategy used to serialize a DTS. Comparison of two DTSs that are not equivalent produces a set of "technical differences" that are identified in this specification. This specification does not define any specific algorithm to find the differences.
There are Difference Events defined for each type of 'technical difference' that is possible between two Versioning Information Items covered by this specification.
The computation of the Difference Events requires two tables of paired properties that define the mapping rules between DTSs. See Section 2.3 and the definitions of namespace pair and role URI pair. Some properties must be compared after applying the appropriate mapping. This specification explicitly defines in which situation the mapping rules must be applied.
A Difference Path contains just one Starting Event and one Ending Event. It is possible that the path contains just one event that plays the role of starting and ending event simultaneously. A Difference Path is not a tree with one Starting Event and multiple Ending Events, or the other way around.
2.3 Mappings
2.3.1 URI mappings
All URI mapping are global information required to correctly understand the versioning report. Further actions in the report depend on how the URI mappings are defined.
All URI mappings express two absolute URI values: the from-URI and the to-URI.
A from-URI
is expressed by the
@value on a
<ver:fromURI>
element.
A to-URI
is expressed by the
@value on a
<ver:toURI>
element.
Error code xbrlvere:invalidRelativeURI MUST be thrown if a from-URI or a to-URI is not an absolute URI.
Two concrete URI mappings are defined in this specification:
2.3.1.1 Namespace mappings
The namespace mapping information is a set of namespace pairs identifying pairs of From and To namespaces.
Error code xbrlvere:nonexistentNamespaceURI MUST be thrown if a from-URI in a namespace mapping is not an XML Schema namespace in the F-DTS or a to-URI in a namespace mapping is not an XML Schema namespace in the T-DTS.
2.3.1.2 Role mappings
The role mapping information is a set of role URI pairs identifying which are the From URI and the To URI
Error code xbrlvere:nonexistentRoleURI MUST be thrown if a from-URI in a role mapping is not a link role URI in the F-DTS or a to-URI in a role mapping is not a role URI in the T-DTS.