$Id: tutorial.xml,v 1.63 2001/08/10 08:05:00 jjc Exp $ JamesClark

jjc@jclark.com

MURATAMakoto

mura034@attglobal.net

10 August 2001 $Id: tutorial.xml,v 1.63 2001/08/10 08:05:00 jjc Exp $ 2001OASIS Copyright © The Organization for the Advancement of Structured Information Standards [OASIS] 2001. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns. This document and the information contained herein is provided on an AS IS basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. This committee specification was approved for publication by the OASIS RELAX NG technical committee. Comments on this document may be sent to relax-ng-comment@lists.oasis-open.org. RELAX NG is a simple schema language for XML, based on and . A RELAX NG schema specifies a pattern for the structure and content of an XML document. A RELAX NG schema thus identifies a class of XML documents consisting of those documents that match the pattern. A RELAX NG schema is itself an XML document. This document is a tutorial for RELAX NG version 0.9. Committee Specification 10 August 2001 Working Draft 12 June 2001

Consider a simple XML representation of an email address book: John Smith js@example.com Fred Bloggs fb@example.net ]]> The DTD would be as follows: ]>]]> A RELAX NG pattern for this could be written as follows: ]]> If the addressBook is required to be non-empty, then we can use oneOrMore instead of zeroOrMore: ]]> Now let's change it to allow each card to have an optional note element. ]]> Note that the text pattern matches arbitrary text, including empty text. Note also that whitespace separating tags is ignored when matching against a pattern. All the elements specifying the pattern must be namespace qualified by the namespace URI: http://relaxng.org/ns/structure/0.9 The examples above use a default namespace declaration xmlns="http://relaxng.org/ns/structure/0.9" for this. A namespace prefix is equally acceptable: ]]> For the remainder of this document, the default namespace declaration will be left out of examples.

Now suppose we want to allow the name to be broken down into a givenName and a familyName, allowing an addressBook like this: John Smith js@example.com Fred Bloggs fb@example.net ]]> We can use the following pattern: ]]> This corresponds to the following DTD: ]>]]>

Suppose we want the card element to have attributes rather than child elements. The DTD might look like this ]>]]> Just change each element pattern to an attribute pattern: ]]> In XML, the order of attributes is traditionally not significant. RELAX NG follows this tradition. The above pattern would match both ]]> and ]]> In contrast, the order of elements is significant. The pattern ]]> would not match: js@example.comJohn Smith]]> Note that an attribute element by itself indicates a required attribute, just as an element element by itself indicates a required element. To specify an optional attribute, use optional just as with element: ]]> The group and choice patterns can be applied to attribute patterns in the same way they are applied to element patterns. For example, if we wanted to allow either a name attribute or both a givenName and a familyName attribute, we can specify this in the same way that we would if we were using elements: ]]> The group and choice patterns can combine element and attribute patterns without restriction. For example, the following pattern would allow a choice of elements and attributes independently for both the name and the email part of a card: ]]> As usual, the relative order of elements is significant, but the relative order of attributes is not. Thus the above would match any of: John Smith js@example.com John Smithjs@example.com]]> However, it would not match js@example.comJohn Smith]]> because the pattern for card requires any email child element to follow any name child element. There is one difference between attribute and element patterns: <text/> is the default for the content of an attribute pattern, whereas an element pattern is not allowed to be empty. For example, ]]> is short for ]]> It might seem natural that ]]> matched an x element with no attributes and no content. However, this would make the meaning of empty content inconsistent between the element pattern and the attribute pattern, so RELAX NG does not allow the element pattern to be empty. A pattern that matches an element with no attributes and no children must use <empty/> explicitly: ]]> Even if the pattern in an element pattern matches attributes only, there is no need to use empty. For example, ]]> is equivalent to ]]>

For a non-trivial RELAX NG pattern, it is often convenient to be able to give names to parts of the pattern. Instead of ]]> we can write ]]> A grammar element has a single start child element, and zero or more define child elements. The start and define elements contain patterns. These patterns can contain ref elements that refer to patterns defined by any of the define elements in that grammar element. A grammar pattern is matched by matching the pattern contained in the start element. We can use the grammar element to write patterns in a style similar to DTDs: ]]> Recursive references are allowed. For example ]]> However, recursive references must be within an element. Thus, the following is not allowed: ]]>

