1.2 (2019-02-09)

External Namespaces

This is a draft specification. It is likely that changes will still be made before the final specification.

Mallard allows elements and attributes from external namespaces to be used in well-defined places throughout the language. External-namespace elements and attributes allow extensions to add functionality to Mallard, while keeping the core Mallard specification simple.


  • All elements in Mallard can have attributes from external namespaces. This can be used to clarify the meaning of an element in a particular context, to provide additional information to processing tools, or to embed richer semantic data into a document.

  • Any external-namespace element can be used in an info element to provide additional information about a page or section. External-namespace informational elements are ignored if not understood. See Processing Expectations on Informational Elements for details.

  • External-namespace elements can also be used inside some informational elements with structured content, such as credit, link, and revision. In these elements, any elements that are not understood are ignored.

  • External-namespace elements can be used in any block context. When not understood, these are processed in a restricted block context. See Block Processing Expectations for details.

  • External-namespace elements can be used in any inline context. When not understood, these are processed as if they were replaced by their child content. See Inline Processing Expectations for details.


A translation tool might copy code blocks directly into the translated document without presenting them to translators. Force a code block to be translated using the its:translate attribute from the Internationalization Tag Set:

<code xmlns:its="http://www.w3.org/2005/11/its" 
      its:version="1.0" its:translate="yes">
// This code block should be translated because it contains this comment.
some_code ()

In an info element, elements can be taken from RDF vocabularies to provide additional information about a page. Specify a bug database using DOAP:

<info xmlns:doap="http://usefulinc.com/ns/doap#"
  <doap:bug-database rdf:resource="http://bugs.example.com/"/>

Inline elements can be borrowed from other formats. Use Ruby Annotation inside a paragraph:

<ruby xmlns="http://www.w3.org/1999/xhtml">

紙芝居 (かみしばい)

Processing Expectations

When an element or attribute from an external namespace is understood, they are processed according to the expectations of the defining specification.

When an external-namespace attribute is not understood on any element, it is always ignored.

How external-namespace elements are handled when not understood depends on context. In an informational context, they are ignored. In a block context, their child content is processed in a restricted block context. In an inline context, they are processed as if they were replaced by their child content.

Comparison to Other Formats

DocBook 4 does not use namespaces, but provides a customizable DTD definition that allows explicit extension. DocBook 5 uses namespaces and is defined by a RELAX NG schema. Although the schema is designed to be customizable for extensions, arbitrary external-namespace content will not validate against the base schema.

DITA does not use namespaces, and is defined by a DTD. The DITA DTD allows customizations by specializing base element types. Using #IMPLIED attribute values in the DTD allows these to fall back by any compliant processing tool. This method works well for refinements to meet domain criteria, but it does not allow arbitrary extensions for new features.


The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the external-namespace elements and attributes. The namespace declarations for these definitions are on the page Pages.

mal_external = element * - (mal:* | local:*) {
  attribute * { text } *,
  ( mal_anything * &
    text ?
mal_anything = element * {
  attribute * { text } *,
  ( mal_anything * &
    text ?
mal_attr_external = attribute * - (mal:* | local:*) { text }
© 2008 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by