1As we have seen, the TEI is designed to support a very wide range of encoding choices. It can be used for a simple reading-oriented transcription of a primary source, whether that be an authorial manuscript, a printed literary work, an audio broadcast, or a dictionary. It can be used for enriched encodings in which many aspects of such texts are made explicit, so that software of all kinds can operate upon them, from visualisation tools and digital publishing systems to specialised statistical analysis packages. It can be used to provide additional annotations and metadata of all kinds. Almost no-one needs everything defined by the TEI, yet every one of its elements is of use or interest to someone. How should you go about choosing just the parts of the TEI you need? One major motivation for creating TEI documents in the first place is the possibility of sharing them with others, and integrating them with other TEI documents. How should you communicate the particular TEI encoding choices you have made to others so that such integration remains possible?

2The TEI provides a way of adressing these concerns, as well as satisfying the important need for detailed project-specific documentation, by providing a set of elements which can be used both to specify a schema in terms of the names and formal properties of the elements and attributes it contains and also to document the way those elements and attributes are used in a given application.

3The notion of a schema is fundamental to XML: it provides a kind of document grammar, naming the possible components and constraining the organization of an XML document. A schema makes it possible to express constraints such as <p> elements may appear within <div> elements or every <list> element must contain at least one <item>. Rules of this kind are easily checked by an automatic processor (a validator). Constraints such as Use the <p> element to contain paragraphs, not pages or use <placeName> for names of places, <persName> for names of people, and <name> for any other name are much less easy to check automatically, since they relate to the semantics of the content rather than its organization. Such rules are defined by documents such as the TEI Guidelines, or by documents referrring to them. Understanding of these semantic constraints is extremely important for those developing software intended to take full advantage of the marked up document, as well as for those wishing to create new documents encoded in the same way. This is particularly true if the schema in use permits a wide variety of elements with very similar meanings, as will be the case for an unmodified and uncustomised TEI schema.

4For this reason, serious use of the TEI requires careful consideration of exactly which of its elements is appropriate to the needs of a project, and also perhaps of things which the project needs to specify more exactly than the TEI does. For example, the TEI makes no binding requirements for the possible values of the attribute @type used on <div> elements, since these are likely to vary greatly across different projects. In a given project, however, it is likely that standardising on an agreed set of values will be very helpful, and there will consequently be a need both to ensure that all documents use only the agreed set of values, and to ensure that documentation about what those values are and what they signify is maintained along with the rest of the schema, and readily available to XML-aware document preparation and editing systems (such as the widely used oXygen program) to help and guide the human document editor.

5The TEI provides a special set of elements which can be used to create such a schema specification. The elements concerned (<schemaSpec>, <moduleRef>, <elementSpec>, <classSpec> and others) combine formal XML declarations for inclusion in a DTD or Schema with detailed documentation and examples, for inclusion in a technical manual about the encoding scheme being specified. For this reason, a document using these elements is informally known as an ODD, for One Document Does it all: it provides information for a computer to process along with documentation of that information for a human being to read in a single integrated XML document. Unsurprisingly, the TEI system itself is expressed using this exact same set of elements, but here we focus on its use in the creation of a TEI customization.

Building a customization

6The simplest TEI customization is the null customization, which simply says permit every element defined by the TEI. The resulting schema, called tei_all, provides (at the time of writing) some 450 different elements, and many, many, different ways of solving often over-lapping encoding problems. The size and permissiveness of this schema alike make it more or less unusable for practical purposes - except for one very important one related to TEI conformance, to which we return below.

7Probably the most widely used and frequently referenced TEI customization is tei_lite, a subset of some fifty elements claiming to satisfy the needs of 90% of TEI users, as evidenced by their actual practice in creating digital texts. This was originally produced for a TEI training workshop back in 1997, but with some updating has continued to be useful in a very wide range of contexts, to the extent that some people think that it is the TEI schema. TEI Lite is included (as an Exemplar) with the standard release of TEI, in source and derived forms.

8A quick glance at the XML source code for the TEI Lite ODD shows that it appears to be a typical TEI document, with <div> elements containing <head>s, <p>s and <list>s, containing much discursive prose, as well as <ptr> elements for cross references and a few other specialised elements such as <egXML> for XML examples. The actual schema specified by this document is represented, towards the end of the document, by a <schemaSpec> element which contains declarations like the following:

<schemaSpec ident="tei_lite" start="TEI teiCorpus">
 <moduleRef key="analysis" include="interp interpGrp pc s w"/>
 <moduleRef key="linking" include="anchor seg"/>
 <moduleRef key="tagdocs" include="att code eg gi ident val"/>
 <moduleRef key="tei"/>
 <moduleRef
   key="textstructure"
   include="TEI argument back body byline closer dateline div docAuthor 
 docDate docEdition docImprint docTitle epigraph front group 
 imprimatur opener postscript salute signed text titlePage 
 titlePart trailer"/>
</schemaSpec>

