Mallard Version

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

The version attribute allows you to specify the version of Mallard you are using, as well as the versions of any Mallard extensions. Future versions of Mallard using the same XML namespace, will make backwards-compatible additions. Mallard is also designed to be extended using elements and attributes from external namespaces. Use the version attribute to signal the version and extensions to a processing tool or validator.

Notes

The version attribute takes a space-separated list of version tokens that identify the Mallard version and the versions of extensions used in a page.
The version attribute can occur on any page element.
Each version token corresponds to a RELAX NG file, either by referencing it with a fully-qualified URI, or by using a shorthand syntax for schemas hosted on projectmallard.org.

Examples

Specify that you are only using features from Mallard 1.2:

<page xmlns="http://projectmallard.org/1.0/"
      version="1.2"
      id="index">

Specify that you are using Mallard 1.2 plus the 1.0 version of the conditional processing extension:

<page xmlns="http://projectmallard.org/1.0/"
      version="1.2 if/1.0"
      id="index">

Specify that you are using Mallard 1.2 plus two extensions:

<page xmlns="http://projectmallard.org/1.0/"
      version="1.2 if/1.0 facet/1.0"
      id="index">

Versions and extensions hosted on projectmallard.org can use an abbreviated form. For extensions hosted elsewhere, you must use a full URL to a RELAX NG schema. Specify that you are using Mallard 1.2 plus an extension hosted elsewhere:

<page xmlns="http://projectmallard.org/1.0/"
      version="1.2 http://example.com/ducks/1.0/ducks-1.0.rng"
      id="index">

Processing Expectations

Tools for viewing or editing Mallard documents may adjust their behavior according to the version attribute. For example, an editor might offer only those elements that are valid according to the specified version. This is not required, however, and this document makes no specifications on the behavior of such tools.

The behavior for validators is specified. Mallard and its extensions are defined using RELAX NG schemas. The core Mallard schema can be used by any validator on its own. Extension schemas define only additional interfaces, or possibly remove interfaces, and are not necessarily usable on their own. Extension schemas are expected to be structured such that they can be combined with other schemas using the method described on this page.

The version attribute takes a space-separated list of version tokens. Each version token maps to a RELAX NG file, according to the following rules:

If the token contains a colon (U+003A), it is taken to be an absolute URI to a RELAX NG file.
If the token contains a single slash (U+002F), it is split into the prefix before the slash and the number after the slash, and the URL to the RELAX NG file is constructed as follows:
```
http://projectmallard.org/prefix/number/prefix-number.rng
```
If the token contains no colon or slash character, it is taken to be a simple version number token, and the URL to the RELAX NG file is constructed as follows:
```
http://projectmallard.org/token/mallard-token.rng
```

The schema corresponding to the first version token is the primary schema. Because Mallard schemas explicitly allow elements and attribute from external namespaces in well-defined places, pages using extensions will usually be able to be validated against the primary schema only. Combining the schemas, however, allows for stricter validation of the extensions.

Unfortunately, RELAX NG does not allow name classes to be extended. Name classes are used by the Mallard schema to provide patterns for elements and attributes from external namespaces. When mixing in an extension schema, the namespaces used by that schema need to be added to the name class. Although it is possible for a single extension to redefine the pattern that holds the name class, this does not work when loading multiple extensions.

Consequently, extension schemas cannot be mixed using standard RELAX NG inclusion mechanisms. Instead, this page details how to create a new schema from a primary schema and any number of extension schemas.

A new RELAX NG grammar is constructed by creating a new top-level grammar element and recursively copying into it the contents of the grammar elements of each of the schemas, making the following transformations:

All element and attribute elements are rewritten to state the namespace explicitly using the ns attribute. The default namespace and the namespace prefixes defined on each schema's grammar element are not available when they are copied into the constructed schema.
Any start element from a non-primary schema that does not have a valid combine attribute is dropped.
A set of valid namespace URIs is constructed by extracting the following from each schema's grammar element:
- The ns attribute
- Any namespace declared with a prefix using xmlns:, except the implicitly-defined namespace http://www.w3.org/XML/1998/namespace with the namespace xml
- The default namespace declared using xmlns, unless the default namespace is http://relaxng.org/ns/structure/1.0
- The empty string
Duplicates are removed. In each schema, any except element inside an anyName element is rewritten as in the following XSLT, assuming the variable $namespaces is a node set whose elements have string values holding the valid namespaces defined above:
```
<except>
  <xsl:for-each select="$namespaces">
    <nsName ns="{.}"/>
  </xsl:for-each>
</except>
```

The resultant schema is used to validate the page.

Schema

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 version attribute. The namespace declarations for this definition are on the page Pages.

mal_attr_version = attribute version { text }