XBRL Generic Links 1.0
Public Working Draft, dated 2007-04-24
Copyright © 2007, XBRL International Inc., All Rights Reserved

This version

XGL-PWD-2007-04-24.rtf

is NORMATIVE. All other formats and versions are NON-NORMATIVE.
Authors
Name	Contact	Affiliation	
Mark Goodhand	mrg@decisionsoft.com	DecisionSoft	
Ignacio Hernández-Ros	ignancio@hernandez-ros.com	Reporting Estándar S.L.	
Geoff Shuetrim	geoff@galexy.net	Galexy Pty. Limited	

Abstract

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.

Status

This is a Public Working Draft whose distribution is unrestricted. Recipients of this draft are invited to submit comments to the authors and contributors, and to submit notification of any relevant patent rights of which they are aware and to provide supporting documentation.

1. Introduction

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] 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:

•	labelLink & labelArc for attaching labels to XBRL concepts.
•	referenceLink & referenceArc for associating XBRL concepts with references to authoritative literature.
•	calculationLink & calculationArc for defining arithmetic relationships between XBRL concepts.
•	definitionLink & definitionArc for defining miscellaneous logical relationships between XBRL concepts.
•	presentationLink & presentationArc for organising XBRL concepts into trees for presentation.

While these constructs are extremely 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 document 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 2.1 Specification.  In particular, section 3.5, which defines the general semantics for XBRL relationships (how they are defined, partitioned, prohibited, and reintroduced) and section 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 document 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 provided in Appendix A.

Finally, in Appendix B, this document provides some non-normative guidance for the creation of custom linking constructs.
1.1  Document conventions
Throughout this document elements, attributes, and namespaces are shown in monospace.  For brevity, the following namespace-prefix bindings are used:

gen	http://xbrl.org/2007/generic	
link	http://www.xbrl.org/2003/linkbase	
xlink	http://www.w3.org/1999/xlink	

2. Generic Linking Components
This section defines some concrete linking components that can be used to establish relationships involving arbitrary XML elements.
2.1  The gen:link element
The gen:link element is an XBRL extended link with namespace “http://xbrl.org/2007/generic” and local name “link”.  Its Schema definition is provided normatively in Appendix A.

The gen:link element can be used in any XBRL linkbase [XBRL 3.5.2], subject to the restrictions imposed by xlink:role attributes on linkbaseRef elements that reference the linkbase [XBRL 4.3.4].
2.1.1  Locators in gen:link elements
Although the generic link Schema allows any element substitutable for link:loc to appear within a gen:link element, users should be aware that DTS discovery [XBRL 3.2] is only defined for link:loc.  Any schema or linkbase document referenced only by link:loc locators will not be included in the DTS, and will not be processed as an XBRL taxonomy document.

The targets of the xlink:href attributes on link:loc elements in gen:link elements are left unconstrained by this specification; locators in gen:link elements are free to point at arbitrary XML elements.
2.1.2  xlink:role attributes on gen:link elements
The xlink:role attribute serves the same purpose on gen:link elements 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.

Except for the standard extended link role value, http://www.xbrl.org/2003/role/link, the XBRL specification requires xlink:role values on standard extended links to be declared by roleType elements [XBRL 5.1.3] resolvable through roleRef elements [XBRL 3.5.2.4].  This specification imposes no such requirement.  However, it does require that processors honour the usedOn constraints of any roleType that is provided.

Constraint (role-res): If the value V of an xlink:role attribute on a gen:link element matches the value of a roleURI attribute on a link:roleRef sibling of the gen:link element, then 

1)	the xlink:href attribute of the roleRef element MUST identify a roleType element with V as the value of its roleURI attribute, and 
2)	a usedOn child of the roleType element MUST contain a QName value with namespace “http://xbrl.org/2007/generic” and local name “link”.
2.2  The gen:arc element
The gen:arc element is an XBRL arc with namespace “http://xbrl.org/2007/generic” and local name “arc”.  Its Schema definition is provided normatively in Appendix A.

gen:arc elements will typically appear inside gen:link elements, but MAY appear elsewhere.
2.2.1  xlink:arcrole attributes on gen:arc elements
The XBRL specification defines a number of standard arcroles, and requires all other xlink:arcrole values used on standard arcs to be to be declared by arcroleType elements [XBRL 5.1.4] resolvable through arcroleRef elements [XBRL 3.5.2.5]. This specification imposes no such requirement.  However, it does require that processors honour the usedOn and cyclesAllowed constraints of any arcroleType that is provided.

