Skip to main content

Document Metadata Model

There are two separate, but related schemas for the LAUDATIO metadata: the first concerns the TEI-based metadata that are used as input from data providers. The second are JSON-based metadata that result from the TEI metadata being ingested into Elasticsearch. This set of metadata provides the attributes that are directly displayed in LAUDATIO.

The following tabs thus describe both sets of metadata and provide their validation sources (.rng in case of TEI metadata and .json in case of JSON). A separate sub-page contains some TEI file examples.

Preliminaries​

To better differentiate TEI tags, tag attributes, and attribute values, we display them like this:

  • tag
  • attribute
  • "value"

By default, all tags and attributes are required unless otherwise noted. We distinguish the following special cases:

  • ‼️: optional according to RNG schema, but required (or at least highly recommended) for LAUDATIO data ingestion
  • 0️⃣: optional and can be dropped
  • 🔂: its presence is dependent on another element, even if they are in theory independently optional (e.g. if forename is given, surname should also be given)

Basic structure​

tip

If you want to declare more than one genre for a document, we currently recommend separating them with commas, e.g. style="Prosa, Poesie".

The teiHeader contains two attributes and four main tags. Of the four main tags, all are required for LAUDATIO, but only one is required by the RNG schema:

  • type must be "DocumentHeader".
  • ‼️ style is used to declare the document genre.1
  • fileDesc (file description) provides description of a document, such as its title, author, publisher, etc.
  • ‼️ profileDesc (text-profile description) Provides a detailed description of non-bibliographic aspects of a text, specifically the languages and sublanguages used, the situation in which it was produced, the participants and their setting.
  • ‼️ encodingDesc (encoding description) documents the relationship between an electronic text and the source or sources from which it was derived.
  • ‼️ revisionDesc (revision description) summarizes the revision history for a file.

The basic structure of the document TEI header is thus as follows:

<?xml version='1.0' encoding='utf-8'?>
<?xml-model href="./document.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<TEI xmlns="http://www.tei-c.org/ns/1.0">
    <teiHeader style="GENRE" type="DocumentHeader">
        <fileDesc>...</fileDesc>
        <profileDesc>...</profileDesc>
        <encodingDesc>...</encodingDesc>
        <revisionDesc>...</revisionDesc>
    </teiHeader>
    <text/>
</TEI>

The four main tags are described in detail below.



fileDesc​

Tips
  1. Best practice: Use the file name as the the ‼️ xml:id (e.g. if the file is document1.xml, ‼️ xml:id should be "document1").
  2. If you want to make the document plaintext accessible in LAUDATIO as well, you MUST use the same file name (without extension) for both the underlying document and the document header. For example, let's say your actual corpus contains text files (extension: .txt). For a document, we recommend naming the text file and the document header file containing the metadata like this: document1.txt and document1.xml.

The fileDesc contains the following tags where the basic meaning is left untouched, but they simply reference the concept Document. For example, the tag author refers to the author of the document and the tag title refers to the title of a single document. The attributes and tags used within fileDesc are:

  • ‼️ xml:id is the document identifier. Use this in the corresp attribute in the corpus sourceDesc.
  • titleStmt (title statement) groups information about the title of a work and those responsible for its content.
  • ‼️ extent describes the approximate size of a text stored on some carrier medium or of some other object, digital or non-digital, specified in any convenient units.
  • publicationStmt (publication statement) groups information concerning the publication or distribution of an electronic or other text.
  • 0️⃣ seriesStmt (series statement) groups information concerning the publication series of an electronic or other text.
  • sourceDesc (source description) describes the source from which an electronic text was derived or generated, typically a bibliographic description in the case of a digitized text, or a phrase such as "born digital" for a text which has no previous existence.

The basic structure of fileDesc is thus as follows:

