1 Introduction
This document specifies semantics and syntax constraints for XBRL tables. XBRL tables define subsets of the facts and fact related information, defined by a DTS, and specify representation of those facts in a Cartesian coordinate system.
XBRL Tables can be used alone, by tools and consuming applications, or as part of containers in XBRL documents that generate complete reports.
Table concepts are defined by abstract concepts and concrete concepts, in a manner that provides a base for extension specifications.
XBRL tables specify semantics and syntax of hierarchical representations of facts that instantiate the concepts in XBRL taxonomies. These hierarchies are one of the basic building blocks of the specification, but also constitute by themselves a vehicle to communicate the meaning of those reporting concepts in a similar approach to that of the presentation linkbase, but enhanced to cover multidimensional information and more complex models.
2 Class Models
The figures below provide a model of XBRL table classes and a model showing how XBRL Tables can, as an example of their use, participate in XBRL rendering semantics.
3 Tables
A table represents selected instance facts defined by a DTS and provides a reference representation of those facts following a matrix layout in a Cartesian space with a determined number of axes involved, including data provided by parameters and data derived from these facts.
[Victor Morilla: An alternative definition would ensure that the table linkbase is not instance specific. A possible alternative would describe a table as representing selected facts from a "universe of facts" ]
[Victor Morilla: A table represents facts. Only facts. That does not mean that we can render fact related information using formatting rules; but formatting rules are not part of this specification. Moreover, a market tool could render the value and its unit, provide a popup window to display footnotes and let the user decide, using application options, whether to represent other properties. An open question is whether it is necessary to force users to provide all those details in a taxonomy. ]
[Hugh Wallis: The above comments will be resolved following feedback from within the Working Group and from the public]
The data defined by a table is referred to as the domain of the table. Both the domain of a table and the mapping to Cartesian space are specified by axes and table-axis relationships. Additional constraints can be imposed to the domain of a table with the help of filters.
Facts that may participate in the domain of a table are identified by their aspects, according to its aspect model.
[Hugh Wallis: It is still under discussion as to whether the following 2 sentences should be included here. Omitting them would serve to generalise this specification and not tie it to rendering specifically.]
The rendering of a fact defaults to rendering its unscaled value. One can also render transformed and scaled values and fact-related data (such as attributes of the fact, values of its instance aspects, footnotes), and DTS information for the fact (element attributes, related resources, and relationship attributes).
Non-fact data allows representation of financial reports, and may selected for inclusion by named aspects dynamically into the domain of a table. This may include information from the instance, such as from contexts, footnotes, and custom attributes, corresponding information from the DTS, such as concepts based on their inter-relationships. Non fact data may also be incorporated into the rendering process by parameters, to provide information to the rendering processor such as report dates, title, and selection parameterization.
Multiple instances may participate in a manner that is still to be determined.
[Hugh Wallis: The WG has not addressed this point yet - one suggestion is to integrate with multiple-instances formula features using selection axis. Feedback on this point is welcomed.]
A table's semantics specify how data in its domain, split and categorized by specified aspects and named selections, are mapped to positions on the table axes. The aspects establish the layout along each axis. The domain of the table is determined by the Cartesian product of the sets of allowed combinations of each axis that meet the conditions defined by the filters of the table.
A fact is said to belong to a table if its aspects meet all the constraints expressed by the axes of the table.
4 Axes
An axis (plural: axes) represents a set of combinations of the values of a subset of the aspects of the data, and a certain arrangement of them along an imaginary line.
[Hugh Wallis: Feedback is sought on whether this is understandable or whether re-wording would be helpful.]
These aspects are referred to as the aspects covered by the axis.
Each one of the possible combinations of aspect values of an axis is referred to as a coordinate.
The axis type specifies the display orientation of its coordinates. This specification provides for three axis types: x-axis, y-axis, and z-axis. The x-axis represents a horizontal arrangement of columns in a table, the y-axis represents a fourth-quadrant vertical progression of rows (except for right-to-left language cultures, where it is third-quadrant), and the z-axis represents an orthogonal axis of choices constraining the two-dimensional view. The x-axis horizontal column progression may be left-to-right, or right-to-left for tables in right-to-left language cultures (e.g. Arabic and Hebrew, to correspond to spreadsheet behaviour). The y-axis vertical column progression is always top to bottom. The z-axis may have multiple values, which can be used either for selection of display (such as by combo-boxes on a GUI) or for multiple tables (such as selected by tab, or output as successive document components).
Aspects that can be covered for facts include those of the dimensional and non-dimensional aspect models Aspects that can be covered for non-fact data include only the concept aspect.
Aspect coverage can be specified by axes in a manner that allows a table to be used for either entry or display for fact data, and in a manner that allows a table to be used for only display of non-fact data (such as DTS relationships). (e.g., a table can be used for entry of instance data but not for entry of taxonomies.).
A fact matches an axis coordinate if, for every aspect covered by the axis, each aspect value of the fact corresponds to the aspect specified for the coordinate.
The aspects covered by an axis MUST be consistent with the aspect model specified by the aspect model identifier of the table.
Error code xbrlte:axisAspectModelMismatch MUST be thrown if the processing software encounters an axis covering aspects that are not defined in the aspect model of the table.
Every coordinate in an axis must provide a means of identifying values for each aspect covered by the axis. When a table is used for entry, each value must be deterministic; when used for display, values can be expressed by filtering.
Error code xbrlte:aspectValueNotDefinedByCoordinate MUST be thrown if the processing software encounters a coordinate that does not specify or provide a means for identifying values for an aspect covered by its axis.
The set of axes of a table is determined by table-axis relationships between the table and its axes, as specified in Section 10.
A single axis may specify multiple aspects and is linear, multiple of the same axis are combined as a cross-product. (e.g., a single axis type of two dimensions may provide specific values of each dimension for each linear position, but two axes of one dimension each specify that the cross product of dimension values are to be displayed or entered.)
Two or more axes of a table MUST NOT cover common aspects.
Error code xbrlte:axisAspectClash MUST be thrown if the processing software encounters two axes in a table that cover common aspects.
Error code xbrlte:axisDefinesNoAspects MUST be thrown if the processing software encounters one axis with no aspects.
The aspects covered by a table are the union of the aspects covered by the axes of the table.
An ordered coordinates graphical representations of axes represents its coordinates along an imaginary line following a certain order. The position of a coordinate in a graphical representation of an axis is an integer number expressing where the coordinate lies in the ordered representation.
Axis headers label the axes to communicate heading information about the cells at the intersection of rows and columns. Header information for a column is displayed at the top of a column. Header information for a row is displayed at the left of a row except for right-to-left tables, where it is displayed on the right of the row. The location to display z-axis and table headers is not constrained by this specification, but would usually be at the top of the table. Axis headers for axis types that have multiple coordinate aspect values may use row and/or column spanning to graphically provide clarity of aspect coverage. Axis header information may be simplified when tables are rendered on media not meant primarily for human readability (such as CSV files, which lack a way to span or merge column headers).
Scrolling of tables may follow spreadsheet expectations, e.g., horizontal scrollbar on bottom, vertical on right for left-to-right tables and on left for right-to-left tables. A table rendering for human consumption may provide a way to fix row and column headers and allow cells to be scrolled independently.
The position of a coordinate in a set of axes of the same type is defined as the cardinality of the set of previous coordinates plus one. There may be multiple axes of the same type (such as multiple x axes where the coordinates are combined. A coordinate position is relative to the combined set of axes of the same type.
[Hugh Wallis: The above two paragraphs are still under discussion as they tend to tie this specification closely to the specific rendering use case.]
Axes can be classified into two groups: predefined and open axes
4.1 Predefined Axes
A predefined axis is an axis that fulfills the following requirements:
Error code xbrlte:predefinedAxisZeroCardinality MUST be thrown if the processing software encounters a predefined axis whose cardinality is zero.
[Herm Fischer: Need further research. It is possible that this can only apply to the aspectRuleAxis when dimension members are not involved, but otherwise it is common to have tree branches with no leafs, particularly where multiple choices of member or taxonomy namespace years may be involved.]
The figure below provides a model of the predefined axis.
An predefined axis is able to both specify how an input instance has its facts mapped to the coordinates of a table, and how newly entered facts on a table can be output into a (new) instance. The rules of this axis must be specified in a manner that allows their isomorphic use (rather than in a way that constrains them to table display only).
An predefined axis member represents a component in the header of the axis and determines the values of the aspects of the coordinates in the axis.
The tree of members of an aspect rule axis is established through axis-member relationships.
(No cycles are allowed, so the relationships must form a tree.)
The parent of a member C is the node source of an axis-member relationship whose target is the member C.
The root of all axis-member relationships in an aspect rule axis is the axis node itself.
The children (singular: child) of a member P are the axis elements in the target of axis-member relationships whose source is the member P.
An abstract member is a predefined axis member that has the attribute @abstract set to true.
4.1.1 Coordinates Order
Each non-abstract member in an aspect rule axis corresponds to an axis coordinate. The cardinality of an aspect rule axis is equal to the number of non-abstract members.
The order of the coordinates is defined in terms of the order of members of the predefined axis. The order of members is defined as follows:
- The order between members with a common parent is determined by the order of its the effective relationships.
-
The order between a node and its children depends on the value of the
@parentChildOrderattribute of the axis. This attribute establishes whether node children corresponding coordinates are placed before or after the coordinate corresponding to the parent (e.g., parent before children would put a total before breakdowns, and the converse would put the total after the breakdowns).
4.2 Open Axes
An open axis is an axis that fulfills the following requirements:
Error code xbrlte:openAxisDefinesMultipleAspects MUST be thrown if the processing software encounters an open axis that covers more than one aspect.
The Filter axis and Selection axis are examples of open axes. These are described in their separate respective documents.
4.3 Axis Requirements
The concept of axis defined in this specification is abstract, and thus, it is meant to be extended by other specifications in charge of defining concrete implementations of axes. This chapter defines the set of requirements that those specification must follow.
- Axes implementations MUST provide a definition of the aspect(s) covered
- The source of context items, if different from ‘facts in instance’ filtered by the table filter, z-axis constraints as a filter, opposite-orientation axis constraints, and other coordinates of the same type axis (e.g., the other x-axes if this is an x axis).
- Rendering transform if other than string (e.g., scaling, numeric transformation, general formatting)
5 Table Filters
Tables can be associated to filters through table-filter relationships. (A filter axis also has a fiter, described in the filter axis specification.)
The domain of the table is limited to those facts that meet the conditions defined by all the filters of the table. A filter may be complemented, by an attribute on the table-filter relationship, which simply inverts the filter’s effect. (For example, a dimension filter listing specific dimension member(s) but complemented, excludes facts with those members from the domain of the table.)
The context item for XPath expressions of table filters is each candidate fact being considered to meet the conditions that would make it an accepted member of the domain of the table.
6 Table Source
The source for input domain to a table is the domain objects considered for table filter matching, axes coordinate matching, and display in a cell value. The source for a table used as an entry form is an instance that does not have the facts to be input (or may have facts with earlier values, to be edited). A minimum source is an empty instance document, with contexts and units existing as needed for aspects of data to be entered.
7 Graphical Representation of Tables
This specification provides a means to associate data with coordinate positions for rendering in a manner independent of presentation formatting. Issues of font select, color, background, component assembly into documents, are left for the XBRL Rendering Specification. This specification does, however, provide for scaling, number transformation, and coordinate axes ordering.
Table-axis relationships include an attribute to help the taxonomy author to specify the representation of the axis of the table in reference a bi-dimensional space.
This attribute ( @axisType) specifies the Cartesian axis where the table axis should be projected on to. The possible values are:
- x-axis: axes projected on to the x axis should be represented along an horizontal line, from left to right, or right to left, according to the language culture.
- y-axis: axes projected on to the y axis should be represented along a vertical line in the fourth quadrant (rows from top to bottom), or third quadrant (for right-to-left language cultures).
- z-axis: axes projected on to the z axis should be represented in axes perpendicular to the plane defined by x and y axes, but are rendered either by user selection of a z-value for a specific table rendering choice, or as a sequence of two-dimensional displays (given flat-surface rendering devices).
8 Set of Coordinates
A set of coordinates is a list of zero or more aspects (reference to the variables specification) and values for those aspects. A set of coordinates MUST contain only a single value for each aspect included. Those aspects and their respective values are referred to as explicit aspect values of the set of coordinates.
A set of coordinates MAY contain labels and references as well. Those labels and references MAY be generic ones (references to generic labels and references) or standard ones (references to XBRL 2.1) depending on the specific representation of the set of coordinates. Nevertheless, these labels and references are to be treated in the same way no matter their syntactic representation.
A generic or standard label for a coordinate provides the row or column header ordinary label. It may be provided in multiple languages, but using the standard label role. Additional labels may include references and header codes, which render in additional row header or column header cells, in order of their relationships. If there is at least coordinate on any type of axis with such additional labels, columns are reserved for all other headers on that type of axis (e.g., if one x-axis column coordinate a reference label, all the column headers will have a reference label cell, even if empty).
A set of coordinates can be abstract. This property will have consequences on the way it is rendered on a table, according to the class of axis (For predefined axes where the aspect represents a breakdown, the non-abstract coordinates will reserve an additional coordinate value for their total).
9 Predefined Axis
An axis is an ordered tree of sets of coordinates. A set of coordinates, in the context of an axis, has a set implicit aspect values; these aspect values are those aspect values (explicit or implicit) of its parent set of coordinates that are not explicitly defined at the child. The aspect values of a set of coordinates in the context of an axis are the union of its explicit aspect values plus the implicit ones.
An axis MUST define a traverse order for the tree of sets of coordinates that conforms the axis. This order is important when a set of coordinates represents a hierarchy of data, such as a dimension with a default representing a total, and members representing breakdown values, or a linkbase of aggregative sums and their breakdown details. The order is either parents first (total at top of breakdown items) or children first (total below breakdown items).
10 Syntax
Axes are represented by elements in the substitution group for the abstract <table:axis>
element.
This specification does not provide any specific axis element, but provides the base for other specifications that define specific axes elements.
An axis element and an predefined axis member element may furthermore specify these attributes:
[Victor Morilla: This will probably be moved from ths specification into the rendering specification. However it is left in this draft to indicate to reviewers the direction of the WG thinking on the application of this specification to rendering.]
@value: An XPath 2 expression to specify an output XPath expression intended to select information related to fact, such as an attribute of the fact, context, footnote, or any DTS information obtainable by Function Registry or custom function, parameter, and reference to any selection axis in effect for the coordinates being rendered.
If@valueis specified, the coordinate is output only, and cannot be used as an form entry cell.
If@valueand@formatare both specified, the@valueXPath expression result is passed to the@formattransformation for rendering (e.g., to select a numeric or date from attribute, context value, or footnote resource and perform indicated transformation on it.)@scale: An integer to specify scaling (powers of 10) on output rendering and input from an entry form.@negate: A Boolean to specify that a numeric rendered (output), or edited value (on input) is sign-flipped from the value in the instance. Corresponds to negated label roles in presentation linkbases, to support display of balance sheet items that also appear in cash flow statements (where some require sign flipping).@format: A QName of a transformation registry transform. Transforms are applied both on output and input. Formatting is also possible by using thexfi:format-numberor any other function in@value, which would restrict the coordinate cell to output rendering only.
The context item for @value is the fact selected for a coordinate (predefined axes), or the selection sequence item (selection axes).
These attributes are inherited (when used in predefined axes and members), so that a @format, @scale, or @negate
may be specified on an ancestor, and need not be respecified on descendant coordinate member elements.
However descendants re-specifying an attribute override any attribute value inherited (or cancellation of an inherited attribute
is specified by an empty string attribute value).
11 Processing model (definition of functions)
A table linkbase is compiled (prepared for processing) by analysing the relationships from table to axes. It is executed by preparing header information, processing its domain (such as facts from an instance) to the facts, assigning values to cells as facts match coordinates of the rows and columns of the cells, and possible compaction for viewing (removal of axes having no data in sparse matrices).
The compilation process may analyse axes by their type (z-axis, x-axis, and y-axis types) to find the axes of those types and evaluate their coordinates (those that can be determined in the absence of processing facts). Aspect clashes can be identified, XPath expressions can be compiled and checked for references to existing parameters and any variables allowed, and for the case of predefined axes, the number of coordinates along the x- and y-axes types identified.
The execution process may prepare headers for x-axis and y-axis types. If data (source facts) exist, they may be mapped to coordinates, and open axes processed to determine aspect population. Column and row coordinates of open axes may be allocated deterministically in advance for explicit dimension data, but must be allocated after analysing data when applying to typed dimensions of unknown content values, or relationship axes that are determined dynamically.