Constraint (arcrole-res): If the value V of an xlink:arcrole attribute on a gen:arc element within a gen:link element matches the value of an arcroleURI attribute on a link:arcroleRef sibling of the gen:link element, then 

1)	the xlink:href attribute of the arcroleRef element MUST identify an arcroleType element with V as the value of its arcroleURI attribute, and 
2)	a usedOn child of the arcroleType element MUST contain a QName value with namespace “http://xbrl.org/2007/generic” and local name “arc”, and
3)	the cyclesAllowed constraints of the arcroleType MUST be enforced (according to the rules of XBRL section 5.1.4.3) for all networks of relationships with arcrole V.

3  References

[SCHEMA-1]   
World Wide Web Consortium.  
XML Schema Part 1: Structures.  
http://www.w3.org/TR/xmlschema-1/

[XBRL]  
Phillip Engel, Walter Hamscher, Geoff Shuetrim, David vun Kannon, Hugh Wallis.  
Extensible Business Reporting Language (XBRL) 2.1
http://www.xbrl.org/SpecRecommendations/ 

[XLINK]  
Steve DeRose, Eve Maler, David Orchard  
XML Linking Language (XLink) Version 1.0.  
http://www.w3.org/TR/xlink/ 
Appendix A - Schema (normative)
<?xml version="1.0" encoding="UTF-8"?>

<schema 
  targetNamespace="http://xbrl.org/2007/generic"
  xmlns:gen="http://xbrl.org/2007/generic"
  elementFormDefault="qualified"
  xmlns:xl="http://www.xbrl.org/2003/XLink"
  xmlns:link="http://www.xbrl.org/2003/linkbase"
  xmlns="http://www.w3.org/2001/XMLSchema"
  >

<import 
    namespace="http://www.xbrl.org/2003/XLink"
    schemaLocation="http://www.xbrl.org/2003/xl-2003-12-31.xsd" />

  <import 
    namespace="http://www.xbrl.org/2003/linkbase"
    schemaLocation="http://www.xbrl.org/2003/xbrl-linkbase-2003-12-31.xsd" />

  <element name="arc" id="arc" substitutionGroup="xl:arc">
    <complexType>
      <complexContent>
        <extension base="xl:arcType">
          <attribute name="id" type="ID" />
        </extension>
      </complexContent>
    </complexType>
  </element>

  <complexType name="linkType" >
    <complexContent>
      <restriction base="xl:extendedType" >
        <choice minOccurs="0" maxOccurs="unbounded" >\
          <element ref="xl:title" />
          <element ref="xl:documentation" />
          <element ref="link:loc" />
          <element ref="xl:arc" />
          <element ref="xl:resource" />
        </choice>
        <anyAttribute namespace="http://www.w3.org/XML/1998/namespace" processContents="lax" />
      </restriction>
    </complexContent>
  </complexType>

  <complexType name="linkTypeWithOpenAttrs" >
    <complexContent>
      <extension base="gen:linkType" >
        <anyAttribute namespace="##other" />
      </extension>
    </complexContent>
  </complexType>

  <element name="link" id="link" substitutionGroup="xl:extended"
    type="gen:linkTypeWithOpenAttrs">
  </element>

</schema>

Appendix B – Defining Custom Linking Components (non-normative)
B.1  Custom extended links
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 an extended link whose sole purpose is to force discovery of a document:

<element name=”documentRef”>
  <complexContent>
      <restriction base="xl:extendedType" >
        <sequence>
          <element ref="xl:documentation" minOccurs=”0” />
          <element ref="link:loc" />
        </sequence>
        <anyAttribute namespace="http://www.w3.org/XML/1998/namespace" processContents="lax" />
      </restriction>
    </complexContent>
</element>

XBRL forbids the use of link:linkbaseRef within linkbases, but a locator within a documentRef achieves the same effect.  Here it is not appropriate to include resources and arcs; the content model only allows a single locator, and an optional documentation element.
B.2  Custom arcs
While you will rarely need to define custom extended links, it is useful to create a custom arc whenever you want to define a type of relationship that has required attributes.  In this way, the occurrence constraints can be specified using XML Schema [SCHEMA-1].
B.3  Custom resources
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 link:label, but used in conjunction with gen:link and gen:arc 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.