Copyright ©2008 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 specification-feedback@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.
XBRL reports make business information available in an open, structured, machine-readable form. The data points in a report can be qualified by any number of dimensions, but are always associated with a time period, a business entity (such as a corporation), and a reporting concept, such as revenue.
The reporting concepts are defined in XBRL taxonomies. Beyond defining a vocabulary for reports, taxonomies contain valuable metadata -- relationships between concepts, human-readable labels, and links to authoritative literature.
This specification aims to facilitate the creation of new kinds of metadata by providing additional concrete linking components, as well as guidance for the definition of custom linking components.
1 Introduction
1.1 Background
1.2 Relationship to other work
1.3 Language independence
1.4 Terminology
1.5 Document conventions (non-normative)
1.6 Namespaces and namespace prefixes
2 Syntax
2.1 Generic links
2.1.1
@xlink:role attributes on generic links
2.1.2
@xlink:role attributes on resources in generic links
2.1.3 Locators in generic links
2.2 Generic arcs
2.2.1
xlink:arcrole attributes on generic arcs
A Normative schema
B Defining Custom Linking Components (non-normative)
B.1 Custom extended links
B.2 Custom arcs
B.3 Custom resources
C References
D Intellectual property status (non-normative)
E Acknowledgements (non-normative)
F Document history (non-normative)
G Errata corrections in this document
1 Namespaces and namespace prefixes
1 XML Schema content model for an extended link that can force document discovery
2 A custom link capturing an audit opinion that is tied to specific facts in an XBRL instance
custom arc
custom extended link
custom resource
generic arc
generic link
xbrlgene:missingArcRoleUsedOnValue
xbrlgene:missingLinkRoleUsedOnValue
xbrlgene:missingResourceRoleUsedOnValue
xbrlgene:missingRoleRefForArcRole
xbrlgene:missingRoleRefForLinkRole
xbrlgene:missingRoleRefForResourceRole
xbrlgene:nonAbsoluteArcRoleURI
xbrlgene:nonAbsoluteLinkRoleURI
xbrlgene:nonAbsoluteResourceRoleURI
xbrlgene:violatedCyclesConstraint
XBRL taxonomies make extensive use of XLink [XLINK] to declare various kinds of relationships that supplement the information and constraints provided by XML Schema. The XBRL 2.1 Specification [XBRL 2.1] defines a number of standard XLink extended links, arcs, roles and arcroles for use with concepts, the basic building blocks of an XBRL taxonomy. These include the following elements:
<link:labelLink>
and
<link:labelArc>
for attaching labels to XBRL concepts.
<link:referenceLink>
and
<link:referenceArc>
for associating XBRL concepts with references to authoritative literature.
<link:calculationLink>
and
<link:calculationArc>
for defining arithmetic relationships between XBRL concepts.
<link:presentationLink>
and
<link:presentationArc>
for organising XBRL concepts into trees for presentation.While these constructs are useful (indeed because they are so useful) one quickly finds oneself wishing to use the power of XLink to associate information with, and express relationships between XML elements that are not XBRL concepts.
This specification defines an extended link (
<gen:link>
) and an
arc (
<gen:arc>
) which are capable of establishing relationships
between arbitrary XML elements.
This specification does not in any way alter the XBRL Specification [XBRL 2.1]. In particular, [XBRL 3.5], which defines the general semantics for XBRL relationships (how they are defined, partitioned, prohibited, and reintroduced) and [XBRL 3.2], which defines the rules of DTS discovery, apply to generic extended links, arcs, and resources in the same way that they apply to the standard arcs and resources.
However, this specification does specify a few additional constraints, which are clearly marked. As a starting point, all processors claiming conformance with this specification MUST enforce the constraints expressed in the Schema for generic links in Appendix A.
Finally, in Appendix B, this specification provides some non-normative guidance for the creation of custom linking constructs.
Many extensions of the XBRL Specification [XBRL 2.1] make use of custom link syntax. This specification provides guidance on the use of custom links and provides concrete syntax that can be leveraged by extensions of the XBRL Specification.
This specification depends upon the XBRL Specification [XBRL 2.1]. In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
This specification is consistent with the definitions of any of the terms defined in specifications that it depends on.
Documentation conventions follow those set out in the XBRL Variables Specification [VARIABLES].
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 |
|---|---|
gen
|
http://xbrl.org/2008/generic
|
xbrlgene
|
http://xbrl.org/2008/generic/error
|
link
|
http://www.xbrl.org/2003/linkbase
|
xlink
|
http://www.w3.org/1999/xlink
|
eg
|
http://example.com/
|
This section defines some concrete linking components that can be used to establish relationships involving arbitrary XML elements.
A generic link is an XBRL extended link that is in the substitution group
of the
<gen:link>
element.
The syntax for the
<gen:link>
element is defined by the normative schema supplied with this specification.
Generic links can be used in any XBRL linkbase
[XBRL 3.5.2],
subject to the restrictions imposed by
@xlink:role attributes on any
<link:linkbaseRef>
elements that reference the linkbase
[XBRL 4.3.4].
@xlink:role attributes on generic links
The
@xlink:role attribute serves the same purpose on
generic links as it serves on the standard
extended links defined by the XBRL 2.1 specification -- it
partitions relationships of the same type into disjoint networks.
The value, V, of the
@xlink:role attribute on a generic
link MUST be an absolute URI.
Error code xbrlgene:nonAbsoluteLinkRoleURI
MUST be thrown if V is not an absolute URI.
If the value V is not the standard extended
link role (http://www.xbrl.org/2003/role/link), then
the ancestor
<link:linkbase>
element of the generic link MUST
have a child
<link:roleRef>
element with V as the value of its
@roleURI attribute.
Error code xbrlgene:missingRoleRefForLinkRole
MUST be thrown if the ancestor
<link:linkbase>
element of the generic link does not
have a child
<link:roleRef>
element
with V as the value of its
@roleURI attribute.
The
<link:roleType>
element pointed to by the
<link:roleRef>
element with
@roleURI attribute equal to V MUST contain a
<link:usedOn>
child element
with a QName value that has namespace equal to the namespace of the generic link
and that has local name equal to the local name of the generic link.
Error code xbrlgene:missingLinkRoleUsedOnValue
MUST be thrown if the
<link:roleType>
element pointed to by the
<link:roleRef>
element with
@roleURI attribute equal to V
does not contain a
<link:usedOn>
child element
with a QName value that has namespace equal to the namespace of the generic link
and that has local name equal to the local name of the generic link.
@xlink:role attributes on resources in generic links
If a resource in a generic link has a
@xlink:role attribute, then
the value, V, of that
@xlink:role attribute
MUST be an absolute URI.
Error code xbrlgene:nonAbsoluteResourceRoleURI
MUST be thrown if V is not an absolute URI.
The ancestor
<link:linkbase>
element of the resource MUST
have a child
<link:roleRef>
element with V as the value of its
@roleURI attribute.
Error code xbrlgene:missingRoleRefForResourceRole
MUST be thrown if the ancestor
<link:linkbase>
element of the resource does not
have a child
<link:roleRef>
element
with V as the value of its
@roleURI attribute.
The
<link:roleType>
element pointed to by the
<link:roleRef>
element with
@roleURI attribute equal to V MUST contain a
<link:usedOn>
child element
with a QName value with a namespace equal to the namespace of the resource
and with a local name equal to the local name of the resource.
Error code xbrlgene:missingResourceRoleUsedOnValue
MUST be thrown if the
<link:roleType>
element pointed to by the
<link:roleRef>
element with
@roleURI attribute equal to V
does not contain a
<link:usedOn>
child element
with a QName value that has namespace equal to the namespace of the resource
and that has local name equal to the local name of the resource.
Although the normative schema in Appendix A
allows any element that is in the substitution group for
the
<link:loc>
element to appear within a generic link,
users should be aware that DTS discovery
[XBRL 3.2] is only defined for
locators expressed by the
<link:loc>
element.
Any schema or linkbase referenced only by locators expressed by
elements other than
<link:loc>
will not be included in the DTS.
The targets of
@xlink:href attributes on
<link:loc>
elements in generic links are
not constrained by this specification; locators in
generic links MAY point to arbitrary
XML elements.
A generic arc is an XBRL arc that is in the substitution group
of the
<gen:arc>
element.
The syntax for the
<gen:arc>
element is defined by the normative schema supplied with this specification.
Generic arcs typically appear inside generic links, but MAY appear elsewhere.
xlink:arcrole attributes on generic arcs
The value, V, of the
@xlink:arcrole attribute on an generic
arc MUST be an absolute URI.
Error code xbrlgene:nonAbsoluteArcRoleURI
MUST be thrown if V is not an absolute URI.
The ancestor
<link:linkbase>
element of the generic arc MUST
have a child
<link:arcroleRef>
element with V as the value of its
@arcroleURI attribute.
Error code xbrlgene:missingRoleRefForArcRole
MUST be thrown if the ancestor
<link:linkbase>
element of the generic arc does not
have a child
<link:arcroleRef>
element
with V as the value of its
@arcroleURI attribute.
The
<link:arcroleType>
element pointed to by the
<link:arcroleRef>
element with
@arcroleURI attribute equal to V MUST contain a
<link:usedOn>
child element
with a QName value that has namespace equal to the namespace of the generic arc
and that has local name equal to the local name of the generic arc.
Error code xbrlgene:missingArcRoleUsedOnValue
MUST be thrown if the
<link:arcroleType>
element pointed to by the
<link:arcroleRef>
element with
@arcroleURI attribute equal to V
does not contain a
<link:usedOn>
child element
with a QName value that has namespace equal to the namespace of the generic arc
and that has local name equal to the local name of the generic arc.
The constraints implied by the
@cyclesAllowed attribute on the
<link:arcroleType>
element MUST be
enforced (according to the rules of [XBRL 5.1.4.3])
for all networks of relationships in the DTS that have arcrole V.
Error code xbrlgene:violatedCyclesConstraint
MUST be thrown if
the constraints implied by the
@cyclesAllowed attribute on the
<link:arcroleType>
element are not
satisfied (according to the rules of [XBRL 5.1.4.3])
for all networks of relationships in the DTS that have arcrole V.
The following is the XML schema provided as part of this specification. This is normative. Non-normative versions (which should be identical to these except for appropriate comments indicating their non-normative status) are also provided as separate files for convenience of users of the specification.
NOTE: (non-normative) Following the schema maintenance policy of XBRL International, it is the intent (but is not guaranteed) that the location of non-normative versions of these schemas on the web will be as follows:
http://www.xbrl.org/2008/ - during the drafting process for
this specification this directory should contain a copy of the
most recent published version of the schema at
http://www.xbrl.org/2008/generic-link.xsd.
For convenience, the normative schema contains the following link role declarations:
A custom extended link is an extended link that is in the substitution group
for the abstract
<xl:extended>
element and that is not one of the concrete extended
link elements defined in the XBRL Specification [XBRL 2.1].
It should not generally be necessary to define custom extended links. A custom extended link should only be defined when tight control over the content model is desired.
For example, you may want to define a custom extended link whose sole purpose is to force discovery of a document:
XBRL forbids the use of
<link:linkbaseRef>
element within linkbases, but a
locator within an element like that in
Example
1
achieves the same effect. Here it is not appropriate to include resources and arcs;
the content model only allows locator, and optional documentation elements.
A custom arc is an element that is in the substitution group
for the abstract
<xl:arc>
element and that is not one of the concrete arcs
defined in the XBRL Specification [XBRL 2.1].
While custom extended links are rarely required,
custom arcs are useful whenever you want to define a type of
relationship that has required attributes in addition to those defined
in the XLink namespace http://www.w3.org/1999/xlink.
Using a custom arc, the occurrence constraints for those attributes can be specified
using XML Schema [SCHEMA-1].
Note: To be usable within generic links,
custom arcs must be in the substitution group for the
<gen:arc>
element.
A custom resource is an element that is in the substitution group
for the abstract
<xl:resource>
element and that is not one of the concrete resources
defined in the XBRL Specification [XBRL 2.1].
It will also be quite common to define custom resources, sometimes
with complex content models, possibly allowing mixed content.
An obvious example would be a generic XHTML resource, akin to
the
<link:label>
element, but used in conjunction with
generic links and generic arcs so that semantics are
determined by the arcrole alone, rather than spread across the
resource
(
<link:label>
,
the arcrole - http://www.xbrl.org/2003/arcrole/concept-label,
the arc -
<link:labelArc>
, and
the extended link -
<link:labelLink>
).
On the other hand, if control over resource roles is desired (to distinguish between a terse and a verbose label, for example), then a concrete, specialised element (possibly derived from a generic XHTML resource) may be appropriate as shown in Example 2.
Note that
Example
2 also includes a custom link
element but only requires the
<gen:arc>
element defined in this specification.
Custom audit opinion linkbase relating the audit opinion to three of the facts in the audited XBRL instance. Naturally, the custom link could be expanded to relate different opinion resources to different sets of facts in the XBRL instance that has been audited.
Supporting XML schema (assumed in the audit link to
have URL: http://www.example.com/opinion.xsd).
The custom link in Example 2 defines relationships from a custom resource to specific facts in an XBRL instance. However, the referenced XBRL instance is not in any DTS that includes this custom link, and should not be processed *as* an XBRL instance (unless it was also the starting point for processing). Any XBRL validation checks, beyond those required by XML Schema constraints, should not apply to such a non-entry point XBRL instance, and DTS discovery should not proceed further from it.
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).
The editors thank the members of the various XBRL working groups for supporting the creation of this document, and for providing valuable feedback on internal drafts.
| Date | Author | Details |
|---|---|---|
| 26 June 2006 | Ignacio Hernandez-Ros |
Created initial draft. |
| 08 November 2006 | Geoff Shuetrim |
Narrowed scope to the specific concrete syntax constructs to be defined in the specification. Inserted updated versions of the syntax definitions provided by Mark Goodhand. |
| 24 July 2007 | Mark Goodhand |
Released as a public working draft. |
| 01 November 2007 | Mark Goodhand |
The schema now allows only arcs substitutable for generic arcs to appear in generic links. |
| 01 November 2007 | Mark Goodhand |
The date in the namespace has changed from 2007 to 2008. |
| 08 February 2008 | Geoff Shuetrim |
Editorial changes in preparation for publication as a second public working draft. Added comments requesting definitions of custom extended links, custom arcs and custom resources. Added new constraints requiring role and arcrole type declarations for custom extended link role values and and custom arc role values. |
| 10 February 2008 | Geoff Shuetrim |
Changed the ID attributes on the generic link and generic arc elements as suggested by Mark Goodhand. Simplified the wording of the constraints relating to roles and arcroles based on feedback from Mark Goodhand. Added new constraints on the roles of resources in generic links. |
| 12 February 2008 | Geoff Shuetrim |
Added definitions of custom extended links, custom arcs and custom resources. |
| 13 February 2008 | Geoff Shuetrim |
Changed definitions of generic links and generic arcs to also include elements in the substitution
groups for the concrete elements defined in the normative schema for this specification. This
enables extension specifications to define new arcs, for example, in the substitution group for
the Fixed the IDs used for the references to specific sections of the XBRL Specification [XBRL 2.1]. |
| 18 March 2008 | Geoff Shuetrim |
Fixed XML Schema validation problems for the example in Appendix B, as identified by Walter Hamscher. |
| 20 March 2008 | Geoff Shuetrim |
Fixed broken hyperlinks. |
| 01 April 2008 | Geoff Shuetrim |
Relaxed the requirments for |
| 02 April 2008 | Geoff Shuetrim |
Added the custom audit link example that was provided by Walter Hamscher. |
| 09 April 2008 | Geoff Shuetrim |
Added material to Appendix B to explain the relationship between custom links, arcs and resources
and the |
| 16 April 2008 | Geoff Shuetrim |
Removed the paragraphs explaining the Error codes have been defined for all constraints imposed by this specification as suggested by Cliff Binstock. |
| 04 November 2008 | Geoff Shuetrim |
Renamed the non-normative schema document. |
| 15 December 2008 | Geoff Shuetrim |
Updated references to the latest errata-corrected version of the XBRL 2.1 specification. |
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 Base Specification and Maintenance Working Group up to and including 31 December 2008. 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.