Schema Documentation: the annotation element

On this page:

Back to
main menu
Usage Example
Allowed parents
Allowed children
Content model and additional requirements
Variants
Namespace
Usage Details

The annotation element represents an annotation that an author, editor, publisher, or other individual or agency has added to a document.

Unless an annotation element has a role value of temporary, it must reference at least one element in the document using the ref attribute or be referenced by at least one annoref. For annotations that apply to more than one element, use a space-separated list of xml:id values in the ref attribute.

The ref attribute identifies the specific element(s) being annotated by referencing their xml:id values.

The annotation element should not be used to add descriptions, footnotes or endnotes. Refer to the description and note (block) elements for more information.

Usage details available in the Usage Details section.

Usage Example

<p>…it created a great chasm between my step-mother and me.<annoref ref="anno-04" value="4" /></p>

<annotation xml:id="anno-04" by="translator">
    This needs explanation. In Germany, even by strangers, children are universally addressed…
</annotation>

Allowed parents

annotation, m:annotation-xml, aside, block, d:body, caption, description, item, d:longdesc, note (block variant), note (phrase variant), object, quote, section, d:simplifiedLanguageDescription, d:summary, td, th and d:tour

Allowed children

This element may contain text.

This element may contain the following children: abbr, annoref, annotation (block variant), annotation (phrase variant), aside, block, ssml:break, caption, char, citation (block variant), citation (phrase variant), code (block variant), code (phrase variant), d, definition, description, d:description, emph (text variant), emph (phrase variant), expansion, hd, rend:linebreak, list, ln, m:math, name, note (block variant), note (phrase variant), noteref, num, object (block variant), object (text variant), object (phrase variant), p, pagebreak, ssml:phoneme (text variant), ssml:phoneme (phrase variant), ssml:prosody (text variant), ssml:prosody (phrase variant), quote (block variant), quote (phrase variant), ref, its:ruby, s, ssml:say-as (text variant), ssml:say-as (phrase variant), span (text variant), span (phrase variant), sub, ssml:sub (text variant), ssml:sub (phrase variant), sup, table, term, time, ssml:token (text variant), ssml:token (phrase variant), verse and w

Content model and additional requirements

optional attributes: @about, @by, @class, @content, @datatype, @desc, @its:dir, @its:translate, @property, @ref, @rel, @rend:prefix, @resource, @rev, @role, @ssml:onlangfailure, @typeof, @xml:base, @xml:id, @xml:lang and @xml:space

a choice of

either one or more of

any of the 19 elements: annotation, aside, block, caption, citation, code, d:description, description, hd, list, m:math, note, object, p, pagebreak, quote, ssml:break, table and verse

or one or more of

a choice of

either one of the 45 elements: abbr, annoref, annotation, char, citation, code, d, definition, emph, emph, expansion, its:ruby, ln, m:math, name, note, noteref, num, object, object, pagebreak, quote, ref, rend:linebreak, s, span, span, ssml:break, ssml:break, ssml:phoneme, ssml:phoneme, ssml:prosody, ssml:prosody, ssml:say-as, ssml:say-as, ssml:sub, ssml:sub, ssml:token, ssml:token, sub, sup, term, time, w or w

or text

end of choice

Note that in addition to restrictions presented in the content model above, use of this element must also respect the following requirements:

The annotation element must be referenced by an annoref or reference another element in the document unless it has the role value temporary.
The annotation element must neither be empty nor contain only whitespace.
Annotations with a role value of temporary must be removed prior to document finalization.

Such requirements take precedence over any conflicting statements in the content model or in the lists above of allowed children and parents.

Variants

This element exists in 2 variants. The other variant is the phrase variant.

Namespace

http://www.daisy.org/ns/z3998/authoring/

Usage Details

The optional by and role attributes define the contributor of the annotation and expresses its nature:

<object xml:id="mnt" src="mnt.png" />
    <annotation ref="mnt" by="republisher" role="alteration">
        <p>This picture was originally on page 15 in the source but has been moved after the paragraph it split.</p>
    </annotation>

The lack of a role value indicates the annotation is general in nature; no implicit value should be assumed. The by attribute has an implicit value of author unless an ancestor element establishes a new relationship.

Notice also in the preceding example that there isn't an explicit reference to the annotation (i.e., no annoref element). As a result, the annotation establishes its relationship to the text via the ref attribute. Only temporary notes may be included with no reference to them or from them:

<annotation role="temporary">
       2010-12-24 - Markup verified to this point. Continuing after holidays. --MG
</annotation>

The by attribute may be omitted from temporary annotations as they must be removed from a document prior to its finalization. Where they are being used to relay production information, however, creating and assigning unique by values for staff/production roles may improve their usability. For example, a quality assurance editor could use the element to leave notes for the markup team:

<annotation role="temporary" by="qa" class="error">
        Missed merged paragraphs.
</annotation>

This specification does not attempt to define all the role values needed for all production contexts. New contributor and annotation types can be added as required, however.

Attaching more than one annotation to an element is permitted, but each annotation must have a unique role.