Extensible Enumerations 1.1

Candidate Recommendation 30 November 2016

Copyright © XBRL International Inc., All Rights Reserved.

This version:
<http://www.xbrl.org/Specification/extensible-enumerations-1.1/CR-2016-11-30/extensible-enumerations-1.1-CR-2016-11-30.html>
Editors:
Masatomo Goto, Fujitsu Laboratories of Europe <masatomo.goto@uk.fujitsu.com>
Richard Ashby, CoreFiling Ltd <rna@corefiling.com>
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
Contributor:
Mark Goodhand, CoreFiling Ltd <mrg@corefiling.com>

Status

Circulation of this Candidate Recommendation is unrestricted. This document is normative. Other documents may supersede this document. Recipients are invited to submit comments to spec@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.

Abstract

This specification allows domain member networks, previously used for dimensions, to constrain the allowed values for primary reporting concepts, enabling taxonomy authors to define extensible enumerations with multi-language labels.

Comment

1 Paul Warren:The working group would welcome feedback on whether there is a need for a mechanism to require that lists have at least one item in them.

Table of Contents

1 Introduction
1.1 Relationship to other work
1.2 Namespaces
2 Constraints on enumeration concepts
3 Validating facts for enumeration concepts

Appendices

A References
B Schemas (normative)
B.1 extensible-enumerations-1.1.xsd
C Intellectual property status (non-normative)
D Acknowledgements (non-normative)
E Document History (non-normative)
F Errata Corrections incorporated in this document

Table

1 Namespaces and namespace prefixes

Definitions

domain head
domain of enumeration values
enumeration concept
Publication URL

Error codes

enumte:InvalidDomainError
enumte:MissingDomainError
enumte:MissingLinkRoleError

enumie:InvalidFactValue
enumie:InvalidListFactValue


1 Introduction

XML Schema's xs:enumeration feature allows enumerated types to be defined. Such types have a fixed list of allowed values that cannot be changed until the next version of the schema is published. XBRL projects often require "extensible enumerations", which leave extension taxonomies free to augment the list of allowed values for a concept, just as they are free to add new members to the domain of an explicit dimension.

For multi-language projects, it is also important that labels can be provided for the enumeration values in each language.

Finally, it is often useful to refer to existing domain hierarchies in fact values. For example, a taxonomy might define a Region dimension, with members representing various countries. As well as using these members to qualify facts (e.g. "Sales in France" versus "Sales in Spain"), the taxonomy may define concepts that expect countries as values (e.g. a "Head office location" concept). Taxonomy authors should be free to define a domain of countries once, and use it in both contexts.

This specification provides a syntax for associating a concept with a domain of members, and validation rules to constrain the allowed values for the concept to the members of that domain. This meets the extensibility, labelling and reuse requirements outlined above.

1.1 Relationship to other work

This specification is a new version of [EXTENSIBLE ENUMERATIONS 1.0], created in order to address the requirement for enumerated items that may take more than one value. The requirements for this are documented more fully in the accompanying requirements document. This version is a new specification identified by a new namespace, and does not alter the behaviour required of a processor supporting [EXTENSIBLE ENUMERATIONS 1.0].

This specification depends upon the XBRL Specification [XBRL 2.1] and the XBRL Dimensions Specification [DIMENSIONS]. In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.

1.2 Namespaces

This Specification uses a number of namespace prefixes when describing elements and attributes. These are:

Table 1: Namespaces and namespace prefixes
Prefix Namespace URI
enum http://xbrl.org/CR/2016-11-30/extensible-enumerations-1.1
enumte http://xbrl.org/CR/2016-11-30/extensible-enumerations-1.1/taxonomy-errors
enumie http://xbrl.org/CR/2016-11-30/extensible-enumerations-1.1/instance-errors
xs http://www.w3.org/2001/XMLSchema

2 Constraints on enumeration concepts

