dom
All model group, so an xs:all element.
An xs:annotation element.
Anonymous complex type definition.
Anonymous complex type definition. It is a non-top-level xs:complexType element without any name attribute.
Anonymous simple type definition.
Anonymous simple type definition. It is a non-top-level xs:simpleType element without any name attribute.
Anonymous type definition, so either an anonymous complex type definition or an anonymous simple type definition.
Any element in a taxonomy schema or linkbase document, at any abstraction level.
Any element in a taxonomy schema or linkbase document, at any abstraction level. For example, the
type-safe DOM element types have this common super-type, but so does type ConceptDeclaration and
so do the type-safe DOM extensions for XBRL formulas and tables. The purpose of this type is to have a
common taxonomy DOM element abstraction that can be used in relationships.
An xs:appinfo element.
A link:arcroleRef element.
A link:arcroleType element.
Either a global attribute declaration or a local attribute declaration.
Either an attribute declaration or an attribute reference.
Attribute group definition, so a top-level xs:attributeGroup element with a name attribute.
Attribute group definition or attribute group reference.
Attribute group reference, so a non-top-level xs:attributeGroup element with a ref attribute, referring to an attribute group definition.
Attribute reference.
Attribute reference. It is an xs:attribute element referring to a global attribute declaration. It is not a direct child element of the xs:schema root element.
The key of a base set, made up by the EName and @xlink:arcrole of the arc, along with the EName and @xlink:role of the parent extended link.
The key of a base set, made up by the EName and @xlink:arcrole of the arc, along with the EName and @xlink:role of the parent extended link. Base set keys are essential for finding networks of relationships.
An XBRL calculation arc.
An XBRL calculation arc. It is a link:calculationArc element.
An XBRL calculation link.
An XBRL calculation link. It is a link:calculationLink element.
Super-type of schema components that can be abstract.
Element-scheme XPointer containing (only) a child sequence.
Element-scheme XPointer containing (only) a child sequence. The indexes in the child sequence are 1-based.
XLink child element of an extended link, so an XLink arc, locator or resource.
Choice model group, so an xs:choice element.
An xs:complexContent element.
Complex type definition, so either a named complex type definition or an anonymous complex type definition.
Concept declaration, wrapping a GlobalElementDeclaration.
Concept declaration, wrapping a GlobalElementDeclaration. It must be in substitution group xbrli:item or xbrli:tuple,
either directly or indirectly.
There are no sub-classes for domain members, because as global element declarations they are defined in the Dimensions specification in the exact same way that primary items are defined. Therefore primary items and dimension members are indistinguishable.
In order to build a ConceptDeclaration from a GlobalElementDeclaration, the builder needs a SubstitutionGroupMap as context.
The created ConceptDeclaration does not retain that used SubstitutionGroupMap. As a consequence, these concept declaration objects
only make sense in a context where the used substitution group map is fixed. In taxonomies that know their substitution group map, this
is clearly the case. In other words, outside the context of a taxonomy that knows its substitution group map, concept declarations
are not "portable" objects, whereas the underlying global element declarations are.
Concept-label resource.
Concept-label resource. It is a link:label element.
Concept-reference resource.
Concept-reference resource. It is a link:reference element.
Either simple content or complex content.
A link:definition element.
An XBRL definition arc.
An XBRL definition arc. It is a link:definitionArc element.
An XBRL definition link.
An XBRL definition link. It is a link:definitionLink element.
Dimension declaration.
Dimension declaration. It must be an abstract item declaration in the xbrldt:dimensionItem substitution group.
Either a global element declaration or a local element declaration.
Either an element declaration or an element reference.
Element reference, referring to a global element declaration.
Element reference, referring to a global element declaration. Like local element declarations it is not a child element of the xs:schema root element, but unlike global and local element declarations it has a ref attribute instead of a name attribute.
Explicit dimension declaration.
Explicit dimension declaration. It must be a dimension declaration without attribute xbrldt:typedDomainRef, among other requirements.
XLink extended link.
XLink extended link. For example (child elements have been left out):
<link:presentationLink xlink:type="extended" xlink:role="http://mycompany.com/myPresentationElr"> </link:presentationLink>
Or, for example (again leaving out child elements):
<link:labelLink xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link"> </link:labelLink>
An xs:extension element.
Global attribute declaration.
Global attribute declaration. It is an xs:attribute element, and a child element of the xs:schema root element.
Global element declaration.
Global element declaration. This element in isolation does not know if the element declaration is a concept declaration, because it does not know from which substitution groups its own substitution group, if any, derives.
Example, assuming an xs:schema parent (and document root) element:
<xs:element id="businessSegments" name="BusinessSegments" type="xbrli:monetaryItemType" substitutionGroup="xbrli:item" xbrli:periodType="duration" />
In this case, we see immediately that the global element declaration is an item concept declaration, but as said above, in general we cannot determine this without looking at the context of all other taxonomy documents in the same "taxonomy".
Once we have a SubstitutionGroupMap as context, we can turn the global element declaration into a ConceptDeclaration,
if the global element declaration is indeed an item or tuple declaration according to the SubstitutionGroupMap.
Hypercube declaration.
Hypercube declaration. It must be an abstract item declaration in the xbrldt:hypercubeItem substitution group.
Element-scheme XPointer starting with an ID and followed by a child sequence.
Element-scheme XPointer starting with an ID and followed by a child sequence. The indexes in the child sequence are 1-based.
Element-scheme XPointer containing only an ID.
Element-scheme XPointer containing only an ID. It is therefore semantically equivalent to a shorthand pointer.
An xs:import element.
An xs:include element.
Item declaration.
Item declaration. It must be in the xbrli:item substitution group, directly or indirectly.
An XBRL label arc.
An XBRL label arc. It is a link:labelArc element.
An XBRL label link.
An XBRL label link. It is a link:labelLink element.
XLink locator or resource.
Element in the link namespace ("http://www.xbrl.org/2003/linkbase").
The link:linkbase root element of a linkbase.
The link:linkbase root element of a linkbase. It may be embedded within a taxonomy schema document.
A link:linkbaseRef element.
Local attribute declaration.
Local attribute declaration. It is an xs:attribute element, but not a direct child element of the xs:schema root element.
Local element declaration.
Local element declaration. Like a global element declaration, it is an xs:element XML element with a name attribute. Unlike a global element declaration, it is not a child element of the xs:schema root element, but it is nested inside a type definition, for example. Unlike a global element declaration, it cannot have any substitution group, and therefore cannot be a concept declaration.
In an XBRL taxonomy, local element declarations are rare, if they occur at all. After all, most element declarations are global element declarations declaring item or tuple concepts, and tuple concept content models refer to other (item or tuple) concept declarations.
Model group, so either a sequence, choice or all model group.
Model group definition, so a top-level xs:group element with a name attribute.
Model group definition or model group reference.
Model group reference, so a non-top-level xs:group element with a ref attribute, referring to a model group definition.
Named complex type definition.
Named complex type definition. It is a top-level xs:complexType element with a name attribute.
Super-type of schema components that have a name attribute.
Named simple type definition.
Named simple type definition. It is a top-level xs:simpleType element with a name attribute.
Named type definition, so either a named complex type definition or a named simple type definition.
Non-standard arc, so an XLink arc that is not a standard arc.
Non-standard arc, so an XLink arc that is not a standard arc. Typically it is a generic arc. Some well-known formula/table-related arcs also fall into this category. Finally, unknown (and possibly incorrect) arcs also fall into this category.
Non-standard extended link, so an XLink extended link that is not a standard link.
Non-standard extended link, so an XLink extended link that is not a standard link. Typically it is a generic link.
Note that in general it is very hard to determine if a non-standard link is a generic link by looking at the link element itself, because we need substitution group (inheritance) context.
Non-standard locator, so an XLink locator that is not a standard locator.
Non-standard locator, so an XLink locator that is not a standard locator. Rarely, if ever, encountered in practice.
Non-standard resource, so an XLink resource that is not a standard resource.
Non-standard resource, so an XLink resource that is not a standard resource. Typically it is a generic label or generic reference. Formula/table-related XLink resources also fall into this category.
Non-standard simple link, so an XLink simple link that is not a standard simple link.
Non-standard simple link, so an XLink simple link that is not a standard simple link. Rarely, if ever, encountered in practice.
Any LinkElem not recognized as an instance of one of the other concrete LinkElem sub-types.
Any LinkElem not recognized as an instance of one of the other concrete LinkElem sub-types. This means that either
this is valid linkbase content not modeled in the LinkElem sub-type hierarchy, or it is syntactically incorrect.
Any element that is neither an XsdElem nor a LinkElem, and that is also not recognized as a non-standard link,
non-standard arc or non-standard resource.
Any element that is neither an XsdElem nor a LinkElem, and that is also not recognized as a non-standard link,
non-standard arc or non-standard resource. It may still be valid taxonomy content, but even in taxonomies with XBRL formulas
or XBRL tables most non-standard linkbase content is still XLink arc or resource content, and therefore does not fall in
this OtherNonXLinkElem category.
The elements that do fall into this OtherNonXLinkElem category are typically either reference parts (used in reference linkbases)
or formula/table-related non-XLink content.
Any XsdElem not recognized as an instance of one of the other concrete XsdElem sub-types.
Any XsdElem not recognized as an instance of one of the other concrete XsdElem sub-types. This means that either
this is valid schema content not modeled in the XsdElem sub-type hierarchy, or it is syntactically incorrect.
As an example of the latter, an xs:element XML element with both a name and a ref attribute is clearly invalid.
Particle (in the context of XML Schema), having optional minOccurs and maxOccurs attributes.
An XBRL presentation arc.
An XBRL presentation arc. It is a link:presentationArc element.
An XBRL presentation link.
An XBRL presentation link. It is a link:presentationLink element.
Primary item declaration.
Primary item declaration. It must be in the xbrli:item substitution group but neither in the xbrldt:hypercubeItem nor in the xbrldt:dimensionItem substitution groups.
A primary item may be used as explicit dimension member.
Note that in the Dimensions specification, primary item declarations and domain-member declarations have exactly the same definition! Although in a taxonomy the dimensional relationships make clear whether an item plays the role of primary item or of domain-member, here we call each such item declaration a primary item declaration.
Super-type of schema components that are references.
An XBRL reference arc.
An XBRL reference arc. It is a link:referenceArc element.
An XBRL reference link.
An XBRL reference link. It is a link:referenceLink element.
An xs:restriction element.
Either a restriction or an extension.
A link:roleRef element.
A link:roleType element.
A link:schemaRef element.
Sequence model group, so an xs:sequence element.
Shorthand pointer, which is by far the most commonly used kind of XPointer in XBRL (and in general).
An xs:simpleContent element.
XLink simple link.
XLink simple link. For example, showing a roleRef:
<link:roleRef xlink:type="simple" xlink:href="Concepts.xsd#SalesAnalysis" roleURI="http://mycompany.com/2017/SalesAnalysis" />
Simple type definition, so either a named simple type definition or an anonymous simple type definition.
An XBRL standard arc.
An XBRL standard arc. This is an XLink arc, and it is either a definition arc, presentation arc, calculation arc, label arc or reference arc.
An XBRL standard extended link.
An XBRL standard extended link. This is an XLink extended link, and it is either a definition link, presentation link, calculation link, label link or reference link.
An XBRL standard locator.
An XBRL standard locator. This is an XLink locator, and it is a link:loc element.
Either a concept-label resource or a concept-reference resource.
Very limited notion of a taxonomy, as a collection of taxonomy documents.
Very limited notion of a taxonomy, as a collection of taxonomy documents. It contains a map from URIs (with fragments) to taxonomy documents, for quick element lookups based on URIs with fragments. It also contains a map from ENames (names with target namespace) of global element declarations and named type definitions.
It does not understand (resolved) relationships, and it has no taxonomy query API, but it supports creation of such a taxonomy that does know about relationships and does have a taxonomy query API. In that sense, the reason for this class to exist is mainly its role in creating rich taxonomy objects.
Not only does this class not understand (resolved) relationships, it also does not know about substitution groups and therefore it does not know about concept declarations (unless all substitution groups are in the taxonomy base and we are prepared to follow them all).
This object is rather expensive to create (through the build method), building the maps that support fast querying based on URI (with fragment) or "target EName".
TaxonomyBase creation should never fail, if correct URIs are passed. Even the instance methods are very lenient and should never fail. Typically, a taxonomy instantiated as an object of this class has not yet been validated.
For the taxonomyDocUriMap and elemUriMap, we have that data is silently lost in those maps if there are any duplicate IDs (per document). In a valid taxonomy (as XML document set) this duplication is not allowed.
For the globalElementDeclarationMap, namedTypeDefinitionMap, etc., we also have that data is silently lost if there is more than 1 global element declaration (or named type definition) with the same "target EName". In a valid taxonomy (as XML schema) this duplication is not allowed.
"Taxonomy DOM document".
Any element in a taxonomy schema or linkbase document.
Any element in a taxonomy schema or linkbase document. The classes in this class hierarchy offer the yaidom query API,
in particular the ScopedElemApi and SubtypeAwareElemApi query API.
Suppose we have an eu.cdevreeze.tqa.base.dom.XsdSchema called schema. Then we can find all global element declarations in
this schema as follows:
import scala.reflect.classTag import eu.cdevreeze.tqa.ENames import eu.cdevreeze.tqa.base.dom.GlobalElementDeclaration // Low level yaidom query, returning the result XML elements as TaxonomyElem elements val globalElemDecls1 = schema.filterChildElems(_.resolvedName == ENames.XsElementEName) // Higher level yaidom query, querying for the type GlobalElementDeclaration // Prefer this to the lower level yaidom query above val globalElemDecls2 = schema.findAllChildElemsOfType(classTag[GlobalElementDeclaration]) // The following query would have given the same result, because all global element declarations // are child elements of the schema root. Instead of child elements, we now query for all // descendant-or-self elements that are global element declarations val globalElemDecls3 = schema.findAllElemsOrSelfOfType(classTag[GlobalElementDeclaration]) // We can query the schema for global element declarations directly, so let's do that val globalElemDecls4 = schema.findAllGlobalElementDeclarations
The classes in this type hierarchy have been designed to be very lenient when instantiating them, even for schema-invalid content.
The few builder methods that may throw exceptions have been clearly documented to potentially do so. For schema-invalid taxonomy
content, the resulting object may be something like OtherXsdElem, OtherLinkElem or OtherNonXLinkElem. For example,
an element named xs:element with both a name and ref attribute cannot be both an element declaration and element
reference, and will be instantiated as an OtherXsdElem. A non-standard XLink arc, whether a known generic arc or some
unknown and potentially erroneous arc, becomes a NonStandardArc, etc.
Some instance methods may fail, however, if taxonomy content is invalid, and if it is schema-invalid in particular. All instance methods must not fail on schema-valid content, unless mentioned otherwise.
Typical instance methods that may fail on schema-invalid content are:
It is important to keep this in mind. Schema-invalid taxonomies will be instantiated successfully, but after instantiation the API user should fall back to (defensive) yaidom level query methods when needed. This is indeed the responsibility of the API user.
The type hierarchy for taxonomy elements is not a strict hierarchy. There are mixin traits for XLink content, "root elements", elements in the xs and link namespaces, etc. Some element types mix in more than one of these traits.
See http://www.datypic.com/sc/xsd/s-xmlschema.xsd.html for schema content in general (as opposed to taxonomy schema content in particular).
It is perfectly fine to embed linkbase content in schema content, and such an element tree will be instantiated correctly.
The underlying backing elements can be any backing element implementation, including BackingNodes.Elem
wrappers around Saxon tiny trees! Hence, this taxonomy DOM API is flexible in that it is not bound to one specific
backing element implementation.
"Taxonomy DOM node".
Taxonomy root element, like an xs:schema element or a link:linkbase element.
Tuple declaration.
Tuple declaration. It must be in the xbrli:tuple substitution group, directly or indirectly.
Type definition.
Type definition. It is either a complex or simple type definition, and it is also either a named or anonymous type definition.
Typed dimension declaration.
Typed dimension declaration. It must be a dimension declaration with an attribute xbrldt:typedDomainRef, among other requirements.
A link:usedOn element.
XLink arc.
XLink arc. For example, showing an XLink arc in a presentation link:
<link:presentationArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/parent-child" xlink:from="parentConcept" xlink:to="childConcept" />
The xlink:from and xlink:to attributes point to XLink locators or resources in the same extended link with the corresponding xlink:label attributes.
An XLink element in a taxonomy, obeying the constraints on XLink imposed by XBRL.
An XLink element in a taxonomy, obeying the constraints on XLink imposed by XBRL. For example, an XLink arc or extended link.
XLink (see https://www.w3.org/TR/xlink11/) is a somewhat low level standard on top of XML, but it is very important in an XBRL context. Many taxonomy elements are also XLink elements, especially inside linkbases.
Simple or extended XLink link.
XLink locator.
XLink locator. For example:
<link:loc xlink:type="locator" xlink:label="entityAxis" xlink:href="Axes.xsd#entityAxis" />
XLink resource.
XLink resource. For example, showing an XLink resource in a label link:
<link:label xlink:type="resource" xlink:label="regionAxis_lbl" xml:lang="en" xlink:role="http://www.xbrl.org/2003/role/label">Region [Axis]</link:label>
XPointer, with sub-types for shorthand pointers and element scheme pointers.
XPointer, with sub-types for shorthand pointers and element scheme pointers.
Note that a locator href attribute may contain multiple element scheme pointers in succession.
Method parseXPointers in the XPointer companion object can parse those successive XPointers.
Element in the XML Schema namespace ("http://www.w3.org/2001/XMLSchema").
The xs:schema root element of a taxonomy schema.
The xs:schema root element of a taxonomy schema.
Content inside a schema (root element) can be queried using the yaidom query API, of course, but this class also offers some own query methods (that are themselves implemented as yaidom queries). For example:
val globalElemDecls = schema.findAllGlobalElementDeclarations val globalElemDeclTypeENames = globalElemDecls.flatMap(_.typeOption).toSet
Type-safe XBRL taxonomy DOM API. This contains DOM-like elements in taxonomy documents. It offers the yaidom query API and more, and wraps an underlying element that itself offers the yaidom query API, whatever the underlying element implementation. This package does not offer any taxonomy abstractions that cross any document boundaries, except for the light-weight
TaxonomyBaseabstraction at the type-safe DOM level.This package mainly contains:
This package has no knowledge about and dependency on XPath processing.
Usage
Suppose we have an eu.cdevreeze.tqa.base.dom.XsdSchema called
schema. Then we can find all global element declarations in this schema as follows:Global element declarations in isolation do not know if they are (item or tuple) concept declarations. In order to turn them into concept declarations, we need a
SubstitutionGroupMapas context. For example:Most TQA client code does not start with this package, however, but works with entire taxonomies instead of individual type-safe DOM trees, and with relationships instead of the underlying XLink arcs.
Leniency
See the remarks on leniency for type
TaxonomyElemand its sub-types. This type-safe XBRL DOM model has been designed to be very lenient on instantiation of the model. Therefore this TQA type-safe DOM model can also be used for validating potentially erroneous taxonomy documents.On the other hand, if the instantiated model cannot be trusted to be schema-valid, one should be careful in choosing the API calls that can safely be made on schema-invalid taxonomy content. Yaidom API level query methods that return collections or options are typically safe to use on potentially schema-invalid taxonomy content.
Other remarks
To get the model right, there are many sources to look at for inspiration. First of all, for schema content there are APIs like the Xerces schema API (https://xerces.apache.org/xerces2-j/javadocs/xs/org/apache/xerces/xs/XSModel.html). Also have a look at http://www.datypic.com/sc/xsd/s-xmlschema.xsd.html for the schema of XML Schema itself. Moreover, there are many XBRL APIs that model (instance and) taxonomy data.
On the other hand, this API (and the entirety of TQA) has its own design. Briefly, it starts bottom-up with yaidom, and gradually offers higher level (partial) abstractions on top of that. It does not hide yaidom, however.
TODO Support for built-in schema types, and built-in XBRL types.