RELAX NG allows patterns to reference externally-defined datatypes, such as those defined by W3C XML Schema Part 2. RELAX NG implementations may differ in what datatypes they support. You must use datatypes that are supported by the implementation you plan to use. The data pattern matches a string that represents a value of a named datatype. The datatypeLibrary attribute contains a URI identifying the library of datatypes being used. The datatype library defined W3C XML Schema Part 2 would be identified by the URI http://www.w3.org/2001/XMLSchema-datatypes. The type attribute specifies the name of the datatype in the library identified by the datatypeLibrary attribute. For example, if a RELAX NG implementation supported the datatypes of W3C XML Schema Part 2, you could use: ]]> It is inconvenient to specify the datatypeLibrary attribute on every data element, so RELAX NG allows the datatypeLibrary attribute to be inherited. The datatypeLibrary attribute can be specified on any RELAX NG element. If a data element does not have a datatypeLibrary attribute, it will use the value from the closest ancestor that has a datatypeLibrary attribute. Typically, the datatypeLibrary attribute is specified on the root element of the RELAX NG pattern. For example: ]]> If the children of an element or an attribute match a data pattern, then complete content of the element or attribute must match that data pattern. It is not permitted to have a pattern which allows part of the content to match a data pattern, and another part to match another pattern. For example, the following pattern is not allowed: ]]> However, this would be fine: ]]> Note that this restriction does not apply to the text pattern. Datatypes may have parameters. For example, a string datatype may have a parameter controlling the length of the string. The parameters applicable to any particular datatype are determined by the datatyping vocabulary. Parameters are specified by adding one or more param elements as children of the data element. For example, the following constrains the email element to contain a string at most 127 characters long: 127 ]]>

Many markup vocabularies have attributes whose value is constrained to be one of set of specified values. The value pattern matches a string that has a specified value. For example, html text ]]> allows the preferredFormat attribute to have the value html or text. This corresponds to the DTD ]>]]> The value pattern is not restricted to attribute values. For example, the following is allowed: html text ]]> The prohibition against a data pattern's matching only part of the content of an element also applies to value patterns. By default, the value pattern will consider the string in the pattern to match the string in the document if the two strings are the same after the whitespace in both strings is normalized. Whitespace normalization strips leading and trailing white-space characters, and collapses sequences of one or more white-space characters to a single space character. This corresponds to the behaviour of an XML parser for an attribute that is declared as other than CDATA. Thus the above pattern will match any of ]]> The way that the value pattern compares the pattern string with the document string can be controlled by specifying a type attribute and optionally a datatypeLibrary attribute, which identify a datatype in the same way as for the data pattern. The pattern string matches the document string if they both represent the same value of the specified datatype. Thus, whereas the data pattern matches an arbitrary value of a datatype, the value pattern matches a specific value of a datatype. If there is no ancestor element with a datatypeLibrary element, the datatype library defaults to a built-in RELAX NG datatype library. This provides two datatypes, string and token. The built-in datatype token corresponds to the default comparison behavior of the value pattern. The built-in datatype string compares strings without any whitespace normalization (other than the end-of-line and attribute value normalization automatically performed by XML). For example, html text ]]> will not match ]]>

The list pattern matches a whitespace-separated sequence of tokens; it contains a pattern that the sequence of individual tokens must match. The list pattern splits a string into a list of strings, and then matches the resulting list of strings against the pattern inside the list pattern. For example, suppose we want to have a vector element that contains two floating point numbers separated by whitespace. We could use list as follows: ]]> Or suppose we want the vector element to contain a list of one or more floating point numbers separated by whitespace: ]]> Or suppose we want a path element containing an even number of floating point numbers: ]]>

