<oo>→<dh> Digital humanities

Pattern: the repeatable or group in mixed content

This structure allows any of the specified elements to appear zero or more times in any combination and in any order, with plain text optionally before, between, or after the element.

• body = element body { mixed { ( country | location | continent )* } }

The following alternatives are correct Relax NG. We prefer the one above because the use of the mixed keyword makes it easy to see that mixed content is involved, but we should also accept:

• body = element body { ( country | location | continent | text )* }

• body = element body { mixed { country* & location* & continent* } }

Anti-pattern: nested repetition indicators

The bad example below works, but the question marks serve no purpose, since the corrected version after it has the same meaning and is easier to read and to debug.

• p = element p {mixed { (quote? | loc? | q? | pr? | slavojism?)* }

• p = element p {mixed { (quote | loc | q | pr | slavojism)* }

Anti-pattern: repetition indicators on attributes

Attributes are not repeatable on their element (this is a well-formedness constraint), which means that they should never have * or + repetition indicators in a schema. Relax NG will—sloppily—let you write those repetition indicators, but that won’t make the attributes repeatable, since you cannot override a well-formedness constraint. Because the attributes are not repeatable, misrepresenting the structure as if they were is bad practice.

The bad example below might represent an attempt to allow for simultaneous speech by multiple speakers:

speech = element speech { speaker+, content }
speaker = attribute speaker { text }

The following XML, though, is not well formed:

<speech speaker="hamlet" speaker="ophelia">Hi, Polonius!</speech>

Fix this by removing the plus sign and listing the speakers in the attribute value, along the lines of:

<speech speaker="hamlet ophelia">Hi, Polonius!</speech>

Anti-pattern: repetition indicators on text

The reserved word text means zero or more textual characters. This has two perhaps surprising consequences:

• The absence of text satisfies the requirement for text in a schema! For this reason, text should never use the ? or * repetition indicators, since that would mean that it was optional, and as long no text counts as text, it doesn’t make sense to try to distinguish text has been omitted from text is present, in the form of zero textual characters.
• Text is not repeatable because if you have some textual characters followed immediately by more textual characters, you have one long instance of text, rather than two instances. This means that text should never be followed by + or * (again), since repetition is meaningless when something cannot be repeated.

The keyword text, then, should never be followed by a repetition indicator.

Pattern: named values

If multiple elements have the same content, you can define a pattern as equal to that content and then use the pattern when you define the elements that contain it.

The bad block below is not invalid Relax NG, but it is bad because it is unnecessarily repetitive, and writing the same code more than once (in this case the same content model three times) creates an opportunity for inconsistency. The version below that is an improvement because it starts by defining the keyword stuff as representing a pattern that can then be used in content models. Note that the first line does not define an element or an attributes (those keywords are missing), so what it means is that you can use the label you’ve just defined, stuff, in a content model wherever you might otherwise have written its expansion. The next three lines then use that label in the content models. These two code blocks have the same meaning, but the second one is better because it avoids the repetition.

• beginning = element beginning { mixed { ( poet | exaggeration | stars )* }
  middle = element middle {mixed { ( poet | exaggeration | stars )* }
  ending = element ending { mixed { ( poet | exaggeration | stars )* }

• stuff = mixed { ( poet | exaggeration | stars )* }
  beginning = element beginning {stuff}
  middle = element middle {stuff}
  ending = element ending {stuff}

Pattern: where to declare attributes in Relax NG

• Attributes are not logically ordered in XML
• Attributes are not repeatable on an element
• Relax NG is permissive about where we write attributes in content models, but we recommend writing them before the actual content. That’s for the convenience of the human; since they go inside the start-tag in XML, putting them first in the Relax NG replicates that order, even though Relax NG itself wouldn’t care if we put them elsewhere. In the rule for <digit> elements in the example below, we specify the attributes first:

  <digit type="money" unit="dollar">99999999</digit>
  digit = element digit {type, unit, xsd:decimal}
  type = attribute type {text}
  unit = attribute unit {text}

Anti-pattern: not ensuring that @xml:id values are unique

The XML below has an error: the value time is assigned to the @xml:id attribute for two different elements. If in your schema you define @xml:id as being of type xsd:ID (and you should), all @xml:id values in the entire document must be unique.

<types>
    <type xml:id="money"/>
    <type xml:id="time"/>
    <type xml:id="weight"/>
    <type xml:id="percent"/>
    <type xml:id="sport"/>
    <type xml:id="animal"/>
    <type xml:id="misc"/>
</types>
<units>
    <unit xml:id="dollar" n="1"/>
    <unit xml:id="mDollar" n="1000000"/>
    <unit xml:id="time" hr="1"/>
    <unit xml:id="dTime" hr="24"/>
    <unit xml:id="yTime" yr="1"/>
</units>

Pattern: reusing element and attribute names

• You can use the same names for elements and attributes with different definitions as long as you use different labels for them in your Relax NG. In the example below, a <person> element that is a child of <persons> has different attributes than a <person> element inside a <p>.

  <persons>
      <person role="filmmaker" surname="Lynch" forename="David" xml:id="lynch"/>
      <-- more persons -->
  </persons>
  
  <!-- more XML content -->
  
  <answer>Yes, I like <person ref="lynch">David Lynch</person>.</answer>

  In the Relax NG below, we use two different labels to define elements of type <person>, each with a different content model. They have the same element name, but we use different labels for them (person_list and p_person).

  persons = element persons {person_list +}          
  person_list = element person {role, surname, forename, id}
  surname = attribute surname {text}
  forename = attribute forename {text}
  id = attribute xml:id {xsd:ID}
  answer = element answer {mixed { p_person* } }
  p_person = element person {ref, text}
  ref = attribute ref {xsd:IDREF}