Monthly Archives: March 2019

ODD topics – Defining schematron constraints in ODD

Like any XML language, the TEI can be parsed with Schematron. Moreover, ODD supports natively the specification of Schematron rules,  and the TEI specification itself (for instance here: https://github.com/TEIC/TEI/blob/dev/P5/Source/Specs/att.datable.w3c.xml ) contains embedded schematron rules.

NB: This post doesn’t aim to explain how the Schematron language works. To learn more about Schematron, see W. Piez and D. Lapeyre, Introduction to Schematron, Mulberry Technologies, Inc, Nov. 2008. However, to minimally understand the following, you should know that Schematron, an ISO specification, is an XML language, based on the extensive use of XPath, that makes assertions or reports on the presence or absence of specific patterns in XML documents.

Schematron rules can be used to provide warnings without causing validation errors (i.e. “non-fatal errors”), or to add more qualitative rules to specific elements. For instance, one may want to set a character number limit for the content of a specific tag, or check the value of an attribute by means of a regular expression.

ODD makes it convenient to specify such rules at the same level of the element specification, in an element <constraintSpec>, possibly present in <attDef>, <classSpec>, <elementSpec>, or <schemaSpec> (see the TEI guidelines for more details). Inside <constraintSpec>, the <constraint> element contains assertions in the Schematron language, as shown in the following example:

<elementSpec ident="TEI" mode="change">
   <constraintSpec ident="xmlid" scheme="schematron" type="SSK">
      <constraint>
         <sch:rule context="tei:TEI">
            <sch:let name="fileName" value="tokenize(document-uri(/), '/')[last()]"/>
            <sch:assert test="string(@xml:id)=substring-before($fileName, '.xml')" role="error">
The xml:id of the TEI element should be equal to the name of the file,
without the file extension. Currently the value of xml:id is "<sch:value-of select="@xml:id"/>" 
whilst the file name is "<sch:value-of select="$fileName"/>"</sch:assert>
         </sch:rule>
      </constraint>
   </constraintSpec>
</elementSpec>

Two important caveats (thanks to Syd Bauman’s XPath and Schematron for TEI Customization, https://www.wwp.northeastern.edu/outreach/seminars/_current/presentations/schematron/schematron_odd.xml):

  1. the element <sch:rule> is not mandatory. When missing (i.e., just bare sch:assert and sch:report elements), the context of the Schematron rule is the element or attribute that is being defined (<elementSpec> or <attDef>).
  2. In <constraintSpec>, you need to specify the tei: prefix for TEI elements (see example below).

When a RELAX NG schema is generated from the ODD, the schematron rule will be embedded in the schema:

<define name="tei_TEI">
   <element name="TEI">
   ... 
      <pattern xmlns="http://purl.oclc.org/dsdl/schematron"
               id="myTEI-TEI-xmlid-constraint-rule-10">
         <sch:rule xmlns="http://www.tei-c.org/ns/1.0"
                   xmlns:sch="http://purl.oclc.org/dsdl/schematron"
                   context="tei:TEI">
            <sch:let name="fileName" value="tokenize(document-uri(/), '/')[last()]"/>
            <sch:assert test="string(@xml:id) = substring-before($fileName, '.xml')" role="error">
The xml:id of the TEI element should be equal to the name of the file, 
without the file extension. Currently the value of xml:id is "<sch:value-of select="@xml:id"/>" 
whilst the file name is "<sch:value-of select="$fileName"/>"</sch:assert>
         </sch:rule>
      </pattern>
   ...
   </element>
</define>

This embedded Schematron rule is checked in addition to the RELAX NG when performing file validation, as shown in the following images:

See the full ODD example under:https://github.com/laurentromary/ODDtopics/blob/master/ODD%20examples/schematronODD.xml

ODD topics – The Encoded Archival Description (EAD) 2002 ODD specification and the EHRI use case

Maintaining an XML specification with ODD can be useful outside the TEI realm. First, an ODD specification allows for a smoother maintenance and evolution of an XML vocabulary, but it is also a great help to document project-specific customizations and practices.

A recent and fully documented use case is the EAD specification and and its customization for the EHRI project. This use case has been described in two publications : Romary, L. & Riondet, C. Arch Sci (2018) 18: 165. https://doi.org/10.1007/s10502-018-9290-y, and Romary, L. & Riondet, C. Umanistica Digitale (2019) 4: Data Sharing, Holocaust Documentation and the Digital Humanities: Best Practices, Case Studies and Benefits. https://doi.org/10.6092/issn.2532-8816/9046

This work has shown the efficiency that can be gained by the use of ODD specifications for low-constrained vocabularies.

The official EAD schema and the official EAD tag library were encoded as an ODD document (with the agreement of the Library of Congress and the Society of American Archivists), in the context of the Parthenos project. This EAD ODD is a starting point for EHRI, and was used to create an EHRI-specific EAD profile with very precise content-oriented rules, based on EHRI requirements and on the data models of the collection holding institution. ODD also allows for the creation of qualitative documentation to be served to the user of conversion and validation services provided by the EHRI project.

EHRI EAD validation process

In EHRI, the EAD specification in ODD inherits everything from the generic EAD ODD except when a more specific behaviour is required by the project. However, the philosophy is to keep the EAD schema as it is. Instead, we use another validation language: ISO Schematron, an  ISO/IEC Standard (ISO/IEC 19757-3:2016) that parses XML documents and makes “assertions about the presence or absence of patterns”. It can be used in conjunction with a large number of grammar languages such as DTD, RELAX NG, etc.

ODD topics – adapting the TEI documentation with one’s own examples

Once the decision has been taken to build up an ODD schema that documents the usages of the TEI guidelines within a given digital humanities project, a first step towards customising the guidelines can be to adapt the documentation to reflect the specific practices of the project. A good way to do so is to work specifically on the examples associated to element description, which can easily be changed in the ODD specification.

Let us imagine we create a simple specification for a dictionary project, thus integrating the modules: core, tei, header, textstructure and dictionaries. We can add a specification that changes the element <entry> as follows:

<elementSpec ident="entry" mode="change">
   <exemplum>
      <egXML xmlns="http://www.tei-c.org/ns/Examples">
               <entry xml:it="e-chat" xml:lang="fr">
                  <form>
                     <orth>chat</orth>
                  </form>
                  <gramGrp>
                     <pos>n</pos>
                  </gramGrp>
              </entry>
        </egXML>
     </exemplum>
</elementSpec>

What we have done here is basically two-fold:

  • Mark that we change the specification of the element by means of the @mode attribute set to “change” on the <elementSpec> element;
  • Introduce an <exemplum> element with the example we want to record for this element.

When compiled to create an XHTML output, all pre-existing examples for from the TEI guidelines are replaced by the one(s), that have been introduced that way (see screenshot below).

See the full ODD example under:

https://github.com/laurentromary/ODDtopics/blob/master/ODD%20examples/changeExample.xml