The interleave pattern allows child elements to occur in any order. For example, the following would allow the card element to contain the name and email elements in any order: ]]> The pattern is called interleave because of how it works with patterns that match more than one element. Suppose we want to write a pattern for the HTML head element which requires exactly one title element, at most one base element and zero or more style, script, link and meta elements and suppose we are writing a grammar pattern that has one definition for each element. Then we could define the pattern for head as follows: ]]> Suppose we had a head element that contained a meta element, followed by a title element, followed by a meta element. This would match the pattern because it is an interleaving of a sequence of two meta elements, which match the child pattern ]]> and a sequence of one title element, which matches the child pattern ]]> The semantics of the interleave pattern are that a sequence of elements matches an interleave pattern if it is an interleaving of sequences that match the child patterns of the interleave pattern. Note that this is different from the & connector in SGML: A* & B matches the sequence of elements A A B or the sequence of elements B A A but not the sequence of elements A B A. One special case of interleave is very common: interleaving <text/> with a pattern p represents a pattern that matches what p matches but also allows characters to occur as children. The mixed element is a shorthand for this. ]]>p]]> is short for ]]>p]]>

The externalRef pattern can be used to reference a pattern defined in a separate file. The externalRef element has a required href attribute that specifies the URL of a file containing the pattern. The externalRef matches if the pattern contained in the specified URL matches. Suppose for example, you have a RELAX NG pattern that matches HTML inline content stored in inline.rng: ]]> Then we could allow the note element to contain inline HTML markup by using externalRef as follows: ]]> For another example, suppose you have two RELAX NG patterns stored in files pattern1.rng and pattern2.rng. Then the following is a pattern that matches anything matched by either of those patterns: ]]>

If a grammar contains multiple definitions with the same name, then the definitions must specify how they are to be combined into a single definition by using the combine attribute. The combine attribute may have the value choice or interleave. For example: ]]> is equivalent to ]]> When combining attributes, combine="interleave" is typically used. For example: ]]> is equivalent to ]]> which is equivalent to ]]> since combining attributes with interleave has the same effect as combining them with group. It is an error for two definitions of the same name to specify different values for combine. Note that the order of definitions within a grammar is not significant. Multiple start elements can be combined in the same way as multiple definitions.

The include element allows grammars to be merged together. A grammar pattern may have include elements as children. An include element has a required href attribute that specifies the URL of a file containing a grammar pattern. The definitions in the referenced grammar pattern will be included in grammar pattern containing the include element. The combine attribute is particularly useful in conjunction with include. For example, suppose a RELAX NG pattern inline.rng provides a pattern for inline content, which allows bold and italic elements arbitrarily nested: ]]> Another RELAX NG pattern could use inline.rng and add code and em to the set of inline elements as follows: ]]> This would be equivalent to ]]> which is equivalent to ]]> Note that it is allowed for one of the definitions of a name to omit the combine attribute. However, it is an error if there is more than one definition that does so. The notAllowed pattern is useful when merging grammars. The notAllowed pattern never matches anything. Just as adding empty to a group makes no difference, so adding notAllowed to a choice makes no difference. It is typically used to allow an including pattern to specify additional choices with combine="choice". For example, if inline.rng were written like this ]]> then it could be customized to allow inline code and code elements as follows ]]>

RELAX NG allows define elements to be put inside the include element to indicate that they are to replace definitions in the included grammar pattern. Suppose the file addressBook.rng contains: ]]> Suppose we wish to modify this pattern so that the card element contains an emailAddress element instead of an email element. Then we could replace the definition of cardContent as follows: ]]> This would be equivalent to ]]> An include element can also contain a start element, which replaces the start in the included grammar pattern.

RELAX NG is namespace-aware. Thus, it considers an element or attribute to have both a local name and a namespace URI which together constitute the name of that element or attribute.

