RELAX NG Specification

Suppose the document http://www.example.com/doc.xml is as follows:

<?xml version="1.0"?>
<foo><pre1:bar1 xmlns:pre1="http://www.example.com/n1"/><pre2:bar2
  xmlns:pre2="http://www.example.com/n2"/></foo>

The element representing this document has

Here is an example of a schema in the full syntax for the document in Section 2.1.

<?xml version="1.0"?>
<element name="foo"
         xmlns="http://relaxng.org/ns/structure/1.0"
         xmlns:a="http://relaxng.org/ns/annotation/1.0"
         xmlns:ex1="http://www.example.com/n1"
         xmlns:ex2="http://www.example.com/n2">
  <a:documentation>A foo element.</a:document>
  <element name="ex1:bar1">
    <empty/>
  </element>
  <element name="ex2:bar2">
    <empty/>
  </element>
</element>

Foreign attributes and elements are removed.

For each element other than value and param, each child that is a string containing only whitespace characters is removed.

Leading and trailing whitespace characters are removed from the value of each name, type and combine attribute and from the content of each name element.

The value of each datatypeLibary attribute is transformed by escaping disallowed characters as specified in Section 5.4 of [XLink].

For any data or value element that does not have a datatypeLibrary attribute, a datatypeLibrary attribute is added. The value of the added datatypeLibrary attribute is the value of the datatypeLibrary attribute of the nearest ancestor element that has a datatypeLibrary attribute, or the empty string if there is no such ancestor. Then, any datatypeLibrary attribute that is on an element other than data or value is removed.

For any value element that does not have a type attribute, a type attribute is added with value token and the value of the datatypeLibrary attribute is changed to the empty string.

The value of the href attribute on an externalRef or include element is first transformed by escaping disallowed characters as specified in Section 5.4 of [XLink]. The URI reference is then resolved into an absolute form as described in section 5.2 of [RFC 2396] using the base URI from the context of the element that bears the href attribute.

The value of the href attribute will be used to construct an element (as specified in Section 2). This must be done as follows. The URI reference consists of the URI itself and an optional fragment identifier. The resource identified by the URI is retrieved. The result is a MIME entity: a sequence of bytes labeled with a MIME media type. The media type determines how an element is constructed from the MIME entity and optional fragment identifier. When the media type is application/xml or text/xml, the MIME entity must be parsed as an XML document in accordance with the applicable RFC (at the term of writing [RFC 3023]) and an element constructed from the result of the parse as specified in Section 2. In particular, the charset parameter must be handled as specified by the RFC. This specification does not define the handling of media types other than application/xml and text/xml. The href attribute must not include a fragment identifier unless the registration of the media type of the resource identified by the attribute defines the interpretation of fragment identifiers for that media type.

An externalRef element is transformed as follows. An element is constructed using the URI reference that is the value of href attribute as specified in Section 4.5. This element must match the syntax for pattern. The element is transformed by recursively applying the rules from this subsection and from previous subsections of this section. This must not result in a loop. In other words, the transformation of the referenced element must not require the dereferencing of an externalRef attribute with an href attribute with the same value.

Any ns attribute on the externalRef element is transferred to the referenced element if the referenced element does not already have an ns attribute. The externalRef element is then replaced by the referenced element.

An include element is transformed as follows. An element is constructed using the URI reference that is the value of href attribute as specified in Section 4.5. This element must be a grammar element, matching the syntax for grammar.

This grammar element is transformed by recursively applying the rules from this subsection and from previous subsections of this section. This must not result in a loop. In other words, the transformation of the grammar element must not require the dereferencing of an include attribute with an href attribute with the same value.

Define the components of an element to be the children of the element together with the components of any div child elements. If the include element has a start component, then the grammar element must have a start component. If the include element has a start component, then all start components are removed from the grammar element. If the include element has a define component, then the grammar element must have a define component with the same name. For every define component of the include element, all define components with the same name are removed from the grammar element.

The include element is transformed into a div element. The attributes of the div element are the attributes of the include element other than the href attribute. The children of the div element are the grammar element (after the removal of the start and define components described by the preceding paragraph) followed by the children of the include element. The grammar element is then renamed to div.

The name attribute on an element or attribute element is transformed into a name child element.

If an attribute element has a name attribute but no ns attribute, then an ns="" attribute is added to the name child element.

For any name, nsName or value element that does not have an ns attribute, an ns attribute is added. The value of the added ns attribute is the value of the ns attribute of the nearest ancestor element that has an ns attribute, or the empty string if there is no such ancestor. Then, any ns attribute that is on an element other than name, nsName or value is removed.

For any name element containing a prefix, the prefix is removed and an ns attribute is added replacing any existing ns attribute. The value of the added ns attribute is the value to which the namespace map of the context of the name element maps the prefix. The context must have a mapping for the prefix.

Each div element is replaced by its children.

A define, oneOrMore, zeroOrMore, optional, list or mixed element is transformed so that it has exactly one child element. If it has more than one child element, then its child elements are wrapped in a group element. Similarly, an element element is transformed so that it has exactly two child elements, the first being a name class and the second being a pattern. If it has more than two child elements, then the child elements other than the first are wrapped in a group element.

