XSD Viewer

1. About the add-on

The XSD-Viewer plugin is created to visualize XSD schemes in either diagrams or tables listing all the elements, types, restrictions and descriptions. This makes XSD schemes even readable for non-technical people.

2. Installation

This plugin is available for download directly from the plugin manager in your Confluence installation. Alternatively, you can download the plugin from the Atlassian Marketplace directly and install the plugin manually. You can find more information about installing plugins in the Confluence documentation.

3. How to use the plugin

3.1. Add the XSD file as attachment to Confluence

Open the Confluence page where you want to render the XSD image or table. Click on the ‘Add’ dropdown and select ‘Attachment’. Locate the XSD schema on your computer and upload it to your Confluence page.

You don’t have to attach the same XSD file for every page where you want to use the macro. Once your XSD file is attached, the plugin can search through spaces and pages for your attachment.

3.2. Macro

Edit the Confluence page where you want to use the plugin. Start typing {xsd. Two options of the XSD-Viewer plugin will show up, XSD Image and XSD Table, select the one that you want to render.

XSD Viewer Macro

3.3. Macro panel

Once you’ve selected an option, the macro panel/browser will show up giving you configuration fields.

  • Page

  • Attachment

  • Starting element

  • Depth

  • Types to exclude

XSD Viewer Panel

Page This field has a built in search functionality. By typing the page where you’ve stored your attachment, even outside of the current space, you can select this page.

Attachment A dropdown of all the attachments with the .xsd extension on this page will be shown. If no attachments with the .xsd extension are found the dropdown will mention this to you.

Note
The atlassian OnDemand version does not yet support the attachment fieldtype, this means that you have to manually enter the xsd filename as a string value. When this is fixed, it will be implemented! It is not possible to link to XSD files hosted elsewhere.

Starting element

  • Starting element is searched in the following order:

    • Element

    • SimpleType

    • ComplexType

Depth With the depth field you can configure how deep the image should be rendered or when choosing the table, what point should be described. The depth configuration is applicable on element types, how far element types of element types should be rendered. The default setting is 1. For rendering the entire structure you can set the depth at 0. Please be aware that if the image to be rendered is too big the XSD-Viewer plugin might not be able to show the image. When recursiveness occurs in the chosen XSD schema we strongly suggest not to render the image at infinite depth. More about this is described below.

Types to exclude In this input field you can configure element types you don’t want to see rendered. The element itself will still be rendered, otherwise the rendered image would be incorrect. This is handy to use when you want to render certain parts only. Some examples are given below.

4. Recursiveness

Recursive (comparative more recursive, superlative most recursive)

In the XSD-Viewer plugin context recursive means that an element type has somewhere children of its own type. The example XSD below is set up this way.

<xs:complexType name="nodeType">
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
        <xs:element name="node" type="nodeType"/>
    </xs:sequence>
</xs:complexType>

The XSD-Viewer plugin is able to draw XSD’s containing recursiveness but only to a certain level, depending on the complexity of the XSD schema itself. When an error occurs rendering the image, concluding possible recursiveness is detected, try to lower your depth level.

A rendered image of the XSD schema above is shown below. The chosen starting element is nodeType and the depth is set at 2 so it is clear this node type is recurring.

Recursive

5. xs:documentation

The xs:documentation is currently only rendered by the table macro. The images do not include the documentation.

The proper way to include html is by including an html namespace:

<xs:documentation>
  <code xmlns="http://www.w3.org/1999/xhtml">source code</code>
</xs:documentation>

5.1. html support

The add-on supports the use of html inside xs:documentation elements. For security reasons the html is sanitized to reduce the risk for cross site forgery attacks.

The following tags are stripped from the html:

  • script

  • noscript

  • iframe

  • frameset

  • frame

  • noframes

  • head

  • title

  • base

  • style

  • link

  • input

  • textarea

The other tags are validated and possibly stripped. For example <a href=""> is checked for sane urls using these regular expressions:

  • on site URLS: "([\p{L}\p{N}\p{Zs}/\.\?=&\-~])+"

  • off site URLS: "(\s)((ht|f)tp(s?)://|mailto:)[~a-zA-Z0-9-_\.@\#\$%&amp;;:,\?=/\!\(\)](\s)*"

Should you have a use case to make this configurable / disable it, let us know!

6. Examples

Study the following XSD Schema

<xs:schema id="XMLSchema1"
           targetNamespace="http://tempuri.org/XMLSchema1.xsd"
           elementFormDefault="qualified"
           xmlns="http://tempuri.org/XMLSchema1.xsd"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
        >

    <xs:complexType name="error">
        <xs:sequence>
            <xs:element name="code" type="xs:int"/>
            <xs:element name="description" type="xs:string" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="reference">
        <xs:all>
            <xs:element name="number" type="xs:string" minOccurs="0"/>
            <xs:element name="description" type="xs:string" minOccurs="0"/>
        </xs:all>
    </xs:complexType>

    <xs:complexType name="errors">
        <xs:sequence>
            <xs:element name="error" type="error" maxOccurs="10"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="messageAnswer">
        <xs:sequence>
            <xs:element name="indicationError" type="xs:boolean"/>
            <xs:element name="errors" type="errors" minOccurs="0" maxOccurs="1">
                <xs:annotation>
                    <xs:documentation>If the message contains errors</xs:documentation>
                </xs:annotation>
            </xs:element>
            <xs:element name="reference" type="reference"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="acknowledgement">
        <xs:sequence>
            <xs:element name="messageAnswer" type="messageAnswer">
                <xs:annotation>
                    <xs:documentation>The answer being given</xs:documentation>
                </xs:annotation>
            </xs:element>
        </xs:sequence>
    </xs:complexType>

    <xs:element name="setAttachmentResponse" type="acknowledgement"/>

</xs:schema>

6.1. Full rendered image

Setting the starting element on setAttachmentResponse with depth 0 and no exclusions.

XSD Viewer full image example

6.2. Full rendered table

XSD Viewer full rendered table example

6.3. Depth

The image below is an XSD rendered with a depth limitation set at 2. The two borders drawn indicate the depth.

XSD Viewer depth example

6.4. Exclude type

The image below has a configured exclusion type. Compared to the full rendered image, you can see that the element itself is still drawn but the type no longer.

XSD Viewer exclude example

This gives you the advantage of going more into detail when wanting to render certain parts of your XSD schema as you can see in the example below.

XSD Viewer exclude example result

7. Limitations

7.1. Nested complex types

Nested complex types are ignored by the parser for now. Please use top level complex types when you can.

The add-on is currently unable to generate documentation for:

<xs:element name="ConfigElement">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="Fragments">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="0" name="ProtocolFragments"/>
            <xs:element minOccurs="0" name="MailFragments"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="Profiles"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

This is handled correctly:

<xs:complexType name="ConfigComplex">
  <xs:sequence>
    <xs:element name="Fragments">
      <xs:complexType>
        <xs:sequence>
          <xs:element minOccurs="0" name="ProtocolFragments"/>
          <xs:element minOccurs="0" name="MailFragments"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    <xs:element name="Profiles"/>
  </xs:sequence>
</xs:complexType>

<xs:element name="Complex" type="ConfigComplex"/>

We are looking into lifting this restriction as soon as we can, but currently do not have an ETA for it.