<fileDesc xml:id="document1">
    <titleStmt>
        <title>...</title>
        <editor>...</editor>
        <author>...</author>
        <respStmt>...</respStmt>
    </titleStmt>
    <extent>...</extent>
    <publicationStmt>
        <publisher>...</publisher>
        <pubPlace>...</pubPlace>
        <idno>...</idno>
        <date>...</date>
        <biblScope>...</biblScope>
    </publicationStmt>
    <seriesStmt>
        <title>...</title>
        <editor>...</editor>
        <biblScope>...</biblScope>
    </seriesStmt>
    <sourceDesc>...</sourceDesc>
</fileDesc>

titleStmt​

tip

If the original author of a document is not known, we advise you to still add the author tag, but simply fill both forename and surname with "NA".

The titleStmt contains the title, editors, and authors of the document.

  • title contains the document title
  • ‼️ author denotes the (original) document author(s)
    • ‼️ persName (personal name) contains a proper noun or proper-noun phrase referring to a person, possibly including one or more of the person's forenames, surnames, honorifics, added names, etc.
      • 🔂 key is used to refer to an external authority file. Possible values are "orcid" and "gnd". If present, ref should be present as well. Note that this information is currently not ingested and shown in LAUDATIO.
      • 🔂 ref contains the URI to the external authority file entry. If present, key should be present as well. Note that this information is currently not ingested and shown in LAUDATIO.
      • 🔂 forename contains a forename, given or baptismal name. If present, surname should be present as well.
      • 🔂 surname contains a family (inherited) name, as opposed to a given, baptismal, or nick name. If present, forename should be present as well.
  • 0️⃣ editor denotes the editors of the document edition you used.
    • 0️⃣ persName (personal name) contains a proper noun or proper-noun phrase referring to a person, possibly including one or more of the person's forenames, surnames, honorifics, added names, etc.
      • 🔂 key is used to refer to an external authority file. Possible values are "orcid" and "gnd". If present, ref should be present as well. Note that this information is currently not ingested and shown in LAUDATIO.
      • 🔂 ref contains the URI to the external authority file entry. If present, key should be present as well. Note that this information is currently not ingested and shown in LAUDATIO.
      • 🔂 forename contains a forename, given or baptismal name. If present, surname should be present as well.
      • 🔂 surname contains a family (inherited) name, as opposed to a given, baptismal, or nick name. If present, forename should be present as well.
  • 0️⃣ respStmt (responsibility statement) specifies other kinds of corpus responsibilities, e.g. those responsible for the metadata schema. Note that this information is currently not ingested and shown in LAUDATIO.
    • resp describes what the responsiblity entails (e.g. metadata)
    • 0️⃣ persName (personal name) contains a proper noun or proper-noun phrase referring to a person, possibly including one or more of the person's forenames, surnames, honorifics, added names, etc.
      • 🔂 key is used to refer to an external authority file. Possible values are "orcid" and "gnd". If present, ref should be present as well. Note that this information is currently not ingested and shown in LAUDATIO.
      • 🔂 ref contains the URI to the external authority file entry. If present, key should be present as well. Note that this information is currently not ingested and shown in LAUDATIO.
      • 0️⃣ forename contains a forename, given or baptismal name.
      • 0️⃣ surname contains a family (inherited) name, as opposed to a given, baptismal, or nick name.
      • 0️⃣ orgName (organization name) contains the name of the organization a person is affiliated with

An example of the titleStmt looks like this:

<titleStmt>
    <title>The great story of the plants</title>
    <author>
        <persName key="gnd" ref="http...">
            <forename>Max</forename>
            <surname>Mustermann</surname>
        </persName>
    </author>
    <editor>
        <persName>
            <forename>Sabine</forename>
            <surname>Schulz</surname>
        </persName>
    </editor>
    <respStmt>
        <resp>Metadata</resp>
        <persName>
            <forename>Jane</forename>
            <surname>Doe</surname>
        </persName>
        <orgName type="Department">Department of Linguistics</orgName>
        <orgName type="Institution">XYZ</orgName>
    </respStmt>
</titleStmt>

extent​