A except element is transformed so that it has exactly one child element. If it has more than one child element, then its child elements are wrapped in a choice element.

If an attribute element has only one child element (a name class), then a text element is added.

A choice, group or interleave element is transformed so that it has exactly two child elements. If it has one child element, then it is replaced by its child element. If it has more than two child elements, then the first two child elements are combined into a new element with the same name as the parent element and with the first two child elements as its children. For example,

<choice> p1 p2 p3 </choice>

is transformed to

<choice> <choice> p1 p2 </choice> p3 </choice>

This reduces the number of child elements by one. The transformation is applied repeatedly until there are exactly two child elements.

A mixed element is transformed into an interleaving with a text element:

<mixed> p </mixed>

is transformed into

<interleave> p <text/> </interleave>

An optional element is transformed into a choice with empty:

<optional> p </optional>

is transformed into

<choice> p <empty/> </choice>

A zeroOrMore element is transformed into a choice between oneOrMore and empty:

<zeroOrMore> p </zeroOrMore>

is transformed into

<choice> <oneOrMore> p </oneOrMore> <empty/> </choice>

In this rule, no transformation is performed, but various constraints are checked.

An except element that is a child of an anyName element must not have any anyName descendant elements. An except element that is a child of an nsName element must not have any nsName or anyName descendant elements.

A name element that occurs as the first child of an attribute element or as the descendant of the first child of an attribute element and that has an ns attribute with value equal to the empty string must not have content equal to xmlns.

A name or nsName element that occurs as the first child of an attribute element or as the descendant of the first child of an attribute element must not have an ns attribute with value http://www.w3.org/2000/xmlns.

A data or value element must be correct in its use of datatypes. Specifically, the type attribute must identify a datatype within the datatype library identified by the value of the datatypeLibrary attribute. For a data element, the parameter list must be one that is allowed by the datatype (see Section 6.2.8).

For each grammar element, all define elements with the same name are combined together. For any name, there must not be more than one define element with that name that does not have a combine attribute. For any name, if there is a define element with that name that has a combine attribute with the value choice, then there must not also be a define element with that name that has a combine attribute with the value interleave. Thus, for any name, if there is more than one define element with that name, then there is a unique value for the combine attribute for that name. After determining this unique value, the combine attributes are removed. A pair of definitions

<define name="n">
  p1
</define>
<define name="n">
  p2
</define>

is combined into

<define name="n">
  <c>
    p1
    p2
  </c>
</define>

where c is the value of the combine attribute. Pairs of definitions are combined until there is exactly one define element for each name.

Similarly, for each grammar element all start elements are combined together. There must not be more than one start element that does not have a combine attribute. If there is a start element that has a combine attribute with the value choice, there must not also be a start element that has a combine attribute with the value interleave.

In this rule, the schema is transformed so that its top-level element is grammar and so that it has no other grammar elements.

Define the in-scope grammar for an element to be the nearest ancestor grammar element. A ref element refers to a define element if the value of their name attributes is the same and their in-scope grammars are the same. A parentRef element refers to a define element if the value of their name attributes is the same and the in-scope grammar of the in-scope grammar of the parentRef element is the same as the in-scope grammar of the define element. Every ref or parentRef element must refer to a define element. A grammar must have a start child element.

First, transform the top-level pattern p into <grammar><start>p</start></grammar>. Next, rename define elements so that no two define elements anywhere in the schema have the same name. To rename a define element, change the value of its name attribute and change the value of the name attribute of all ref and parentRef elements that refer to that define element. Next, move all define elements to be children of the top-level grammar element, replace each nested grammar element by the child of its start element and rename each parentRef element to ref.

In this rule, the grammar is transformed so that every element element is the child of a define element, and the child of every define element is an element element.

First, remove any define element that is not reachable. A define element is reachable if there is reachable ref element referring to it. A ref element is reachable if it is the descendant of the start element or of a reachable define element. Now, for each element element that is not the child of a define element, add a define element to the grammar element, and replace the element element by a ref element referring to the added define element. The value of the name attribute of the added define element must be different from value of the name attribute of all other define elements. The child of the added define element is the element element.

Define a ref element to be expandable if it refers to a define element whose child is not an element element. For each ref element that is expandable and is a descendant of a start element or an element element, expand it by replacing the ref element by the child of the define element to which it refers and then recursively expanding any expandable ref elements in this replacement. This must not result in a loop. In other words expanding the replacement of a ref element having a name with value n must not require the expansion of ref element also having a name with value n. Finally, remove any define element whose child is not an element element.

In this rule, the grammar is transformed so that a notAllowed element occurs only as the child of a start or element element. An attribute, list, group, interleave, or oneOrMore element that has a notAllowed child element is transformed into a notAllowed element. A choice element that has two notAllowed child elements is transformed into a notAllowed element. A choice element that has one notAllowed child element is transformed into its other child element. An except element that has a notAllowed child element is removed. The preceding transformations are applied repeatedly until none of them is applicable any more. Any define element that is no longer reachable is removed.

