ZedAI Using Namespace Prefixes

From zedwiki

The Problem

Many editors provide code completion and will automatically add the correct namespace to your elements as you author your documents. For example, adding the select element from the Content Selection feature to output a description element would result in the following:

<select xmlns="http://www.daisy.org/ns/z3986/authoring/features/select/">
   <when expr="target:format('BRAILLE')">
      <description xmlns="http://www.daisy.org/ns/z3986/authoring/"/>
   </when>
   <otherwise>
      <description xmlns="http://www.daisy.org/ns/z3986/authoring/"/>
   </otherwise>
</select>

There are two things to note in the above example: 1) the child elements of the select automatically inherit the parent namespace, so the xmlns attribute is not repeated on them; and 2) because all descendants inherit the new namespace, the two description elements have to redeclare that they are actually in the same namespace as the rest of the document.

The above example is a trivial one, but imagine if the content being alternated contained child elements. Each of those children would inherit the namespace of the most recent ancestor with an xmlns attribute. For example:

<select xmlns="http://www.daisy.org/ns/z3986/authoring/features/select/">
   <when expr="target:format('BRAILLE')">
      <description xmlns="http://www.daisy.org/ns/z3986/authoring/">
        <p>A description of a figure...</p>

It's no longer readily apparent by looking at the element names what namespace each is in. An author has to backtrack through all the open ancestors to determine which elements belong to which namespace.

Now imagine trying to copy and re-use the content in another context. If you don't grab the ancestor that declares the namespace you may wind up wondering why you suddenly start getting errors from tags that look right (or worse, the namespace you paste into declares a similarly named element but with a different purpose).

Another problem in using the xmlns attribute to switch namespaces as you go is that you may not see elements and attributes that are available to you in the code completion options as you type.

Left out of the above example, for example, is the selid attribute, which belongs in the same namespace as the select/when/otherwise elements. Because this attribute is allowed on any element except elements in the select namespace, a namespace prefix must be declared for it (i.e., it can never inherit a default xmlns declaration for the select namespace).

The Solution

Always declare and use namespace prefixes for elements and attributes not in the default namespace of your document.

The best place to declare the namespaces you intend to use is on the document element so that they are consistently applied throughout the document and anyone glancing at the file can quickly see which ones are in use. You can even break the declarations onto separate lines for clarity:

<document xmlns="http://www.daisy.org/ns/z3986/authoring/" xml:lang="en"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:sel="http://www.daisy.org/ns/z3986/authoring/features/select/">

The above example declares that all XLink atributes are identified by the prefix "xlink:", all elements and attributes from the Content Selection feature are prefixed by "sel:" and all elements in the document that don't have a prefix are in the default ZAI authoring namespace.

We could now write the example in the first section more legibly (and now completely) as:

<sel:select>
   <sel:when expr="target:format('BRAILLE')">
      <description sel:selid="desc" xlink:href="desc-br.xml"/>
   </sel:when>
   <sel:otherwise>
      <description sel:selid="desc" xlink:href="desc.xml"/>
   </sel:otherwise>
</sel:select>

It's now obvious which namespace the elements and attributes belong to, and the tagging is no longer cluttered by xmlns attributes re-declaring the correct namespace to use.

Common ZAI Namespaces

The following namespaces commonly occur in ZAI documents. The declarations are provided for quick copy and pasting to your root document element.

   xmlns:its="http://www.w3.org/2005/11/its"
   xmlns:m="http://www.w3.org/1998/Math/MathML"
   xmlns:rend="http://www.daisy.org/ns/z3986/authoring/features/rend/"
   xmlns:sel="http://www.daisy.org/ns/z3986/authoring/features/select/"
   xmlns:ssml="http://www.w3.org/2001/10/synthesis"
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns:xforms="http://www.w3.org/2002/xforms/"
   xmlns:xlink="http://www.w3.org/1999/xlink"

Note: although the prefix you use for any namespace can be anything you like, conventions like "xlink:" for XLink attributes and "m:" for MathML are widely recognized and quickly understood. The above prefixes should be used unless there is a good reason to alter them.