The ‼️ extent provides information about the size of the document. The attribute type defines the counting unit, which can be "Tokens" or "Words".

  • extent describes the approximate size of a text stored on some carrier medium or of some other object, digital or non-digital, specified in any convenient units.
    • type Characterizes the element in some sense, using any convenient classification scheme or typology. Possible values are "Tokens" or "Words".

An example for this tag is:

<extent type="Tokens">1234</extent>

publicationStmt​

The publicationStmt refers to bibliographic metadata, usually a printed publication, either an edition or the first publication. If this exemplar contains a historical source, provide metadata for this source in sourceDesc.

  • publisher provides the name of the organization responsible for the publication or distribution of a bibliographic item.
  • 0️⃣ pubPlace (publication place) contains the name of the place where a bibliographic item was published.
  • 0️⃣ idno (identifier) supplies any form of identifier used to identify some object, such as a bibliographic item, a person, a title, an organization, etc. in a standardized way. This is not ingested/shown in LAUDATIO.
  • 0️⃣ date contains a date in any format. If this tag is not provided, LAUDATIO will show "YY".
    • when supplies the value of the date or time in a standard form, e.g. yyyy or yyyy-mm-dd. Note that what gets shown in LAUDATIO is this, NOT what the text of date contains.
  • 0️⃣ biblScope (scope of bibliographic reference) defines the scope of a bibliographic reference, for example as a list of page numbers, or a named subdivision of a larger work.

A simple publicationStmt looks like this:

<publicationStmt>
    <publisher>ABC Druck</publisher>
    <pubPlace>Berlin</pubPlace>
    <idno></idno>
    <date when="1674">1674</date>
    <biblScope>pp.1-80</biblScope>
</publicationStmt>

seriesStmt​

A publication may be published within a series. 0️⃣ seriesStmt provides information about the publication series of the publication of the document:

  • title contains a title for any kind of work.
  • 0️⃣ editor contains the editor of the series as a free text.
  • 0️⃣ biblScope (scope of bibliographic reference) defines the scope of a bibliographic reference, for example as a list of page numbers, or a named subdivision of a larger work.
    • 0️⃣ unit identifies the type of information conveyed by the element, e.g. columns, pages, volume. We default to treating the text of biblScope as the volume information, so unit is ignored.

An example for a seriesStmt is given here:

<seriesStmt>
    <title>Zeitschrift für Pflanzen</title>
    <editor>Königliche Akademie der Wissenschaften. Historische Komission, München</editor>
    <biblScope unit="vol">2</biblScope>
</seriesStmt>

sourceDesc​

tip

If a historical original is not applicable or known, you still need to provide this tag! However, you can leave it blank like this:

<sourceDesc>
    <msDesc>
        <msIdentifier>
            <msName>NA</msName>
        </msIdentifier>
    </msDesc>
</sourceDesc>

sourceDesc provides metadata of the historical original, if applicable and known.

The elements it includes are:

  • 0️⃣ n (number) gives a number (or other label) for an element, which is not necessarily unique within the document. This is simply an incrementing document counter.
  • ‼️ msDesc (manuscript description) contains a description of a single identifiable manuscript or other text-bearing object.
    • msIdentifier (manuscript identifier)
      • ‼️ msName (manuscript name) contains any form of unstructured name used for a manuscript. This gets shown as "Classification" under "Source Description" in LAUDATIO.
      • 0️⃣ altIdentifier contains any form of unstructured alternative name used for a manuscript, such as an ‘ocellus nominum’, or nickname. This is not ingested/shown in LAUDATIO.
        • 0️⃣ repository contains the name of a repository within which manuscripts are stored, possibly forming part of an institution.
        • 0️⃣ collection contains the name of a collection of manuscripts, not necessarily located within a single repository.
        • idno is an identifier.
    • 0️⃣ history groups elements describing the full history of a manuscript or manuscript part.
      • 0️⃣ origin contains any descriptive or other information concerning the origin of a manuscript or manuscript part.
        • 0️⃣ objectType contains a word or phrase describing the type of object being referred to.
        • 0️⃣ origDate (origin date) contains any form of date, used to identify the date of origin for a manuscript or manuscript part. Note that we use two custom attributes here:
          • 0️⃣ notBefore-custom indicates that the manuscript was not created before this date (lower bound of date range). This is given in the format yyyy.
          • 0️⃣ notAfter-custom indicates that the manuscript was not created after this date (upper bound of date range). This is given in the format yyyy.
          • 0️⃣ precision indicated how certain the date information is. Possible values are: "high", "medium", "low", "unknown"
        • 0️⃣ origPlace (origin place) contains any form of place name, used to identify the place of origin for a manuscript or manuscript part.
        • 0️⃣ title contains a title for any kind of work.
        • 0️⃣ locus defines a location within a manuscript or manuscript part, usually as a (possibly discontinuous) sequence of folio references.
  • 0️⃣ recordHist (recorded history) provides information about the source and revision status of the parent manuscript description itself. This is not ingested/shown in LAUDATIO.
    • source
      • facs (facsimile)
      • 0️⃣ ref (reference) defines a reference to another location, possibly modified by additional text or comment.
        • 0️⃣ target specifies the destination of the reference by supplying one or more URI References

