eu.cdevreeze.tqa.base.dom

All model group, so an xs:all element.

An xs:annotation element.

Anonymous complex type definition. It is a non-top-level xs:complexType element without any name attribute.

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

An XBRL calculation arc. It is a link:calculationArc element.

An XBRL calculation link. It is a link:calculationLink element.

Super-type of schema components that can be abstract.

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. 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. It is a link:label element.

Concept-reference resource. It is a link:reference element.

Either simple content or complex content.

A link:definition element.

An XBRL definition arc. It is a link:definitionArc element.

An XBRL definition link. It is a link:definitionLink element.

Dimension declaration. It must be an abstract item declaration in the xbrldt:dimensionItem substitution group.

Element in the label namespace ("http://xbrl.org/2008/label").

Element in the link namespace ("http://www.xbrl.org/2003/linkbase").

Element in the reference namespace ("http://xbrl.org/2008/reference").

Element in the XML Schema namespace ("http://www.w3.org/2001/XMLSchema").

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. 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. It must be a dimension declaration without attribute xbrldt:typedDomainRef, among other requirements.

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. It is an xs:attribute element, and a child element of the xs:schema root element.

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. It must be an abstract item declaration in the xbrldt:hypercubeItem substitution group.

An xs:import element.

An xs:include element.

Item declaration. It must be in the xbrli:item substitution group, directly or indirectly.

An XBRL label arc. It is a link:labelArc element.

A label:label element. Not any element in that substitution group, but only a label:label element.

An XBRL label link. It is a link:labelLink element.

XLink locator or resource.

The link:linkbase root element of a linkbase. It may be embedded within a taxonomy schema document.

A link:linkbaseRef element.

Local attribute declaration. It is an xs:attribute element, but not a direct child element of the xs:schema root element.

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. 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. 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. 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. 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. Rarely, if ever, encountered in practice.

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. Rarely, if ever, encountered in practice.

Any ElemInLabelNamespace not recognized as an instance of one of the other concrete ElemInLabelNamespace sub-types. This means that either this is valid linkbase content not modeled in the ElemInLabelNamespace sub-type hierarchy, or it is syntactically incorrect.

Any ElemInLinkNamespace not recognized as an instance of one of the other concrete ElemInLinkNamespace sub-types. This means that either this is valid linkbase content not modeled in the ElemInLinkNamespace sub-type hierarchy, or it is syntactically incorrect.

Any ElemInReferenceNamespace not recognized as an instance of one of the other concrete ElemInReferenceNamespace sub-types. This means that either this is valid linkbase content not modeled in the ElemInReferenceNamespace sub-type hierarchy, or it is syntactically incorrect.

Any ElemInXsdNamespace not recognized as an instance of one of the other concrete ElemInXsdNamespace sub-types. This means that either this is valid schema content not modeled in the ElemInXsdNamespace 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.

Non-standard XLink arc that is not in one of the known namespaces.

Non-standard extended link that is not in one of the known namespaces.

Non-standard XLink locator that is not in one of the known namespaces.

Non-standard XLink resource that is not in one of the known namespaces.

Non-standard simple link that is not in one of the known namespaces.

Any element that is not in one of the "known" namespaces, 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.

Particle (in the context of XML Schema), having optional minOccurs and maxOccurs attributes.

An XBRL presentation arc. It is a link:presentationArc element.

An XBRL presentation link. It is a link:presentationLink element.

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. It is a link:referenceArc element.

A reference:reference element. Not any element in that substitution group, but only a reference:reference element.

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.

An xs:simpleContent element.

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. 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. 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. 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. 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. The classes in this class hierarchy offer the yaidom query API, in particular the ScopedElemApi and SubtypeAwareElemApi query API.

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

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

==Leniency==

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 OtherElemInXsdNamespace, OtherElemInLinkNamespace 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 OtherElemInXsdNamespace. A non-standard XLink arc, whether a known generic arc or some unknown and potentially erroneous arc, becomes an instance of NonStandardArc or one of its sub-types, 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:

• methods that query for one mandatory attribute (as far as the schema is concerned)

• methods that query for one mandatory child element (as far as the schema is concerned)

• methods that query for values of specific types (enumerations, integers etc.)

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.

==Other remarks==

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. It must be in the xbrli:tuple substitution group, directly or indirectly.

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. It must be a dimension declaration with an attribute xbrldt:typedDomainRef, among other requirements.

A link:usedOn element.

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. 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. For example:

<link:loc xlink:type="locator"
 xlink:label="entityAxis"
 xlink:href="Axes.xsd#entityAxis" />

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>

The xs:schema root element of a taxonomy schema.

==Usage==

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