Edit online

Schema Annotations in Author Mode

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.

Figure 1. Schema Annotation in the Content Completion Assistant

The schema annotations support is available if the schema type is one of the following:

XML Schema
Relax NG
NVDL schema
DTD

This feature is enabled by default, but you can disable it by deselecting the Show annotations in Content Completion Assistant option in the Annotations preferences page.

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 (such as <div>, <body>, <p>, <br>, <table>, <ul>, or <ol>).

The HTML rendering is controlled by the Show annotations using HTML format, if possible option in the Annotations preferences page. When this option is deselected, the annotations are converted and displayed as plain text and 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. For example, <p> begins a new paragraph, <br> breaks the current line, <ul> encloses a list of items, and <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>

If an element or attribute does not have a specific annotation, then Oxygen XML Author looks for an annotation in the type definition of that element or attribute.

Collecting Annotations from Relax NG Schemas

For Relax NG schema, element and attribute annotations are made using the <documentation> element from the http://relaxng.org/ns/compatibility/annotations/1.0 namespace like this:

<define name="person" >
  <element name="person">
    <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0">
            Information about a person. </a:documentation>
      <ref name="name"/>
        <zeroOrMore>
      <ref name="email"/>
        </zeroOrMore>
  </element>
</define>

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, select the Use all Relax NG annotations as documentation option in the Annotations preferences page.

Collecting Annotations from Relax NG Compact Syntax Schemas

For Relax NG Compact Syntax schema, annotations are made using comments like this:

##  Information about a person.
element person { name, email*}

Collecting Annotation from DTDs

For DTD, Oxygen XML Author defines a custom mechanism for annotations using comments enabled by the Prefer DTD comments that start with "doc:" as annotations option in the Annotations preferences page. The following is an example of a DTD annotation:

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