Copyright © 2016, 2017 XBRL International Inc., All Rights Reserved.
Circulation of this Public Working Draft is unrestricted. This document is normative. Other documents may supersede this document. Recipients are invited to submit comments to formula-feedback@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.
This specification is an extension to the Formula Validation Specification [VALIDATION]. It defines elements and relationships that allow formula authors to associate assertions and assertion sets with an assertion set and control the processing of groups of assertions.
1 David Bell: Should the @name be made
mandatory ?
If authors forget to name their
assertions then they cannot be referenced in any
dependency definiiton. (Unless we add some extra arcs.)
2 David Bell: Is there a need to support an
assertion-set-parameter arc for consistency ?
Current consensus appears to be 'no'.
3 David Bell: Is there a need to reference
dependent assertion sets via arcs (rather than only via
QNames) for consistency ?
Consensus appears to be
'no'.
4 David Bell:This forces all dependencies and all
dependent assertion sets for a given assertion set to be
evaluated first. This ensures that all 'prior'
dependents on all dependency items are evaluated and it
is not possible to have partial evaluations that could
result in ambiguities for later processing.
5 David Bell:This allows full/partial evaluation
to be a policy decision rather than something that is
enforced by the taxonomy. It also avoids issues where
different parts of a taxonomy, due to extensions for
example, end up with differing behaviours that would
then require them to be overridden or modified to be
consistent.
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.5.1 Typographic conventions
1.5.1.1 Definition notation
1.5.1.2 Footnote notation
1.5.1.3 Element and attribute notation
1.5.1.4 Error code notation
1.5.2 Formatting conventions
1.6 Namespaces and namespace prefixes
1.7 XPath Usage
2 Syntax
2.1 Assertion Sets
2.1.1 Assertion-set relationships
2.1.2 Assertion-set-satisfied-message relationships
2.1.3 Assertion-set-unsatisfied-message relationships
2.1.4 Assertion Set Severity
2.2 Assertion Set Preconditions
2.2.1 Assertion-set-precondition relationships
2.3 Assertion Set Dependencies
2.3.1 Assertion-set-dependency relationships
3 Processing Model
3.1 Assertion Set Processing
3.2 Dependency Evaluation
3.3 Dependency Expression Evaluation
3.4 Multiple Dependencies
3.5 Assertion Set Evaluation
3.6 Assertion Set Precondition Evaluation
3.7 Assertion Evaluation
3.8 Formula Evaluation
A Schema and Linkbase
A.1 Assertion Set schema
B References
C Intellectual property status (non-normative)
D Acknowledgements (non-normative)
E Document history
F Errata corrections in this document
1 Namespaces and namespace prefixes
1 A normative example
2 A non-normative example
3 An example of poor usage
assertion evaluation
assertion set
assertion set dependency
assertion set evaluation not satisfied
assertion set evaluation result
assertion set name
assertion set not evaluated
assertion set precondition
assertion set processing
assertion set with no assertions
assertion set with no evaluations
assertion-set relationship
assertion-set-all-satisfied
assertion-set-dependency relationship
assertion-set-evaluation
assertion-set-precondition relationship
assertion-set-satisfied
assertion-set-satisfied-message relationship
assertion-set-unsatisfied-message relationship
dependency evaluation
dependency expression
dependent assertion sets
formula evaluation
formula processing
Publication URL
satisfied dependency condition
ase:assertionSetNameClash
ase:cyclicDependencies
ase:invalidDependency
ase:invalidDependencyReference
All formula assertions specifications ([VALUE ASSERTIONS], [EXISTENCE ASSERTIONS] and [CONSISTENCY ASSERTIONS]) define a standard XML-based syntax for validations on XBRL business reports.
The technical nature of an assertion is that the assertion is either "satisfied" or "unsatisfied". This specification adds a number of processing features to the assertion sets originally defined by the Validation [VALIDATION] specification:
This specification extends the suite of formula specifications without modifying any existing specifications.
This specification depends upon the XBRL Specification [XBRL 2.1], the XBRL Generic Link Specification [GENERIC LINKS] and the Formula Variables Specification [VARIABLES] which defines assertions resources. 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.
Comments which are informative, but not essential to the understanding of the point at hand, are provided in footnotes. All footnotes are non-normative.
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.
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.
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 |
|---|---|
as |
http://xbrl.org/PWD/2017-05-04/assertion-sets-2.0 |
ase |
http://xbrl.org/PWD/2017-05-04/assertion-sets-2.0/error |
eg |
http://example.com/ |
fn |
http://www.w3.org/2005/xpath-functions |
link |
http://www.xbrl.org/2003/linkbase |
xbrli |
http://www.xbrl.org/2003/instance |
xfi |
http://www.xbrl.org/2008/function/instance |
xbrldi |
http://xbrl.org/2006/xbrldi |
xbrldt |
http://xbrl.org/2005/xbrldt |
xl |
http://www.xbrl.org/2003/XLink |
xlink |
http://www.w3.org/1999/xlink |
xs |
http://www.w3.org/2001/XMLSchema |
xsi |
http://www.w3.org/2001/XMLSchema-instance |
gen |
http://xbrl.org/2008/generic |
variable |
http://xbrl.org/2008/variable |
iso4217 |
http://www.xbrl.org/2003/iso4217 |
XPath usage is identical to that in the XBRL Variables Specification [VARIABLES], except that the context item is undefined unless otherwise stated. Such XPath expressions allowed by this specification are evaluated with no context item to avoid the use of arbitrary XPath expressions which rely heavily on the XML of the instance.
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.
Assertion sets serve to define groupings of assertions for evaluation purposes by an XBRL formula processor.
An
assertion set is a resource expressed
by the <as:assertionSet> element.
Assertion set evaluation is the process of evaluating each assertion that is associated with the assertion set to produce an assertion evaluation result.
An assertion set evaluation result is a boolean value that is the aggregtion of all assertion evaluation results. .
The assertion set evaluation is satisfied if the evaluation
result of every referenced assertion is satisfied, in which
case the assertion set evaluation result is true.
The assertion set evaluation is unsatisfied if the
evaluation result of any referenced assertion is
unsatisfied, in which case the assertion set evaluation
result is false.
The optional
@name
on an assertion set declaration defines the
QName of the assertion set being declared. This QName
MAY be used within any assertion set
dependency to reference this assertion.
This QName MAY be used as a variable
within any assertion set dependency XPath expression
to reference the assertion evaluation result.
If an assertion set is not defined with a @name
attribute, it cannot be referenced within dependency
definitions.
[David Bell: Should the @name be made
mandatory ?
If authors forget to name their
assertions then they cannot be referenced in any
dependency definiiton. (Unless we add some extra arcs.)
]
Error code
ase:assertionSetNameClash
MUST be thrown if two assertion sets
in the discoverable taxonomy set have the same
QName specified by their @name attributes.
If an assertion is to be a member of the set of assertions referenced by an assertion set, then there MUST be an assertion-set relationship from the assertion set to the assertion for each assertion set.
An assertion-set relationship is a relationship between an assertion set and an assertion that is expressed by an XLink arc.
To declare an assertion-set relationship an XLink arc MUST:
http://xbrl.org/arcrole/PWD/2017-05-04/assertion-set The arcrole value, http://xbrl.org/arcrole/PWD/2017-05-04/assertion-set, is declared in the normative schema supplied
with this spcification.
Assertion-set relationships MUST be expressed by generic arcs as indicated by the restrictions imposed by the arcrole declaration in the normative schema. Violations of this requirement will be detected by validation against the XBRL Specification [XBRL 2.1].
An assertion MAY be associated with one or more assertion sets. Multiple relationships between the same assertion and assertion set pair are discouraged but permitted.
An assertion-set-satisfied-message relationship is a specific case of element-message relationship between an assertion-set and a message expressed by an XLink arc.
To declare an assertion-set-satisfied-message relationship an XLink arc MUST:
http://xbrl.org/arcrole/PWD/2017-05-04/assertion-set-satisfied-message The arcrole value, http://xbrl.org/arcrole/2010/assertion-set-satisfied-message, is declared in this normative schema.
Assertion-set-satisfied-message relationships MUST be expressed by generic arcs as indicated by the restrictions imposed by the arcrole declaration in the normative schema.
An assertion-unsatisfied-message relationship is a specific case of element-message relationship between an assertion-set and a message expressed by an XLink arc.
To declare an assertion-set-unsatisfied-message relationship an XLink arc MUST:
http://xbrl.org/arcrole/PWD/2017-05-04/assertion-set-unsatisfied-message The arcrole value, http://xbrl.org/arcrole/2010/assertion-set-unsatisfied-message, is declared in the normative schema for
messages.
Assertion-set-unsatisfied-message relationships MUST be expressed by generic arcs as indicated by the restrictions imposed by the arcrole declaration in this normative schema.
Relationships to assertion severities, as defined by the Assertion Severity Specification [ASSERTION SEVERITY], are not provided for assertion sets.
An assertion set precondition MAY be used to affect the evaluation of all assertions referenced by an assertion set.
An assertion
set precondition is a resource expressed by
the <variable:precondition> element.
The full definition of this element can be found in the Formula Variables Specification [VARIABLES].
Note that the definition of <variable:precondition>
allows the XPath expression to make reference to resources
that are either referenced by the variable resource
(assertion or fomula) via a declared relationship, or, for
parameters, referenced by their global QName.
As an assertion set is not a variable resource, its relationships are limited, correspondingly the XPath expression is also limited and may only make references to parameters by means of their global QName.
[David Bell: Is there a need to support an
assertion-set-parameter arc for consistency ?
Current consensus appears to be 'no'. ]
An assertion-set-precondition relationship is a relationship between an assertion-set and an assertion precondition that is expressed by an XLink arc.
To declare an assertion-set-precondition relationship an XLink arc MUST:
http://xbrl.org/arcrole/PWD/2017-05-04/assertion-set-preconditionPrecondition behaviour and syntax are defined and specified by the existing Formula Variables Specification [VARIABLES].
Assertion set dependencies serve to define the dependency relationships with respect to other assertion sets for the purposes of sequencing assertion set evaluations.
An assertion set
dependency is a resource expressed by the
<as:dependency> element.
The
@dependents attribute on a dependency
MUST contain a white space separated
list of one or more assertion set QNames. Each QName
value MUST refer to an assertion set of
the same name as defined by the @name of an
<as:assertionSet> element present within
the discoverable
taxonomy set.
No semantics are to be inferred from the order of the specified QNames.
When using fully qualified QNames, namespaces MUST be taken into account.
Error code ase:invalidDependency
MUST be thrown if a QName specified
by @dependents attribute cannot be resolved to
an assertion set of the same name.
The optional
@test attribute on a dependency contains
an XPath expression. Its content is referred to as a
dependency expression. If omitted, the
default value of the expression is true only
if all dependent assertion sets were
evaluated. See Section 3 for further details.
A satisfied
dependency condition is the result of the
evaluation of the XPath expression which evaluates to an
effective
Boolean value of true.
The XPath expression MAY reference the
results of other assertion sets using an XPath variable of
'$QName', on condition that the QName is specified in the
@dependents attribute.
Error code
ase:invalidDependencyReference
MUST be thrown if the XPath
expression makes reference to an assertion set result
QName that is not specified in the list defined by
@dependents.
[David Bell: Is there a need to reference
dependent assertion sets via arcs (rather than only via
QNames) for consistency ?
Consensus appears to be
'no'.]
An assertion-set-dependency relationship is a relationship between an assertion-set and an assertion dependency that is expressed by an XLink arc.
To declare an assertion-set-dependency relationship an XLink arc MUST:
http://xbrl.org/arcrole/PWD/2017-05-04/assertion-set-dependencyThis section defines key features of the processing model for all assertion sets.
Formula processing is defined as the complete set of operations to process all formula resources that MAY be defined within a discoverable taxonomy set. This includes all assertion sets, assertions and formula.
Assertion set processing is defined as the complete set of operations to process all assertion sets that MAY be defined in the discoverable taxonomy set.
Dependency evaluation is the process that ensures that any for a given assertion set, its dependent assertion sets have been processed and any dependency expression has been evaluated.
Assertion evaluation is the evaluation of a single assertion in accordance with the XBRL Formula Assertion Specifications, [CONSISTENCY ASSERTIONS], [EXISTENCE ASSERTIONS] and [VALUE ASSERTIONS].
Note that an assertion may produce zero or more evaluation results depending upon the number of successful binding sets.
Formula evaluation is the evaluation of a single formula in accordance with the XBRL Formula Formula Specification [FORMULA]
Within a given formula processing scenario there may be assertion sets, formula and assertions. Assertions MAY be associated with zero or more assertions sets. Formula MAY be associated with consistency assertions.
Processing MUST ensure that all assertion sets, assertions and formula are considered for evaluation and that all assertion set results, assertion results and formula outputs MUST only be reported once.
Formula processing completes when all assertion set processing is complete, and all assertions not associated with any assertion sets have been evaluated and all formula have been evaluated.
Assertion set processing completes when all assertion sets have been considered for evaluation.
Assertion set dependencies affect the evaluation of the assertion set and consequently the evaluation of the associated assertions.
Assertion set preconditions control the evaluation of the assertions associated with an assertion set.
Assertion set processing considers each assertion set in turn and attempts to evaluate the associated assertions in accordance with any assertion set dependency definitions and any assertion set preconditions.
A processor MAYdetermine the order of assertion set processing through static analysis of the discoverable taxonomy set before formula processing is performed, or it MAY be discovered dynamically during evaluation. In either case the results will be the same although the order of operations may not be.
If an assertion set has already been processed, then its outcome is known and it SHOULD not be processed again.
The dependencies for an assertion set MAY
be described by the optional <as:dependency>
elements and relationships. If there are no
<as:dependency> elements defined, then no
constraints are specified, otherwise dependency evaluation
is performed.
If there are no defined dependencies, or the dependency condition is satisfied, the assertion set will be evaluated and will produce an evaluation result.
If there are any assertion set preconditions, then any
associated assertions will only be evaluated if all
preconditon tests evaluate to true.
In the absence of any preconditions, or a precondition
evaluation result of true, assertion evaluation
is performed.
The results of assertion evaluation are then used to determine the result of the assertion set evaluation.
An assertion set evaluation is satisfied if any of the following are true:
An assertion set evaluation is unsatisfied if any associated assertion that is evaluated has an unsatisfied result.
An assertion set that is not evaluated, due to unsatisfied dependencies, does not produce an assertion set evaluation result.
Any assertion evaluation evaluation result that was produced is made available for subsequent assertion set processing.
Dependency evaluation is only performed if the assertion set is
associated with one or more <as:dependency>
elements. Otherwise the assertion set will be evaluated
and will produce an evaluation
result.
When an assertion
set is associated with a
<as:dependency> element, then its preceding
assertion sets are defined by the @dependents
attribute. A valid <as:dependency> element must
define at least one dependency.
Each dependent assertion set must be, or have already been, processed before the current assertion set can be processed. The order of processing for multiple dependents is undefined and implementation dependent.
Error code
ase:cyclicDependencies
MUST be thrown if circular references
are detected within the contents of
@dependents attributes of
<as:dependency> while processing the
dependency network.
Once all of the dependent assertion sets have been processed, the current assertion set dependency expression can be evaluated.
The optional dependency expression is defined by the
@test attribute and can be used to replace the
default expression to provide finer grained control of
assertion set processing.
In all cases the logical expression is an XPath expression that evaluates to an effective Boolean value to determine whether or not the assertion set will be evaluated.
In the absence of any explicit dependency expression, the assertion set will only be evaluated if all dependent assertions were evaluated and produced an assertion set evaluation.
The equivalent XPath expression is:
every $evaluation-result in
dependency-evaluation-results satisfies
exists($evaluation-result)
Where any assertion set that was not evaluated is assigned the empty sequence as its result, so that the XPath exists() function returns a value of false.
Thus if any of the dependent assertion sets were not evaluated, then the condition is not satisfied and the current assertion set will also not be evaluated.
If the @test atrribute is defined, then the
dependency
expression defined by the XPath expression
will be evaluated. The expression MUST
produce an effective Boolean value and
MAY reference the results of any
dependent assertion sets refernced by the
@dependents attribute, as well as any
parameters.
A result of true will cause the assertion set to
be evaluated.
In the case where an assertion set is related to multiple dpendencies, processing MUST consider each dependency in turn and MUST process all dependencies for an assertion set before processing any other assertion set.
An assertion set will therefore be evaluated if the logical
OR operation of multiple dependency expressions has an
effective result of true.
All dependent assertion sets and all dependency expressions MUST be evaluated before the assertion set can be evaluated, even if the result of the dependency expressions can be determined part way through.
[David Bell: This forces all dependencies and all dependent assertion sets for a given assertion set to be evaluated first. This ensures that all 'prior' dependents on all dependency items are evaluated and it is not possible to have partial evaluations that could result in ambiguities for later processing. ]
If the dependency expression evaluation is true
then the assertion set will be evaluated and will produce an
assertion set evaluation result.
Whether or not the assertions within the assertion set are evaluated MAY be subject to any assertion set precondition tests. See Section 3.6 for details.
The assertions referenced by the assertion set together with any dependent formula are evaluated in accordance with the XBRL Formula Specification [FORMULA]
If the assertion set is empty, in that it does not reference
any assertions, or none of the assertions were evaluated,
then the result of the assertion set processing will be
true as no assertions were evaluated as being
unsatisfied.
A conformant processor MUST always provide the ability to evaluate all assertions referenced by the assertion set. This is the default behaviour.
If an assertion evaluation is not satisfied then a processor MAY provide the capability of not evaluating any further assertions referenced by the assertion set.
The details of how this capability MAY be enabled is outside the scope of this specification and is implementation dependent.
[David Bell: This allows full/partial evaluation to be a policy decision rather than something that is enforced by the taxonomy. It also avoids issues where different parts of a taxonomy, due to extensions for example, end up with differing behaviours that would then require them to be overridden or modified to be consistent.]
Logically an assertion set precondition applies to every referenced assertion and will augment any existing assertion preconditions that MAY be attached to the assertion.
An assertion will only be evaluated if the evaluation result
of each of its preconditions is true.
As a consequence, if an assertion set precondition is
specified and the test evaluates to a value of
false then the assertions in the assertion
set will not be evaluated. The result of the assertion set
processing will be true as no assertions were
evaluated as being unsatisfied.
In the case where multiple assertion set preconditions are defined, the test result is the logical AND operation across all of the tests.
As assertion set resources cannot be linked to variables the contents of the XPath test is limited.
These limitations allow the assertion set precondition test to be evaluated as a true precondition that MAY be evaluated before any of the associated assertions. The test expressions may reference XPath constructs and functions, as well as parameters via their global QNames.
Assertion set processing will process all assertions
associated with the assertion set if neither of the dependency
expressions, if present, nor the assertion set
preconditions, if present, evaluate to
false.
The assertions associated with the assertion set are then processed individually in accordance with the appropriate XBRL specifications. This specification does not change nor augment any other existing specifications. The order of assertion evaluation is implementation dependent.
If an assertion has already been evaluated it SHOULD not be evaluated another time, however, processors are free to implement as they wish, but the assertion results MUST not include results of mutiple evaluations of either assertions or any associated formula.
Assertions that are not associated with any assertion sets are always evaluated. The point in time at which they are evaluated is implementation dependent.
Formula are always evaluated.
The order of formula evaluation is implementation dependent, the only constraints being those imposed by any consistency assertions.
If a formula has already been evaluated it SHOULD not be evaluated another time, however, processors are free to implement as they wish, but the formula output results MUST not include results from mutiple evaluation.
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.
The Publication URL for this document is: http://www.xbrl.org/PWD/2017-05-04/assertion-sets-2.0.xsd.
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).
This document could not have been written without the contributions of many people.
| Date | Author | Details |
|---|---|---|
| 08 December 2016 | Herm Fischer |
Initial draft. |
| 14 December 2016 | David Bell |
Reworked and reordered initial sections. Added precondition and dependency sections. Added content to processing model. |
| 04 January 2017 | David Bell |
Updates to processing model. |
| 05 January 2017 | David Bell |
Updates to schema. |
| 19 April 2017 | David Bell |
Updates to schema. |
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 Formula Working Group up to and including 04 May 2017. 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.