9The <moduleRef> element is used to reference a TEI module. A module is simply a named container for a number of declarations for TEI elements and classes. The TEI currently defines 22 modules, each one corresponding to a chapter in the TEI Guidelines where its contents are described in detail. By default, a module reference implies that all the declarations it contains are to be transferred to the schema being specified, but the attributes @include and @except can be used to modify this default behaviour. Thus, in the above example the schema being created will include all the declarations found in the module called tei, but declarations only for elements <anchor> and <seg> from the module called linking. Alternatively, the attribute @except might have been used to select everything from this module except for the elements named as its value.

10A module makes available to the <schemaSpec> a declaration for each element selected, in the form of an <elementSpec> element. This has several components, most of which are visualised in the TEI reference documentation. It includes, for example:

• one or more <desc> elements to provide a short description of the function of the element, possibly in different languages;
• a <classes> element containing a <memberOf> element for each class of which the element is a member;
• an <attList> element, containing a structured list of all the attributes locally defined for the element, together with information about their datatype and any predefined set of values, expressed by means of the elements <attDef>, <valList> and <valItem> respectively;
• a <content> element providing a formal declaration of the legal content of the element, and optionally <constraint> elements used to express any additional usage constraints;
• one or more <exemplum> elements, each containing an examples of usage, as far as possible taken from real documents, plus commentary.

11 Appendix C of the TEI Guidelines provides nicely-formatted documentation for every defined TEI element on the basis of such declarations.

12As well as selecting or excluding declarations, a <schemaSpec> can modify some parts of a declaration. A little later in the ODD for TEI Lite, we find the following:

<elementSpec ident="TEI" mode="change">
 <attList>
  <attDef ident="version" mode="delete"/>
 </attList>
</elementSpec>

the effect of which is to provide a second declaration for the element <TEI>, along with that selected from the textstructure module. An ODD processor must reconcile or unify such duplications, under control of the attribute @mode . In this particular case, the effect is to change the <attList> declared for the <TEI> element by deleting the attribute @ident from it.

13Exactly the same procedure is used in the remainder of the TEI Lite customization to remove from it some other unwanted attributes. For example, the attributes @notBefore, @notAfter, and others are provided by the attribute class att.datable.w3c. The easiest way of removing them is therefore to provide an additional declaration for the class as follows:

<classSpec
  type="atts"
  ident="att.datable.w3c"
  module="tei"
  mode="change">
 <attList>
  <attDef ident="notBefore" mode="delete"/>
  <attDef ident="notAfter" mode="delete"/>
  <attDef ident="from" mode="delete"/>
  <attDef ident="to" mode="delete"/>
 </attList>
</classSpec>

14An ODD specification can include or exclude elements and attributes in these and other ways. It can also modify an existing declaration by adding additional constraints to it. For an example, consider the TEI customization known as Epidoc, which is widely-used by epigraphers and others working with inscriptions from the ancient world. As we noted above, the @type attribute on the <div> element is not constrained in any way by the TEI. The Epidoc community however has decided that it wishes to enforce the presence of this attribute and to permit only six predefined values for it. Here is the fragment of the Epidoc ODD which achieves that effect:

<elementSpec
  ident="div"
  mode="change"
  module="textstructure">
 <attList>
  <attDef
    ident="type"
    mode="replace"
    usage="req">
   <valList type="closed">
    <valItem ident="apparatus">
     <desc>to contain apparatus criticus or textual notes</desc>
    </valItem>
    <valItem ident="bibliography">
     <desc>to contain bibliographical information, previous publications,
           etc.</desc>
    </valItem>
    <valItem ident="commentary">
     <desc>to contain all editorial commentary, historical/prosopographical
           discussion, etc.</desc>
    </valItem>
    <valItem ident="edition">
     <desc>to contain the text of the edition itself; may include multiple
           text-parts</desc>
    </valItem>
    <valItem ident="textpart">
     <desc>used to divide a div[type=edition] into multiple parts (fragments,
           columns, faces, etc.)</desc>
    </valItem>
    <valItem ident="translation">
     <desc>to contain a translation of the text into one or more modern
           languages</desc>
    </valItem>
   </valList>
  </attDef>
 </attList>
</elementSpec>

15Note that further constraints could be added to check that these values are correctly used: for example to check that a <div type="textpart"> always has a <div type="edition"> as its parent.

16The Epidoc project shows how a particular research community can adapt the TEI to their own needs, and its customization is a good demonstration of the kinds of things which the ODD language makes possible.

Adding a new element

17The ODD system also makes it possible to add entirely new elements to a schema. At its simplest this involves no more than the addition of a <elementSpec> for the new element to the schema specification, but deciding on the proper content for that new element does require some knowledge of the way the TEI system is designed. Choosing which class memberships should be specified for a new element, for example, is difficult without knowing which classes exist and how they interact. Choosing an appropriate content model for the new element similarly requires some thought about how other elements are defined, assuming that we wish our new element to behave consistently with the rest of the TEI. And finally, because this is a non-TEI element, we must take care to define it in a non-TEI namespace.