An enumeration concept is a concept with a data type of enum:enumerationItemType, enum:enumerationsItemType, or a type derived from one of these types.

The following constraints apply to all enumeration concept declarations:

  1. The @enum:domain attribute MUST be specified. If this condition is not satisfied, enumte:MissingDomainError MUST be raised.
  2. The value of the @enum:domain attribute MUST identify a concept in the taxonomy that is in the xbrli:item substitution group and not in the xbrldt:hypercubeItem or xbrldt:dimensionItem substitution groups. If this condition is not satisfied, enumte:InvalidDomainError MUST be raised.
  3. The @enum:linkrole attribute MUST be specified. If this condition is not satisfied, enumte:MissingLinkRoleError MUST be raised.
  4. The optional @enum:headUsable attribute MAY be specified to control whether the member identified by @enum:domain should itself be included in the domain.

The domain head is the item identified by the @enum:domain attribute on an enumeration concept declaration.

The domain of enumeration values for an enumeration concept is the set of usable domain members obtained by following domain-member relationships starting from the domain head in the extended link role identified by the @enum:linkrole attribute. If the concept has an @enum:headUsable attribute with an effective value of 'true', then the domain of enumeration values also includes the domain head, otherwise it does not.

The domain is obtained by following the rules defined for obtaining a domain of valid members for an explicit dimension as defined in [DIMENSIONS].

Within [DIMENSIONS] the domain-member relationships that form a domain have the attribute @xbrldt:usable to provide a way of excluding members from the domain. But because @xbrldt:usable only applies to the target of an effective domain-member relationship, the @enum:headUsable attribute exists to provide a way to exclude the head member itself. This is required because no incoming arcs which have the domain head as their target are taken into account when establishing the domain of enumeration values.

3 Validating facts for enumeration concepts

Facts reported against enumeration concepts with a data type that is, or is derived from, enum:enumerationItemType and with a non-nil value MUST have a value that is a QName identifying a member in the domain of enumeration values for the concept. enumie:InvalidFactValue MUST be raised if this condition is not satisfied.

Facts reported against enumeration concepts with a data type that is, or is derived from, enum:enumerationsItemType and with a non-nil value MUST have a value that is a space-separated list of QNames, each of which identifies a member in the domain of enumeration values for the concept. The list of QNames MAY be empty. [Paul Warren: The working group would welcome feedback on whether there is a need for a mechanism to require that lists have at least one item in them.] enumie:InvalidListFactValue MUST be raised if this condition is not satisfied.

Note that the schema definition for enum:enumerationsItemType has the whiteSpace facet set to collapse. This means that QNames in the list may be separated by any string of whitespace characters, and that the list may be preceded by, or followed by, any number of whitespace characters.

Appendix A References

