FlexDoc/XML - DiagramKit - FAQ

How To Run DiagramKit
DiagramKit Settings
Component Properties
Compound Diagrams
Generator Setups

Compound Diagrams

What are compound diagrams?

A typical diagram generated by DiagramKit depicts the content model of a single XSD component: everything about the child XML elements and attributes that component defines. We shall call it simple diagram.

However, some people want to see on the same diagram something deeper: the content models of some of those children important to them, children of the children and so on. That is, instead of solely the content model of a given XSD component, the diagram may represent some fragment of the content model of the entire XML subtree defined by that component. We shall call this compound diagram, an example of which is shown below:

Each compound diagram consists of several simple diagrams linked together and arranged in vertical columns as shown on the following screenshot:

The first column is occupied by the only simple diagram representing the content model of that XSD component, for which the entire compound diagram is generated. Each next column is produced from the previous one as follows:

All simple diagrams contained in the column and all elements shown on them are iterated from top to bottom.
If an element matches certain criteria, it will be shown as expanded and its content diagram placed in the next column linked from that element the same way as in the case of an ordinary diagram.
The iterations continue until no new content diagrams are produced (no elements expanded).

Obviously, each column represents a next level of element descendancy against the content of the initial XSD component (for which the diagram is generated).

If an element that meets the expansion criteria appears multiple times in total, it will be shown as expanded only once. The uniqueness of elements is determined by their {qualified name + type}.

How to specify expanded elements?

Which exactly elements visible across all the simple diagrams (that constitute the compound one) get expanded is specified with the template parameter:

DiagramKit | Compound Diagrams | Expanded Elements

It accepts a JSON value providing one or multiple specifications for expanded elements:

expanded_elements_spec

or

[
  expanded_elements_spec1,
  expanded_elements_spec2,
  ...
]

That list is iterated for each XSD component to be represented with a diagram. The matching specifications are applied to every simple diagram starting from the initial one. If an element found on a simple diagram matches at least one of those specifications, it will be shown as expanded, its content diagram with the link from that element will appear in the next compound diagram column.

Single specification

Each 'expanded_elements_spec' is a JSON object looking as follows:

{
  "disable":             true | false,
  
  "for_elements":        name_patterns,
  "for_global_elements": name_patterns,
  "for_complexTypes":    name_patterns,
  "for_groups":          name_patterns,

  "expand":              name_patterns,
  "depth":               number  
}

with all fields and values explained here:

disable

Optional. Allows you to disable a particular expanded elements specification without deleting it. If true, that specification will be ignored.



for_elements


for_global_elements


for_complexTypes


for_groups

Optional. Specify which XSD components (to be represented with a compound diagram) this spec matches according to the component type and name. If neither of these fields is provided, the spec matches any XSD component.

expand

Specify which elements should be shown expanded on the diagram.

Not all element nodes that meet the expansion criteria will be expanded. The repeating elements are expanded only once. The uniqueness of elements is determined by their {qualified name + type}.

depth

Optional. Allows you to limit the size of the generated compound diagrams when the specified matching conditions are too broad.

It specifies the maximal depth of the element expansion. Basically, it is the level of element descendancy against the content of the initial XSD component (for which the diagram is generated). Each descendance level will form a separate column of the compound diagram.

If the depth field is not specified, the depth is unlimited.

For instance, if depth=1, only elements found in the initial content model will be expanded. The compound diagram will have two columns.

If the name pattern specified in the expand field is a wildcard and the depth field is absent, the generated compound diagrams may be extremely large!

Name patterns

This is a list of XML qualified name patterns, by which the component name is matched. It may be either a single pattern, an array of patterns or true:


"name_pattern"

["name_pattern1", "name_pattern2", ... ]

true

The true setting indicates matching with any name.

Each 'name_pattern' specifies a component name pattern that covers either the fully qualified name of the component or how it appears on the diagram:

Pattern	Matches
`prefix:localName`	components with the specified namespace prefix and local name
`prefix:*`	components with any local name and the specified namespace prefix
`{namespaceURI}:localName`	components with the specified local name in a namespace identified by the specified URI
`{namespaceURI}`	components that belong to the specified namespace
`{}:localName`	components with the specified local name in no namespace
`{}`	components that belong to no namespace
`localName`	components with the specified local name and no namespace prefix
`*`	components without namespace prefix
`*:localName`	components with the specified local name in any namespace
`:`	components with any local name from any namespace; the same as specifying `true` for the whole name pattern list

Examples

The following examples show possible value of the template parameter parameter:

DiagramKit | Compound Diagrams | Expanded Elements

The parameter accepts a text in JSON format, which is shown in boxes.

Example 1

Generate compound diagrams for all XSD components with all elements expanded into unlimited depth. That will show the content model of the entire XML subtree defined by each component:

{ "expand": "*:*" }
or: { "expand": true }

Example 2

For each XSD component, expand all elements found in its initial content model. However, the elements <xs:annotation>, <xs:documentation>, <xs:appinfo> (if any) must be fully expanded in any case:

[
  { "expand": true, "depth": 1 },
  {
    "expand": [
      "xs:annotation",
      "xs:documentation",
      "xs:appinfo"
    ]
  }
]

That's how the first diagram on this page was generated. Click on it to see in the documentation along with other similar diagrams.

Example 3

Generate a compound diagram for the element <cpl:cpl> with the elements <cpl:address>, <cpl:address-switch>, <cpl:toplevelaction>, <routed>, <rule>, <rule-switch> shown expanded on it:

{
  "for_elements": "cpl:cpl",
  "expand": [
    "cpl:address",
    "cpl:address-switch",
    "cpl:toplevelaction",
    "otherwise",
    "routed",
    "rule",
    "rule-switch"
  ]
}

That's how the second diagram on this page was generated.

Related template parameters

These are template parameters relevant to the generation of compound diagrams:

DiagramKit | Compound Diagrams: The parameter group to control the generation of compound diagrams. This parameter itself allows you to disable that feature without deleting any other settings.
DiagramKit | Compound Diagrams | Expanded Elements: The most important parameter. Here you specify using JSON how compound diagrams are generated: which elements should be expanded and to which components that applies.
DiagramKit | Show in Diagram | Substitution Groups: Here you can specify if the repeating of substitution groups should be suppressed. The same substitution group may appear in all content diagrams of expanded elements, which will bloat the whole diagram too much.
DiagramKit | Layout | Expand / Collapse Icons: Controls whether to show expand/collapse icons. The expand/collapse icons provide more clarity and may be particularly useful in compound diagrams. However, they occupy more space and without them the result diagram will look a bit narrower and more compact.