18For example, suppose we wish to add a new element <speciesName> to mark up the names of botanical or other species appearing in a text. Our new element is semantically similar to the existing <persName> or <name> elements, so a good starting point will be to look at the ODD specification for other name-like elements. For example, in the <elementSpec> for the element <persName>, we see that it is a member of a model class model.nameLike.agent, which is a subclass of the more general model.nameLike class. Adding our new element to this class will ensure that it will appear in the content models of other TEI elements in the same places as other naming elements, without any further work on our part. We also note that <persName> is a member of several attribute classes, notably @att.global (which has several subclasses of its own) and att.canonical, both of which look useful for our purposes. Adding our new element to these classes will ensure that it uses these attributes in the same way as other name-like elements.

19Next, we consider the content model of our new element. The easiest course of action would be to do the same as the other naming elements, and say that it can contain just text, mixed in with other phrase-level elements, elements such as <g>, and global elements. This is so common a requirement in the TEI scheme that there is a short cut (a “macro”) defined for it called macro.phraseSeq. If however we want to represent the internal content of a <speciesName> (for example to distinguish the “genus name” from the “specific name” component), we might want to define a more specific content model, possibly involving other new elements or other constraints. Whichever course of action we take will be explicitly documented in our ODD, so that other users of our data can see how we have customized the basic TEI framework.

Customization and Conformance

20The TEI must reflect the diversity of practice within its user community if it is to continue to be useful. It is sometimes said that asking two academics the same question will always provide you with at least three different answers to it, and so it should be unsurprising to find considerable diversity in the TEI’s recommendations.

21Nevertheless, one of the purposes of the TEI Guidelines is to guide encoding practice. It is not a standard which tells you what to do (in the way that engineering standards, for example, specify exactly the shape and dimensions of electrical fittings); instead it tells you how to communicate what you have done to others. This is why, in the section of the Guidelines defining TEI conformance, one of the essential characteristics specified is the existence of an ODD, defining a schema which may be used to validate the documents in question, along with other possible constraints. Other essential criteria for TEI conformance include formal validity with respect to the schema tei_all, and respect for the defined semantics of the TEI elements used. A conformant TEI document may contain elements from many namespaces, but any elements from the TEI namespace must have the semantics defined for them by the TEI.

22Consider for example the redoubtable English nineteenth century novelist Bulwer-Lytton. In one corpus of TEI documents we might hope to find his full name tagged, and associated with a definition of the person himself, as follows:

<persName
  ref="http://en.wikipedia.org/wiki/Edward_Bulwer-Lytton,_1st_Baron_Lytton">
 <forename>Edward</forename>
 <forename>George</forename>
 <surname type="linked">Bulwer-Lytton</surname>, <roleName>Baron Lytton of <placeName>Knebworth</placeName>
 </roleName>
</persName>

23But in others we will find versions with less informative markup or using different TEI elements, such as

<p>
 <rs type="name">Baron Lytton of Knebworth</rs>
</p>

or

<p>
 <name type="person" key="BWLY">The Right Honourable the Lord Lytton PC</name>
</p>

or

<p>
 <persName ref="#BWLY">First Baron Lytton of Knebworth</persName>
</p>

24Such variations are only to be expected: projects vary considerably in their priorities. For some, it is enough just to show that a string of words is a name; for others, it is important to distinguish names of persons from names of places; for yet others it is essential to disambiguate named entity references, as they are known. The outputs from such projects clearly cannot simply be combined in a straightforwardly interoperable way, without some additional effort. Can they all be considered TEI-conformant?

25An explicit customization, using the features of ODD we have sketched in this section, is the easiest way for a project to communicate its own decisions about how the TEI should be applied, and hence the easiest way to ensure its documents are interchangeable with others. A project can simply suppress (say) the element <rs> from its schema, or specify a closed list of values for its @type attribute. It can choose to use one or other (or both) of the attributes @key and @ref to associate different versions of a person’s name with data about the person intended, and hence disambiguate them. Such choices can be made explicit in a customized schema, and hence tell us which of the many very different approaches to tagging an individual’s name has been adopted in a given set of documents. And because it is also possible to generate an ODD automatically from a set of TEI XML documents, we can also distinguish an intended customization - expressing what the creators of a document intended to be their encoding practice - from an actual customization, expressing the encoding practices actually found.

26If the TEI is designed to be customized, how can it also claim to be an interchange format? For “blind interchange” (also known as “interoperability”), the recipient of a document must be confident that it will contain only TEI elements, and that those elements have been used according to the rules defined by the TEI. Unmodified, those rules permit so much variation that it is all but impossible for a developer to anticipate every possibility that their software must be able to handle. The availability of an ODD greatly simplifies this task, both by limiting the elements available, and by optionally adding to the constraints they represent on data content.