Prepare your TEI document

The TEI standard allows for multiple ways to encode the same textual features. For example, you can use the tag <persName>, the tag <name>, or even the tag <rs> to markup a personal name (cf. TEI Guidelines, 13. Names, Dates, People, and Places).

This TEI feature has the advantage of flexibility, but it makes creating a universal TEI-to-RDF transformation script a difficult task. This is why this documentation includes a set of encoding guidelines designed to ensure a smooth TEI-to-RDF transformation via LIFT. In particular, in order for LIFT to work on your TEI document, you must adhere to the following simple guidelines:

  1. Provide TEI elements with unique identifiers using @xml:id

  2. Provide an at least minimal TEI header

  3. Use <person> and <persName> to represent persons and in-text references to such persons

  4. Use <place> and <placeName> to represent places and in-text references to such places

  5. Assign a @sameAs attribute to real-world entities

  6. Encode relationships between persons within <listRelation>

  7. Use <event> to represent events, either within <person> or <place>

Provide TEI elements with unique identifiers using @xml:id

A unique URI must be assigned to each entity of a linked data graph (for example, a person, a place, a literary work, etc.). LIFT uses @xml:id attributes to create unique URIs. To accomplish this, LIFT concatenates the value of the attribute @xml:base attribute of the <TEI> element is concatenated with the value of the @xml:id attribute of the element. For example, the element below representing a person

<TEI xmlns="http://www.tei-c.org/ns/1.0" xml:base="https://example.org">
        ...
        <person xml:id="socr">...</person>
        ...
</TEI>

will be assigned the following URI:

<https://example.org/person/socr>

Note that the value of your @xml:base attribute should be registered as a permanent URL (i.e. through services such as w3id.org). Check the W3C Permanent Identifier Community Group for more information on how to register your URL.

If your TEI document lacks unique identifiers, you can use Charlotte Tupman’s this XSLT transformation (written for SAWS project), which generates a unique identifier for each element that has no @xml:id. You can run the transformation using xsltproc after downloading the stylesheet to the same folder as your TEI document. You can look at this tutorial for detailed instructions about the process (last accessed 2021-10-25).

Provide an at least minimal TEI header

Your TEI header should comprise, at least, the minimal recommended elements as shown below:

<teiHeader>
        <fileDesc>
                <titleStmt>
                        <title><!-- Title of the resource --></title>
                        <author><!-- Author of the resource --></author>
                </titleStmt>
                <publicationStmt>
                        <p><!-- Information about the distribution of the resource --></p>
                </publicationStmt>
                <sourceDesc>
                        <p><!-- Information about the source from which the resource derives --></p>
                </sourceDesc>
        </fileDesc>
</teiHeader>

Use <person> and <persName> to represent persons and in-text references to such persons

Each person mentioned in the TEI document must be described in the TEI header within a <person> element to which an @xml:id has been assigned.

It is possible to provide a normalized form of each person’s name by nesting a <persName> element containing the normalized name within <person>. You can provide multiple normalizations, e.g. in different languages (to specify the language use the @xml:lang attribute and a value from the ISO 639 list of language codes).

All in-text occurrences of personal names must be encoded using <persName>. The attribute @ref should be used on the element to relate each name to the corresponding person (via the person’s @xml:id). For example:

<TEI xmlns="http://www.tei-c.org/ns/1.0" xml:base="https://example.org">
        <teiHeader>
                ...
                <person xml:id="socr">
                        <persName xml:lang="en">Socrates</persName>
                        <persName xml:lang="el">Σωκρᾰ́της</persName>
                </person>
                ...
        </teiHeader>
        <text>
                ...
                <persName ref="#socr">Socrates</persName>
                ...
        </text>
</TEI>

Persons can be grouped using <listPerson>. Each <listPerson> (or, alternatively, each <person> element if <listPerson> is not present) can be assigned a @type and/or @corresp containing a short description of the group or individual. In particular, use @type for free-text descriptions (if using multi-word descriptions, please separate each word with an hyphen) or @corresp to provide a URI from a controlled vocabulary. For example:

<listPerson type="ancient-athenian-philosophers" corresp="http://dbpedia.org/class/yago/WikicatAncientAthenianPhilosophers">
        <person xml:id="Socr">
        ...

Use <place> and <placeName> to represent places and in-text references to such places

The guidelines for encoding persons apply to places as well. For example:

<TEI xmlns="http://www.tei-c.org/ns/1.0" xml:base="https://example.org">
        <teiHeader>
        ...
                <place xml:id="athens">
                        <placeName xml:lang="en">Athens</placeName>
                </place>
        ...
        </teiHeader>
        <text>
        ...
                <placeName ref="#athens">Athens</persName>
        ...
        </text>
</TEI>

Assign a @sameAs attribute to real-world entities

By assigning a @sameAs attribute to your entities, you can disambiguate them by connecting them to external authority files, such as VIAF, Worldcat, or the Library of Congress.

Provide a URI in a @sameAs attribute. You can supply multiple URIs, separated by a whitespace. For example:

<person xml:id="Socr" sameAs="http://viaf.org/viaf/88039167 http://id.loc.gov/rwo/agents/n79055329">

Encode relationships between persons within <listRelation>

Use a series of <relation> elements nested within <listRelation> to markup relationships between persons in the TEI header. Note that <listRelation> must be a child element of <listPerson>.

In particular, for unidirectional relationships (e.g. ‘Socrates has student Plato’) use the attributes @active and @passive to express the subject and the object of the relationship respectively; for bidirectional relationships (e.g. ‘Plato has colleague Xenophon’) use the attribute @mutual. It is possible to represent a mutual relationship involving multiple persons by declaring more than one value for the @mutual attribute. Multiple values must be separated by whitespaces. Finally, use the @name attribute to express the nature of the relationship. You can reuse terms from AgRelOn, the Agent Relationship Ontology. For example:

<listRelation>
        <relation xml:id="rel01" name="hasStudent" active="#socr" passive="#plat #xen #criti"/>
        <relation xml:id="rel02" name="hasColleague" mutual="#plat #xen"/>
</listRelation>

Use <event> to represent events, either within <person> or <place>

It is possible to describe events that occur in relation to a specific person or place. Such descriptions should be nested within the corresponding <person> or <place> elements.

The element <event> contains the description of the event. The attributes @type and @corresp can be assigned to <event> to provide a free-text label or a URI, respectively.

The date of the event must be recorded in @when or @from/@to attributes. Dates should be represented according to the ISO 8601 standard.

A <label> can be used to provide a short textual description of the event, while a <desc> can contain the extended account of the event, including personal names, place names, and dates (encoded using the <date> element).

It is possible to specify the role held by the person in the event using the attribute @role and/or using the attribute @corresp on <persName>. The attribute @corresp should only contain a URI representing the role.

Furthermore, if there exist a primary or secondary source about the event, the element <bibl> can be used to express it (either as a child of <desc> or as a direct child of <event>). The <bibl> element may contain information about the <author>, the <title> and the <date> of publication of the source. A @sameAs can be associated to <bibl>.

For example:

<person xml:id="socr" sameAs="http://viaf.org/viaf/88039167">
        ...
        <event xml:id="ev01" type="trial" when="-0399" corresp="http://wordnet-rdf.princeton.edu/id/01198357-n">
                <label>Socrates trial</label>
                <desc xml:id="desc01">The trial of <persName ref="#socr" role="defendant" corresp="http://wordnet-rdf.princeton.edu/id/09781524-n">Socrates</persName> for impiety and corruption of the youth took place in <placeName ref="#athens">Athens</placeName> in <date when="-0399">399 B.C.</date></desc>
                <bibl xml:id="bibl01" sameAs="http://viaf.org/viaf/214045129"><author ref="#plat">Plato</author> gives a contemporary account of the trial in his work titled <title ref="Apology_of_Socr">Apology of Socrates</title>.</bibl>
        </event>
        ...
</person>

Full example

You can download a TEI XML pseudo-edition featuring all of the examples presented above from this link.