By Syd Bauman

This blog post describes the history behind and recent release of the “tei_customization” schema available in the oXygen TEI framework. 

As many readers of this blog already know, the Text Encoding Initiative schema is designed to be customized by its users. The customization process enables individual projects or user communities to alter the TEI’s constraints and make them more restrictive, more permissive, or just plain different. While the strategic value of such customization is a subject of ongoing debate within the TEI (see for instance Bauman Interchange vs. Interoperability), customization itself is central to the TEI data model.

A TEI customization is expressed using a customization specification, or an “ODD file” (One Document Does-it-all), which represents all of the design choices being made in the customization: the TEI modules to be included, the specific elements to be included or excluded, changes to allowable attribute values, and so forth. This information is then used as a kind of blueprint from which a TEI schema can be generated, using a tool like the TEI’s Roma schema generator. The ODD file is actually written in TEI, using a specialized module that contains elements for things like “include this module” (<moduleRef>) or “here’s a list of attributes” (<attList>). 

In 2006, the Women Writers Project began teaching workshops and seminars on scholarly text encoding, and in 2010, we decided it was time to include a seminar on TEI customization in the series. When we started planning the workshop curriculum, one challenge we flagged right away was the question of how to help participants focus on the main concepts of schema design, rather than the tiny practical pitfalls in the TEI ODD language. In principle, writing an ODD is straightforward, but in practice, there are numerous details that can be tricky to remember and that aren’t directly constrained by the normal TEI schema. We decided to create a customized TEI schema that would provide extra constraints and guidance for people writing TEI schema customizations. If you’re thinking “that seems like a challengingly recursive process,” you’re in good company. We have developed a slide to show how all the pieces fit together.

Thus what this schema does is limit the available constructs to those that make sense in a customization. Some examples:

• • The @key attribute of the aforementioned <moduleRef> element is limited to one of the formal names of an existing TEI module. This means when you add a <moduleRef> to your customization file, you don’t have to go look up whether it is spelled “namesanddates” or “namesDates” or “names_and_dates”, you just select “namesdates” from the pop-up list your editor provides.
  • The @ident attribute of the <elementSpec> element is limited to one of the 575 or so formal names of existing TEI elements. On the plus side, this means when you add an <elementSpec> to your customization file to modify an existing TEI element (e.g., to change its attributes or add an example), you don’t have to remember whether it is spelled “noteStatement”, “notesStatement”, or “noteStmt”, you just select “notesStmt” from the pop-up list your editor provides. On the minus side, this means that if you want to add a new <static> element (as syntactic sugar for <gap reason="illegible" agent="radio_static">) in your TEI customization, the <elementSpec mode="add"> that defines it will be inappropriately flagged as having an invalid @ident.
  • Deleting <publicationStmt> from your schema is flagged as a warning — the resulting documents will, by definition, be non-TEI-conformant.
  • An <elementSpec> that either adds a new element or replaces an existing one is flagged as an error if it does not have a <content> element.
  • More than one <elementSpec> with the same @ident is not allowed — although the ODD language technically allows this situation, current ODD software chokes on it.
  • If, for instance, you inadvertently try to modify the <stage> element with <elementSpec ident="stage" module="drama"> the error will be flagged. (<stage> is not in the drama module, it is in the core module.)

The first version of this customization was “brown_odds” (in parallel with “tei_odds”), and we used it in the first TEI customization seminar we taught in August 2010. It took some time to settle on the name; “brown_odds” was rejected when SyncroSoft (the makers of the oXygen XML editor) wanted to include the customization in oXygen’s TEI framework. We briefly tried “toctoc” (“TEI ODD Customization for TEI ODD Customizations”), followed by “odd4odds” (“ODD for ODDs”, charming but precious), and finally, the TEI Council named it “tei_customization”, which accurately captures the real function and matches the naming pattern used in TEI Exemplars.

Because details in TEI change, each release of the TEI Guidelines gets its own version of “tei_customization”; these can be found at the links below:

• RELAX NG (compact syntax)
• Schematron (and Schematron constraints expressed in XSLT)

The “tei_customization” schema is available in the oXygen TEI framework. This means that when you get oXygen from the SyncRO Soft website, “tei_customization” (as well as the rest of the TEI Exemplar schemas) is already available. To access it, choose the File > New… menu item and then choose the “TEI for writing TEI customizations” template. (It does not matter whether you choose from the “TEI P5” or “TEI ODD” section, it’s the same template.) But that is the version that was current when that version of oXygen was released, which may be several versions behind the current TEI. To automatically get updated versions of the TEI oXygen framework, follow the helpful instructions prepared by James Cummings.

WARNING: When using the tei_customization RELAX NG schema, DTD compatibility mode must be turned off. In oXygen, this means unchecking the “Check ID/IDREF” box in the “XML / XML Parser / RELAX NG” preferences pane. When using jing on the commandline, it means using the -i switch. If you do not turn DTD compatibility mode off, you will get several copies of pretty much the same (useless) error message that starts “conflicting ID-types for attribute …”.

To read more about this customization, see “A TEI customization for writing TEI customizations” by Syd Bauman.