About Local Elements

• The problem with Local Elements
• How Local Elements are documented
• Local Documenting
• Global Documenting
  • Unifying Local Elements By Type
• Global Naming of Local Elements
  • Examples
  • Omitting Name Extensions

The problem with Local Elements

• complex types (either global ones or defined anonymously within other elements)
• element groups (which are separate schema components that define whole bunches of elements arranged in specific complex models).

Now, within the same XML document, you may find several different XML elements that although share the same name, actually represent more or less different things and, therefore, may have different attributes and content. It is clear that such equally named but essentially different local elements must be documented separately.

On the other hand, in many cases local elements are declared very simply:

<xs:element name="elementName" type="typeName"/>

How Local Elements are documented

Local elements can be documented simultaneously in two ways: locally and globally.

The purpose of two types of the documentation is that some elements may be important to show in the navigation lists, whereas other elements (particularly those with predefined simple content that essentially play the role of attributes) are better to be documented locally where they are defined/used. Exposing such insignificant elements in the navigation lists and summaries (along with the global elements or those with complex content) may blow out and overwhelm such lists and make them difficult to navigate.

Local Documenting of Local Elements

That documentation appears in the "Content Element Detail" section of the XSD Component Documentation generated for the element's parent component. It may contain more details about the element declaration itself, but will provide less information about how the element is used elsewhere.

What exactly is included in this section for each element is controlled by the parameter group: "Details | XSD Component | Content Element Detail"

Global Documenting

In the case of framed HTML documentation, such an element will also appear in the component lists shown in the documentation List Frame (on the left).

Moreover, unlike the section describing that element in the "Content Element Detail" of its parent component, the detailed Element Documentation may include a lot more information about how the element interacts with other XML schema components (e.g. "List of Containing Elements", "Usage/Definition Locations" etc.)

Which local elements are documented globally is controlled by the parameter group: "Generate Details | XSD Components | Elements | Local Elements". What will be included in that documentation is controlled by parameters in "Details | XSD Component" group.

Unifying Local Elements By Type

{ namespace : elementName : typeName }

<xs:element name="elementName" type="typeName"/>

On the other hand, the same name/type combination for a schema element is typically associated with the same notion from the real world. When you try to understand a particular XML schema, tracking something associated with different local elements scattered across the whole schema may be difficult. Having a single documentation for those elements may quickly reveal a lot more things.

This XML schema documentation generator supports such a possibility.

When the parameter "Generate Details | XSD Components | Elements | Local Elements | Unify By Type" is selected (true), all local elements that share the same {namespace : elementName : typeName} will be documented on the same global documentation page (or block) as a single entity -- unified local element.

All actual element components unified by type across the documentation will be hyperlinked to that page and all of them will be represented by a single item in various navigation lists.

If some of the definitions of the unified local element do vary (e.g. they may have different annotations or a few other settings, like default attribute) those differences will be also documented on the same unified global documentation page.

For many XML schemas, the unification of local elements by type may greatly reduce the overall number of documented elements, thereby making the documentation a lot clearer. In some special cases, the XML schema documentation generated without it would be even difficult to understand and use. All you would see would be lots of repeating element names with a little clue what they actually mean (especially given that some of them may represent essentially the same things, whereas others quite different ones.)

Global Naming of Local Elements

But when such equally named local elements need to be presented in a single navigation/reference list or summary, it may be impossible to tell them apart (at least until clicking the links).

Fortunately, that problem can be solved by extending each repeating local element name with a little text that would make the element unique across the documentation. Such extensions of local element names are generated according to the following rules:

1. When the element is included in the content model of only one other element (taking also into account the unification of local elements by type; see above), the element name is extended with the full name of its possible parent element like this:

   name (in full_parent_name)

   where full_parent_name is a normal qualified name for a global element or the qualified name with the extension for a local element.

   Otherwise, the element name is extended differently (as described below).

2. If the following conditions are met
   • The element has a type attribute
   • The unification of local elements by type is enabled. (See Unifying Local Elements By Type above.)
   • The element is documented globally
   then the element name is extended with the name of the type like the following:

   name (type type_name)

   or, when the name appears within the extension of other local element's name:

   name : type_name

   Here, the type_name is the qualified name of a global type specified in the type attribute.

   The conditions above guarantee that such a whole name (i.e. the element qualified name + extension) will be unique for every separately documented element entity (that is, the hyperlinks from equal names will always lead to the same documentation).

3. In all other cases, the local element must be the one defined within a global complex type or element group.

   Indeed, any local element can be defined only in three types of locations: Within a global complex type Within a global element group Within an anonymous complex type in another element component The last possibility is excluded here because in that case the given local element would be included in the content model of only one other element: the one, in which it is defined.

   So, the name extension is produced from the definition location, as follows:

   name (defined in type_name complexType)

   or

   name (defined in group_name group)

   where type_name or group_name is the qualified name of the global complex type or element group, in which the element is defined.

Examples:

Here, the local element 'xs:choice' (whose name is being extended) may be included in only one other element 'xs:group', which is the global one.

The element 'xs:group' has a global type 'xs:groupRef'. This local element component is documented globally, possibly along with other equally named local elements unified by the same type.

The local element 'xs:attribute' may be included in several other elements (documented differently) or in none at all. However, it is defined in only one location -- in 'xs:attrDecls' group.

The local element 'configuration' (whose name is being extended) may be included in only one other element 'plugin', which itself is also a local one included only in 'plugins' element and so on.

The local element 'configuration' may be included in only one other element 'plugin', which by itself can be one or several local element components unified by the same type 'Plugin'.

Omitting Name Extensions

In those cases, you can disable the generation of name extensions using "Show | Element Name Extensions" parameter, either for all local elements altogether or for only those whose original names are unique.