In this rule, the grammar is transformed so that an empty element does not occur as a child of a group, interleave, or oneOrMore element or as the second child of a choice element. A group, interleave or choice element that has two empty child elements is transformed into an empty element. A group or interleave element that has one empty child element is transformed into its other child element. A choice element whose second child element is an empty element is transformed by interchanging its two child elements. A oneOrMore element that has an empty child element is transformed into an empty element. The preceding transformations are applied repeatedly until none of them is applicable any more.

The following is an example of how the schema in Section 3.1 can be transformed into the simple syntax:

<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
  <start>
    <ref name="foo.element"/>
  </start>

  <define name="foo.element">
    <element>
      <name ns="">foo</name>
      <group>
        <ref name="bar1.element"/>
        <ref name="bar2.element"/>
      </group>
    </element>
  </define>

  <define name="bar1.element">
    <element>
      <name ns="http://www.example.com/n1">bar1</name>
      <empty/>
    </element>
  </define>

  <define name="bar2.element">
    <element>
      <name ns="http://www.example.com/n2">bar2</name>
      <empty/>
    </element>
  </define>
</grammar>

The main semantic concept for name classes is that of a name belonging to a name class. A name class is an element that matches the production nameClass. A name is as defined in Section 2: it consists of a namespace URI and a local name.

We use the following notation:

We are now ready for our first axiom, which is called "anyName 1":

This says for any name n, n belongs to the name class <anyName/>, in other words <anyName/> matches any name. Note the effect of the implicit universal quantification over the variables in the axiom: this is what makes the axiom apply for any name n.

Our first inference rule is almost as simple:

This says that for any name n and for any name class nc, if n does not belong to nc, then n belongs to <anyName> <except> nc </except> </anyName>. In other words, <anyName> <except> nc </except> </anyName> matches any name that does not match nc.

We now need the following additional notation:

The remaining axioms and inference rules for name classes are as follows:

The axioms and inference rules for patterns use the following notation:

Now we can define when an element is valid with respect to a schema. We use the following additional notation:

An element is valid if together with an empty set of attributes it matches the start pattern of the grammar.

Let e₀ be

where m is

and e₁ is

and e₂ is

Assuming appropriate definitions of cx₀, cx₁ and cx₂, this represents the document in Section 2.1.

We now show how e₀ can be shown to be valid with respect to the schema in Section 5.1. The schema is equivalent to the following propositions:

Let name class nc₁ be

and let nc₂ be

Then, by the inference rule (name) in Section 6.1, we have

and

By the inference rule (empty) in Section 6.2.3, we have

and

Thus by the inference rule (element) in Section 6.2.7, we have

Note that we have chosen cx₀, since any context is allowed.

Likewise, we have

By the inference rule (group) in Section 6.2.1, we have

By the inference rule (element) in Section 6.2.7, we have

Here cx₃ is an arbitrary context.

Thus we can apply the inference rule (valid) in Section 6.3 and obtain

In this section we describe restrictions on where elements are allowed in the schema based on the names of the ancestor elements. We use the concept of a prohibited path to describe these restrictions. A path is a sequence of NCNames separated by / or //.

For example, the element

<foo>
  <bar>
    <baz/>
  </bar>
</foo>

matches the paths foo, foo/bar, foo//bar, foo//baz, foo/bar/baz, foo/bar//baz and foo//bar/baz, but not foo/baz or foobar.

A correct RELAX NG schema must be such that, after transformation to the simple form, it does not contain any element that matches a prohibited path.

RELAX NG does not allow a pattern such as:

<element name="foo">
  <group>
    <data type="int"/>
    <element name="bar">
      <empty/>
    </element>
  </group>
</element>

Nor does it allow a pattern such as:

<element name="foo">
  <group>
    <data type="int"/>
    <text/>
  </group>
</element>

More generally, if the pattern for the content of an element or attribute contains

then the two patterns must be alternatives to each other.

This rule does not apply to patterns occurring within a list pattern.

To formalize this, we use the concept of a content-type. A pattern that is allowable as the content of an element has one of three content-types: empty, complex and simple. We use the following notation.

The empty content-type is groupable with anything. In addition, the complex content-type is groupable with the complex content-type. The following rules formalize this.

Some patterns have a content-type. We use the following additional notation.

The following rules define when a pattern has a content-type and, if so, what it is.

Now we can describe the restriction. We use the following notation.

All patterns occurring as the content of an element pattern must have a content-type.

Duplicate attributes are not allowed. More precisely, for a pattern <group> p1 p2 </group> or <interleave> p1 p2 </interleave>, there must not be a name that belongs to both the name class of an attribute pattern occurring in p1 and the name class of an attribute pattern occurring in p2. A pattern p1 is defined to occur in a pattern p2 if

Attributes using infinite name classes must be repeated. More precisely, an attribute element that has an anyName or nsName descendant element must have a oneOrMore ancestor element.

For a pattern <interleave> p1 p2 </interleave>,

Section 7.3 defines when one pattern is considered to occur in another pattern.