msDesc shall only give a short overview over the publication history of each document of the corpus in order to use the view and search functions of LAUDATIO. Thus, recordHist is used to provide references to resources where much more detailed information about the manuscript history is given.

An example for this tag looks like this:

<sourceDesc n="1">
    <msDesc>
        <msIdentifier>
            <msName>Base manuscript for the transcription (A). Continuation (1434-1441) and some
              Additions come from ms. a: Nürnberg, Stadtbibliothek, Cod. Amb. 237.4°</msName>
            <altIdentifier>
                <repository>Nürnberg. Staatsarchiv</repository>
                <collection>Rep. 52a (Reichsstadt Nürnberg)</collection>
                <idno>Hs. Nr. 14</idno>
            </altIdentifier>
        </msIdentifier>
        <history>
            <origin>
                <objectType>Chronicle of the history of the city of Nuremberg (Franconia) from 1126 to
                    1434, with an extension until 1441. It provides detailed information about imperial
                    history and city history, particularly from around 1420 onwards. The work underwent
                    multiple revisions and was used by later Nuremberg chroniclers.</objectType>
                <origDate notAfter-custom="1441" notBefore-custom="1400" precision="medium">The text
                    was certainly written around 1434 with extension until 1441</origDate>
                <origPlace>Nuremberg</origPlace>
                <title>Chronik aus Kaiser Sigmund's Zeit</title>
                <locus />
            </origin>
        </history>
    </msDesc>
    <recordHist>
        <source facs="urn:nbn:de:bvb:12-bsb10798054-4">
        <ref target="https://www.digitale-sammlungen.de/en/view/bsb10798054">
            Bayerische Staatsbibliothek digital
        </ref>
        </source>
    </recordHist>
</sourceDesc>


profileDesc​

Important

Include at most three language tags and make sure to use each style only once!

The ‼️ profileDesc only contains metadata concerning the language of the document including remarks on language type and lanuage area.

  • langUsage (language usage) describes the languages, sub-languages, registers, dialects, etc. represented within a text.
    • language characterizes a single language or sublanguage used within a text.
      • style contains an expression in some formal style definition language which defines the rendering or presentation used for this element in the source text; possible values: "Language", "LanguageType", "LanguageArea"
      • ident (identifier) supplies a language code constructed as defined in BCP 47 which is used to identify the language documented by this element, and which is referenced by the global xml:lang attribute.2

A concrete example of profileDesc would be:

<profileDesc>
    <langUsage>
        <language ident="de" style="Language">Early New High German</language>
        <language ident="de" style="LanguageArea">Southern dialects</language>
        <language ident="de" style="LanguageType">Bavarian</language>
    </langUsage>
</profileDesc>


encodingDesc​

info

Note that encodingDesc contains one schemaSpec tag, but schemaSpec can contain multiple elementSpec tags!