The element pattern uses a ns attribute to specify the namespace URI of the elements that it matches. For example ]]> would match any of ]]> but not any of ]]> A value of an empty string for the ns attribute indicates a null or absent namespace URI (just as with the xmlns attribute). Thus, the pattern ]]> matches any of ]]> but not any of ]]> It is tedious and error-prone to specify the ns attribute on every element, so RELAX NG allows it to be defaulted. If an element pattern does not specify a ns attribute, then it defaults to the value of the ns attribute of the nearest ancestor that has a ns attribute, or the empty string if there is no such ancestor. Thus ]]> is equivalent to ]]> and ]]> is equivalent to ]]> The attribute pattern also takes a ns attribute. However, there is a difference in how it defaults. This is because of the fact that the XML Namespaces Recommendation does not apply the default namespace to attributes. If a ns attribute is not specified on the attribute pattern, then it defaults to the empty string. Thus ]]> is equivalent to ]]> and so will match ]]> or ]]> but not ]]>

When a pattern matches elements and attributes from multiple namespaces, using the ns attribute would require repeating namespace URIs in different places in the pattern. This is error-prone and hard to maintain, so RELAX NG also allows the element and attribute patterns to use a prefix in the value of the name attribute to specify the namespace URI. In this case, the prefix specifies the namespace URI to which that prefix is bound by the namespace declarations in scope on the element or attribute pattern. Thus ]]> is equivalent to ]]> If a prefix is specified in the value of the name attribute of an element or attribute pattern, then that prefix determines the namespace URI of the elements or attributes that will be matched by that pattern, regardless of the value of any ns attribute. Note that the XML default namespace (as specified by the xmlns attribute) is not used in determining the namespace URI of elements and attributes that element and attribute patterns match.

Normally, the name of the element to be matched by an element element is specified by a name attribute. An element element can instead start with an element specifying a name-class. In this case, the element pattern will only match an element if the name of the element is a member of the name-class. The simplest name-class is anyName, which any name at all is a member of, regardless of its local name and its namespace URI. For example, the following pattern matches any well-formed XML document: ]]> The nsName name-class contains any name with the namespace URI specified by the ns attribute, which defaults in the same way as the ns attribute on the element pattern. The choice name-class matches any name that is a member of any of its child name-classes. The anyName and nsName name-classes can contain an except clause. For example ]]> would allow the card element to have any number of namespace-qualified attributes provided that they were qualified with namespace other than that of the card element. Note that an attribute pattern matches a single attribute even if it has a name-class that contains multiple names. To match zero or more attributes, the zeroOrMore element must be used. The name name-class contains a single name. The content of the name element specifies the name in the same way as the name attribute of the element pattern. The ns attribute specifies the namespace URI in the same way as the element pattern. Some schema languages have a concept of lax validation, where an element or attribute is validated against a definition only if there is one. We can implement this concept in RELAX NG with name classes that uses except and name. Suppose, for example, we wanted to allow an element to have any attribute with a qualified name, but we still wanted to ensure that if there was an xml:space attribute, it had the value default or preserve. It wouldn't work to use: default preserve ]]> because an xml:space attribute with a value other than default or preserve would match ]]> even though it did not match default preserve ]]> The solution is to use name together with except: xml:space default preserve ]]> Note that the define element cannot contain a name-class; it can only contain a pattern.

If a RELAX NG element has an attribute or child element with a namespace URI other than the RELAX NG namespace, then that attribute or element is ignored. Thus, you can add annotations to RELAX NG patterns simply by using an attribute or element in a separate namespace: Information about a single email address. ]]> RELAX NG also provides a div element which allows an annotation to be applied to a group of definitions in a grammar. For example, you might want to divide up the definitions of the grammar into modules: <grammar xmlns:m="http://www.example.com/module"> <div m:name="inline"> <define name="code"> pattern </define> <define name="em"> pattern </define> <define name="var"> pattern </define> </div> <div m:name="block"> <define name="p"> pattern </define> <define name="ul"> pattern </define> <define name="ol"> pattern </define> </div> </grammar> This would allow you easily to generate variants of the grammar based on a selection of modules. A companion specification, RELAX NG DTD Compatibility Annotations , defines annotations to implement some features of XML DTDs.