DIMENSIONS
XBRL International Inc.. "XBRL Dimensions 1.0"
Ignacio Hernández-Ros
, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XDT-REC-2006-09-18.htm)
EXTENSIBLE ENUMERATIONS 1.0
XBRL International Inc.. "Extensible Enumerations 1.0"
Masatomo Goto
, and Richard Ashby.
(See http://www.xbrl.org/Specification/ext-enumeration/REC-2014-10-29/ext-enumeration-REC-2014-10-29.html)
URI
IETF (Internet Engineering Task Force). "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"
T. Berners-Lee
, L. Masinter, and R. Fielding.
(See http://tools.ietf.org/html/rfc3986)
XBRL 2.1
XBRL International Inc.. "Extensible Business Reporting Language (XBRL) 2.1 Includes Corrected Errata Up To 2013-02-20"
Phillip Engel
, Walter Hamscher, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XBRL-2.1/REC-2003-12-31/XBRL-2.1-REC-2003-12-31+corrected-errata-2013-02-20.html)
XML Schema Datatypes
W3C (World Wide Web Consortium). "XML Schema Part 2: Datatypes Second Edition"
Paul V. Biron
, and Ashok Malhotra.
(See http://www.w3.org/TR/xmlschema-2/)
XML Schema Structures
W3C (World Wide Web Consortium). "XML Schema Part 1: Structures Second Edition"
Henry S. Thompson
, David Beech, Murray Maloney, and Noah Mendelsohn.
(See http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/)

Appendix B Schemas (normative)

This section contains XML files that form part of this specification. Each document has a standard Publication URL, at which the normative copy of the document is published. A non-normative copy of each document is included in this appendix for convenience.

All references to these documents made for the purposes of DTS Discovery MUST resolve to the Publication URL, after applying XML Base processing (where applicable) and resolving any relative URLs.

It should be noted that the path component of a URL is case-sensitive, and so must match exactly. Further, alternative hosts and schemes that happen to resolve to the same location are not considered equivalent and may not be used. See [URI] for more details on URL equivalence.

The requirement to reference documents by Publication URL does not prevent processors from substituting local copies of the documents for performance or other reasons.

XBRL taxonomies using this specification MAY import extensible-enumerations-1.1.xsd schema and MUST be schema valid according to the schema validation rules defined in [XML Schema Structures] and [XML Schema Datatypes].

XBRL instances using the elements whose type is defined in extensible-enumerations-1.1.xsd MUST be XML Schema valid according to validation rules defined in [XML Schema Structures] and [XML Schema Datatypes].

B.1 extensible-enumerations-1.1.xsd

<schema
  xmlns
="http://www.w3.org/2001/XMLSchema"

  xmlns:enum
="http://xbrl.org/CR/2016-11-30/extensible-enumerations-1.1"
targetNamespace="http://xbrl.org/CR/2016-11-30/extensible-enumerations-1.1" elementFormDefault="qualified">
<import namespace="http://www.xbrl.org/2003/instance" schemaLocation="http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd"/>
<attribute name="domain" type="QName"/>
<attribute name="linkrole" type="anyURI"/>
<attribute name="headUsable" type="boolean" default="false"/>
<annotation>
<documentation> enumerationItemType specializes QNameItemType. The content of a fact of this type MUST be a QName denoting an xbrl concept in the xbrli:item substitution group and which appears in the domain of enumeration values identified by the attributes on the enumerationItemType. </documentation>
</annotation>
<complexType name="enumerationItemType" id="enumerationItemType">
<simpleContent>
<restriction base="xbrli:QNameItemType">
<attributeGroup ref="xbrli:nonNumericItemAttrs"/>
</restriction>
</simpleContent>
</complexType>
<annotation>
<documentation> enumerationsItemType is a list equivalent of enumerationItemType. Its format is intended to be equivalent to an XML Schema list of QNames. The XBRL v2.1 specifications prevents the derivation of item types that uses XML Schema lists, so this type simulates it using a string-based type. </documentation>
</annotation>
<complexType name="enumerationsItemType" id="enumerationsItemType">
<simpleContent>
<restriction base="xbrli:tokenItemType">
<pattern value="\s*[\i-[:]][\c-[:]]*:[\i-[:]][\c-[:]]*(\s+[\i-[:]][\c-[:]]*:[\i-[:]][\c-[:]]*)*\s*"/>
<attributeGroup ref="xbrli:nonNumericItemAttrs"/>
</restriction>
</simpleContent>
</complexType>
</schema>

Appendix C Intellectual property status (non-normative)

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).

Appendix D Acknowledgements (non-normative)

This document could not have been written without the contributions of many people.

Appendix E Document History (non-normative)

DateAuthorDetails
12 October 2016Paul Warren

Initial Public Working Draft of version 1.1, addressing requirement for multi-valued enumerations.

30 November 2016Paul Warren

Candidate Recommendation of version 1.1 released. Base type of "enumerationsItemType" changed to "tokenItemType".

Appendix F Errata Corrections incorporated in this document

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 Specification Maintenance Working Group (SWG) up to and including 30 November 2016. 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.