Schema Annotations

A schema annotation is a documentation snippet associated with the definition of an element or attribute in a schema. If such a schema is associated with an XML document, the annotations are displayed in:

The Content Completion Assistant.
A small tooltip window shown when the mouse hovers over an element or attribute. The tooltip window can be invoked at any time using the F2 shortcut.

The schema annotations support is available the schema type is one of the following: XML Schema, Relax NG, NVDL, or DTD. If you want to turn off this feature, disable the Show annotations in Content Completion Assistant option.

Styling Annotations with HTML

You can use HTML format in the annotations you add in an XML Schema or Relax NG schema. This improves the visual appearance and readability of the documentation window displayed when editing XML documents validated against such a schema. An annotation is recognized and displayed as HTML if it contains at least one HTML element, like: div, body, p, br, table, ul, or ol.

The HTML rendering is controlled by the Show annotations using HTML format, if possible option. When this options is disabled, the annotations are converted and displayed as plain text. If the annotation contains one or more HTML tags (p, br, ul, li), they are rendered as an HTML document loaded in a web browser: p begins a new paragraph, br breaks the current line, ul encloses a list of items, li encloses an item of the list.

Collecting Annotations from XML Schemas

In an XML Schema the annotations are specified in an <xs:annotation> element like this:

<xs:annotation>
  <xs:documentation>
            Description of the element.
  </xs:documentation>
</xs:annotation>

For XML Schema, if an element or attribute does not have a specific annotation, then Oxygen XML Editor looks for an annotation in the type definition of that element or attribute.

Collecting Annotations from Relax NG Schemas

For Relax NG schema element / attribute annotation are made using the <documentation> element from the http://relaxng.org/ns/compatibility/annotations/1.0 namespace. However, any element outside the Relax NG namespace (http://relaxng.org/ns/structure/1.0) is handled as annotation and the text content is displayed in the annotation window. To activate this behavior, enable the Use all Relax NG annotations as documentation option.

Collecting Annotation from DTDs

For DTD Oxygen XML Editor defines a custom mechanism for annotation using comments enabled from the option Use DTD comments as annotations. Following is an example of a DTD annotation:

<!--doc:Description of the element. -->