There is no prohibition against nesting grammar patterns. A ref pattern refers to a definition from nearest grammar ancestor. There is also a parentRef element that escapes out of the current grammar and references a definition from the parent of the current grammar. Imagine the problem of writing a pattern for tables. The pattern for tables only cares about the structure of tables; it doesn't care about what goes inside a table cell. First, we create a RELAX NG pattern table.rng as follows: ]]> Patterns that include table.rng must redefine cell.content. By using a nested grammar pattern containing a parentRef pattern, the including pattern can redefine cell.content to be a pattern defined in the including pattern's grammar, thus effectively importing a pattern from the parent grammar into the child grammar: ]]> Of course, in a trivial case like this, there is no advantage in nesting the grammars: we could simply have included table.rng within the outer grammar element. However, when the included grammar has many definitions, nesting it avoids the possibility of name conflicts between the including grammar and the included grammar.

RELAX NG does not require patterns to be "deterministic" or "unambiguous". Suppose we wanted to write the email address book in HTML, but use class attributes to specify the structure. addressBook card name givenName familyName email ]]> This would match a XML document such as:

John Smith

js@example.com

]]> but not

John Smith

js@example.com

]]>

The definitive specification of RELAX NG is .

RELAX NG provides functionality that goes beyond XML DTDs. In particular, RELAX NG uses XML syntax to represent schemas supports datatyping integrates attributes into content models supports XML namespaces supports unordered content supports context-sensitive content models ID/IDREF validation is not provided by RELAX NG; however, it is provided by a companion specification, RELAX NG DTD Compatibility Annotations . Comprehensive support for cross-reference checking is planned for a future specification. RELAX NG does not support features of XML DTDs that involve changing the infoset of an XML document. In particular, RELAX NG does not allow defaults for attributes to be specified; however, this is allowed by RELAX NG DTD Compatibility Annotations does not allow entities to be specified does not allow notations to be specified does not specify whether white-space is significant Also RELAX NG does not define a way for an XML document to associate itself with a RELAX NG pattern. Any description in RELAX Core can be directly captured in RELAX NG without loss of information.

An elementRule as well as the referenced tag element is typically captured by a define element containing an element element as the child. An elementRule-tag pair in RELAX Core is shown below: <elementRule role="foo" label="bar"> hedge model </elementRule> <tag role="foo" name="baz"> attribute declarations </tag> A rewrite in RELAX NG is shown below: <define name="bar"> <element name="baz"> hedge model attribute declarations </element> </define>

A hedgeRule element is captured by a define element containing attribute declarations. A hedgeRule element in RELAX Core is shown below: <hedgeRule label="bar"> hedge model </hedgeRule> A rewrite in RELAX NG is <define name="bar"> hedge model </define>

An attPool element in RELAX Core is shown below: <attPool role="foo"> attribute declarations </attPool> A rewrite in RELAX NG is <define name="foo"> attribute declarations </define>

Mapping of hedge models in RELAX Core to RELAX NG is summaized below: occurs="*" in RELAX Core is captured by <zeroOrMore>...</zeroOrMore>. occurs="+" in RELAX Core is captured by <oneOrMore>...</oneOrMore> occurs="?" in RELAX Core is captured by <optional>...</optional> <mixed>...</mixed> in RELAX Core is captured by <mixed>...</mixed> <ref label="..."/> in RELAX Core is captured by <ref name="..."/>. <hedgeRef label="..."/> in RELAX Core is captured by <ref name="..."/>

Both languages use attribute. However, in RELAX Core, an attribute without required="true" declares a defaultable attribute. On the other hand, in RELAX NG, a defaultable attribute has to be declared by an attribute element within an optional element. Declaration of a required attribute in RELAX Core is shown below: <attribute name="foo" type="integer" required="true"/> In RELAX NG, this is captured by <attribute name="foo"> <data type="integer"/> </attribute> Declaration of an optional attribute in RELAX Core is shown below: <attribute name="foo" type="integer"/> In RELAX NG, this is captured by <optional> <attribute name="foo"> <data type="integer"/> </attribute> </optional>