The ‼️ encodingDesc contains a list of annotation keys sorted by rough linguistic categories:

  • schemaSpec (schema specification) generates a TEI-conformant schema and documentation for the annotations.
    • ident supplies the identifier by which this element may be referenced. Possible value: "AnnotationKey"
    • ‼️ elementSpec (element specification) documents the structure, content, and purpose of a single element type. This basically denotes a group of annotations of the same categroy (e.g. "MarkUp").
      • ident supplies the identifier by which this element may be referenced. Corresponds to the annotation layer classification used in tagsDecl tag of encodingDesc of the corpus metadata:
        • "Transcription"
        • "Lexical"
        • "Morphological"
        • "Syntactic"
        • "Graphical"
        • "MarkUp"
        • "Meta"
        • "Other"
      • ‼️ valList (value list) contains one or more valItem elements defining possible values. Here, all annotation layers of the specified annotation category are listed.
        • ‼️ valItem documents a single value in a predefined list of values.
          • corresp ID of the annotation layer as given in corresp of the annotation metadata model (should also correspond to file name)
          • ident free identifier.3

An example is thus:

<encodingDesc>
    <schemaSpec ident="AnnotationKey">
        <elementSpec ident="Transcription">
            <valList>
                <valItem corresp="clean" ident="clean"/>
                <valItem corresp="dipl" ident="dipl"/>
                <valItem corresp="norm" ident="norm"/>
            </valList>
        </elementSpec>
        <elementSpec ident="Lexical">
            <valList>
                <valItem corresp="lemma" ident="lemma"/>
                <valItem corresp="pos" ident="pos"/>
            </valList>
        </elementSpec>
        <elementSpec ident="Graphical">
            <valList>
                <valItem corresp="lb" ident="lb"/>
                <valItem corresp="head" ident="head"/>
            </valList>
        </elementSpec>
        <elementSpec ident="Syntactic">
            <valList>
                <valItem corresp="attr_gen" ident="attr_gen"/>
                <valItem corresp="morph_ellipsis" ident="morph_ellipsis"/>
                <valItem corresp="gram" ident="gram"/>
            </valList>
        </elementSpec>
    </schemaSpec>
</encodingDesc>


revisionDesc​

‼️ revisionDesc refers to the version history of the whole corpus. Corpora in LAUDATIO may have several versions. The changes between these versions will be provided here with the focus on the singular document.

  • ‼️ revisionDesc (revision description) summarizes the revision history for a file.
    • change documents a change or set of changes made during the production of a source document, or during the revision of an electronic file. A text within the tag should also be provided!
      • ‼️ n (number) gives a number (or other label) for an element, which is not necessarily unique within the document. Note that this is not a counter, but means the corpus version numbers, e.g. "1.0".
      • ‼️ when supplies the value of the date or time in a standard form, e.g. yyyy or yyyy-mm-dd.
      • 0️⃣ type specifies the kind of corpus revision undertaken. This is not ingested/shown in LAUDATIO.
      • 0️⃣ who indicates the person, or group of people, to whom the element content is ascribed. This is not ingested/shown in LAUDATIO.
<revisionDesc>
    <change n="4.0" type="QualityCheck" when="2014-04-01" who="LAUDATIO">Documents added,
        consistency check and unifying list of annotation keys.
    </change>
    <change n="4.1" type="Extension" when="2014-10-27" who="LAUDATIO">Annotation keys were added.</change>
    <change n="5.0" type="CorpusExtension" when="2016-06-07" who="LAUDATIO">Additional texts were
        added to the corpus. Conversion steps were changed. The corpus is now converted directly
        from EXCEL to PAULA and from EXCEL to ANNIS. Selective corrections of several annotation
        keys.
    </change>
</revisionDesc>

Footnotes​

  1. We are aware that this is a vague term. ↩

  2. BCP 47 seems to be interoperable with ISO 639 language tags, so this means we could work with very granular language tags. ↩

  3. Unclear how it is used right now. ↩