Here is a rewrite of an example in STEP 7 of "HOW TO RELAX". The first paragraph cannot contain footnotes, but the other paragraphs can. <grammar> <start> <element name="doc"> <ref name="paraWithoutFNotes"/> <zeroOrMore> <ref name="paraWithFNotes"/> </zeroOrMore> </element> </start> <define name="paraWithoutFNotes"> <element name="para"> <text/> </element> </define> <define name="paraWithFNotes"> <element name="para"> <mixed> <zeroOrMore> <element name="fnote"> <text/> </element> </zeroOrMore> </mixed> </element> </define> </grammar> The following document matches this pattern. <doc><para/><para><fnote/></para></doc> On the other hand, the following document does not. <doc><para><fnote/></para></doc>

Here is a rewrite of an example in STEP 8 of "HOW TO RELAX". This pattern assigns different content models for the same tag name div depending on the value of the attribute class. <grammar> <start> <element name="html"> <zeroOrMore> <ref name="section"/> </zeroOrMore> </element> </start> <define name="section"> <element name="div"> <attribute name="class"><value>section</value></attribute> <zeroOrMore> <element name="para"> <text/> </element> </zeroOrMore> <zeroOrMore> <ref name="subsection"/> </zeroOrMore> </element> </define> <define name="subsection"> <element name="div"> <attribute name="class"><value>subsection</value></attribute> <zeroOrMore> <element name="para"> <text/> </element> </zeroOrMore> </element> </define> </grammar> The following document matches this pattern. <html> <div class="section"> <para/> <div class="subsection"> <para/> </div> </div> <div class="section"> <div class="subsection"> <para/> </div> </div> </html> On the other hand, the following document does not. <html> <div class="subsection"> <para/> <div class="section"> <para/> </div> </div> </html>

RELAX NG has some features which are missing in RELAX Core. Namespaces: since RELAX Core is intended to be used in conjunction with RELAX Namespace, RELAX Core does not support namespaces. On the other hand, RELAX NG supports namespaces. RELAX Namespace will be extended so that it can work with RELAX NG. Mixture of element and attribute: RELAX Core does not allow their mixture but rather provide two types of basic constructs, namely elementRule/hedgeRule and tag/attPool. Name classes: RELAX Core does not have name classes but merely provide name literals. interleave: RELAX Core does not provide any mechanism for interleaving. Datatype libraries: RELAX Core allows XML Schema Part 2 but does not allow other datatype libaries. define in include: RELAX Core does not allow such redefinitions. list: RELAX Core does not provide such structured strings. data in choice: in RELAX Core, the hedge model of elementRule is either a datatype reference or an expression without datatype references.

RELAX NG has the following changes from TREX: the concur pattern has been removed the string pattern has been replaced by the value pattern the anyString pattern has been renamed to text the namespace URI is different pattern elements must be namespace qualified anonymous datatypes have been removed the data pattern can have parameters specified by param child elements the list pattern has been added for matching whitespace-separated lists of tokens the replace and group values for the combine attribute have been removed an include element in a grammar may contain define elements that replace included definitions the restriction that definitions combined with the combine attribute must be from different files has been removed a div element may be used to group together definitions within a grammar an include element occurring as a pattern has been renamed to externalRef; an include element is now allowed only as a child of the grammar element the parent attribute on the ref element has been replaced by a new parentRef element the type attribute of the data element is an unqualified name; the data element uses the datatypeLibrary attribute rather than the ns attribute to identify the namespace of the datatype a start element is not allowed to have a name attribute an attribute element is not allowed to have a global attribute the not and difference name classes have been replaced by except the data element may have an except child key and keyRef have been removed; support for ID and IDREF is now available in a companion specification, RELAX NG DTD Compatibility Annotations difference and not have been replaced by except a start element is no longer allowed to have a name attribute an attribute element is no longer allowed to have a global attribute RELAX NGJames Clark, Makoto MURATA, editors. RELAX NG Specification. OASIS, 2001. AnnotationJames Clark, Makoto MURATA, editors. RELAX NG DTD Compatibility Annotations. OASIS, 2001. TREXJames Clark. TREX - Tree Regular Expressions for XML. Thai Open Source Software Center, 2001. RELAXMURATA Makoto. RELAX (Regular Language description for XML). INSTAC (Information Technology Research and Standardization Center), 2001.