Skip to main content

Annotation 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

Best practice: Use the xml:id for this annotation provided in the corpus header for file naming (e.g. if the xml:id is "pos", the file should be called pos.xml).

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

  • type must be "PreparationHeader".
  • fileDesc (file description) provides description of an annotation layer, such as its name, annotator, etc.
  • ‼️ 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 annotation TEI header is thus as follows:

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

The four main tags are described in detail below.



fileDesc​

The fileDesc contains the following tags where the basic meaning is left untouched, but they simply reference the concept Annotation. For example, the tag author refers to the author of the annotation and the tag title refers to the name of an annotation layer. Tags used within fileDesc are:

  • 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.
  • 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 as follows:

<fileDesc>
    <titleStmt>
        <title>...</title>
        <editor>...</editor>
        <author>...</author>
        <respStmt>...</respStmt>
    </titleStmt>
    <extent>...</extent>
    <publicationStmt>
        <authority>...</authority>
        <availability>...</availability>
        <date>...</date>
    </publicationStmt>
    <sourceDesc>...</sourceDesc>
</fileDesc>

titleStmt​

tip

Best practice: Use the file name as the the ‼️ corresp (e.g. if the file is pos.xml, ‼️ corresp should be "pos").

The titleStmt contains the title, editors, annotators, and technical staff (infrastructure) of the annotation layer. LAUDATIO requires a TEI XML file for each annotation layer in the corpus. Each annotation needs an XML ID, which must be specified in the attribute xml:id in the corpus metadata. This xml:id is used here in corresp within title.

The titleStmt therefore looks like this:

  • title contains the name of the annotation layer.
    • corresp refers to the xml:id of this layer in the the corpus metadata and also the file name.
    • type must be "AnnotationKey".
  • ‼️ editor denotes those responsible for creating this annotation layer. Usually corresponds to those who edited the corpus.
    • 0️⃣ n specifies the numerical order of people to be listed.
    • role specifies the role of this person. Only possible value is "CorpusEditor".
    • ‼️ 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.
    • 🔂 affiliation contains an informal description of a person's present or past affiliation with some organization, for example an employer or sponsor. If at least one editor has the affiliation tag, all other editors should have it too. Plus, all affiliation tags must contain the same number of orgName tags.
      • 🔂 orgName (organization name) contains the name of the organization a person is affiliated with.
        • ‼️ type must be either "Department" or "Institution".
  • 0️⃣ author denotes the technical staff of this annotation (those responsible for annotation, infrastructure, or transcription).
    • 0️⃣ n specifies the numerical order of people to be listed. These can be counted separately for each role below!
    • role specifies the role of this person. Possible values are "Annotator", "Infrastructure", and "Transcription".
    • 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.
    • 🔂 affiliation contains an informal description of a person's present or past affiliation with some organization, for example an employer or sponsor. If at least one author has the affiliation tag, all other editors should have it too. Plus, if present, all affiliation tags must contain the same number of orgName tags.
      • 🔂 orgName (organization name) contains the name of the organization a person is affiliated with.
        • ‼️ type must be either "Department" or "Institution".
  • 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.
        • 0️⃣ type must be either "Department" or "Institution".

An example of the titleStmt looks like this:

<titleStmt>
    <title corresp="pos" type="AnnotationKey">POS</title>
    <editor n="1" role="CorpusEditor"><!-- add more editors if necessary -->
        <persName><!-- optional, recommended add norm references such as OCRIDs as attributes, 
            add @key and @ref, e.g.: key="orcid" ref="https://orcid.org/1234-1234-1234-" -->
            <forename>Jane</forename>
            <surname>Doe</surname>
        </persName>
        <affiliation>
            <orgName type="Department">Department of Linguistics</orgName>
            <orgName type="Institution">XYZ</orgName>
        </affiliation>
    </editor>
    <author n="1" role="Annotator"><!-- add more annotators if necessary, count in attribute @n -->
        <persName>
            <forename>John</forename>
            <surname>Doe</surname>
        </persName>
        <affiliation>
            <orgName type="Department">Department of History</orgName>
            <orgName type="Institution">University</orgName><
        </affiliation>
    </author>
    <respStmt>
        <resp>Metadata</resp>
        <persName><!-- add more if necessary -->
            <forename>John</forename>
            <surname>Doe</surname>
        </persName>
        <orgName type="Department">Department of History</orgName>
        <orgName type="Institution">University</orgName>
    </respStmt>
</titleStmt>

extent​

The ‼️ extent provides information about the size of the corpus. 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">305056</extent>

publicationStmt​

The publicationStmt covers the authority, availability, and publication dates. Annotations are published with a certain version of a corpus, so the publicationStmt refers here only to the corpus publication dates.

  • authority (release authority) supplies the name of a person or other agency responsible for making a work available, other than a publisher or distributor.
  • 0️⃣ availability supplies information about the availability of a text, for example any restrictions on its use or distribution, its copyright status, any licence applying to it, etc. This does not get ingested/shown in LAUDATIO.
    • status supplies a code identifying the current availability of the text.
    • licence information on the licence applying to the corpus.
      • 0️⃣ target supplies a URI to the chosen licence.
    • 0️⃣ p (paragraph) shortly describes the licence.
  • date contains a date in any format. A text within the tag should also be provided!
    • ‼️ type describes the kind of release this license is associated with.
    • when supplies the value of the date or time in a standard form, e.g. yyyy or yyyy-mm-dd.

An example of is given here:

<publicationStmt>
    <authority>Humboldt-Universität zu Berlin</authority>
    <availability status="free">
        <licence target="http://creativecommons.org/licenses/by/3.0/" />
    </availability>
    <date type="AnnotationRelease" when="2017-09-21">Licensed under a Creative Commons
        Attribution 3.0 Unported License. Seventh corpus release. Annotation is released in the
        seventh version.
    </date>
    <date type="AnnotationRelease" when="2018-03-29">Licensed under a Creative Commons
        Attribution 3.0 Unported License. Eighth corpus release. Annotation is released in the
        eighth version.
    </date>
    <date type="AnnotationRelease" when="2020-03-31">Licensed under a Creative Commons
        Attribution 3.0 Unported License. Ninth corpus release. Annotation is released in the
        ninth version.
    </date>
</publicationStmt>

sourceDesc​

tip

If an annotation documentation is not applicable or known, you still need to provide this tag! However, you can leave it blank like this:

<sourceDesc>
    <p>
    </p>
</sourceDesc>

sourceDesc contains a description and link to the annotation documentation. This is not shown in LAUDATIO.

  • p (paragraph) contains the text description. Only this value is ingested.
    • 0️⃣ ref (reference) defines a reference to another location (e.g. the project homepage), possibly modified by additional text or comment.
      • 0️⃣ target specifies the destination of the reference by supplying one or more URI References.
      • 0️⃣ type
<sourceDesc>
    <p>
        <ref target="https://hu.berlin/ridges-documentation-v8-en" type="CorpusHomepage" />
        Corpus Homepage (Documentation).
    </p>
</sourceDesc>


encodingDesc​

info

The attribute n is ignored when determining the order for LAUDATIO. What counts is the actual order within the TEI file to determine the sequence of preparation steps.

The ‼️ encodingDesc for an annotation layer provides information on how and with which tools this annotation layer was achieved and what kind of segmentation and corrections were applied. They should ideally reflect the ordered preparation steps by which this annotation layer was created.

It has the following attributes and tags:

  • 0️⃣ n (number) refers to step number of this preparation.
  • ‼️ style gives the name of the encoding/preparation step (free text).
  • ‼️ appInfo specifies each preparation step.
  • 0️⃣ editorialDecl contains details on segmentation and normalization of each preparation step.
  • 0️⃣ projectDesc describes the research project and its references.

The basic structure is thus as follows:

<encodingDesc n="1" style="SpanAnnotation">
    <!-- each <encodingDesc> describes describes a preparation step for this annotation layer, add more <encodingsDesc> if the annotation has more than one preparation step -->
    <appInfo>...</appInfo>
    <editorialDecl>...</editorialDecl>
    <projectDesc>...</projectDesc>
</encodingDesc>

appInfo​

The ‼️ appInfo (application information) records information about application/software used in this preparation step:

  • 0️⃣ n (number) gives a number (or other label) for an element, which is not necessarily unique within the document.
  • style gives the model type for the encoding/preparation step. Possible values are: "Automatic", "Semi-automatic", "Manual".
  • application provides information about an used application/software.
    • ident supplies an identifier for the application/software (independent of its version number or display name), e.g. "EXCEL" or "ANNIS".
    • style is used to give the file extension of this preparation step (e.g. .xls)
    • type defines the type of preparation step. In LAUDATIO, this is currently only shown in search results and annotation tables, but NOT on the detail page of an annotation layer. Corresponds to the closed list of annotation layer classification:
      • "Transcription"
      • "Lexical"
      • "Morphological"
      • "Syntactic"
      • "Graphical"
      • "MarkUp"
      • "Meta"
      • "Other"
    • subtype is a free field and supplies a subcategorization for the preparation step (if not applicable, enter "NA").
    • version supplies a version number for the format (independent of its identifier or display name), e.g. "15.0.4551.1011".
    • ‼️ label contains a free-form field to name the application/software.
    • ‼️ p contains a free-form field to describe what was done in the application/software.
<appInfo n="1" style="Manual">
    <application ident="EXCEL" style="xls" subtype="NA" type="Lexical" version="15.0.4551.1011">
        <label>MS EXCEL 2013.</label>
        <p>Span annotation with key "abbr" of all documents of RIDGES Herbolgy 9.0
            Manually annotated by annotators. Consistency checks and further changes
            such as changes in tokenization are applied in this preparation step. For
            further information see https://hu.berlin/ridges-documentation-v9-en.
        </p>
    </application>
</appInfo>

editorialDecl​

0️⃣ editorialDecl (editorial practice declaration) provides details of editorial principles and practices applied during the encoding of a text. This is not shown in LAUDATIO.

  • ‼️ segmentation describes the principles according to which the text has been segmented, for example into sentences, tone-units, graphemic strata, etc.
    • 0️⃣ corresp corresponds to the annotation layer this layer depends on (if style is "Dependent").
    • 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: "Dependent", "Independent"
  • 0️⃣ normalization indicates the extent of normalization or regularization of the original source carried out in converting it to electronic form. This is not ingested.
    • method indicates the method adopted to indicate normalizations within the text. Possible values: "None", "Silent", "Automatic".
  • 0️⃣ correction (correction principles) states how and under what circumstances corrections have been made in the text. This is not ingested.
    • method indicates the method adopted to indicate corrections within the text. Possible values: "manual", "semi-automatic", "automatic".
    • 0️⃣ status indicates the degree of correction applied to the text. Possible values: "high", "medium", "low", "unknown".
<editorialDecl>
    <segmentation corresp="norm" style="Dependent">
        <p>Segmentation depends on "norm".</p>
    </segmentation>
    <normalization method="None">
        <p>NA</p>
    </normalization>
    <correction method="manual" status="low">
        <p>Manually checked by annotator.</p>
    </correction>
</editorialDecl>

projectDesc​

0️⃣ projectDesc (project description) describes in detail the aim or purpose for which an electronic file was encoded, together with any other relevant information concerning the process by which it was assembled or collected. This is not shown in LAUDATIO.

  • p (paragraph) contains the project description. Only the text is ingested, the tag ref is ignored.
    • 0️⃣ ref (reference) defines a reference to another location (e.g. the project homepage), possibly modified by additional text or comment.
      • 0️⃣ target specifies the destination of the reference by supplying one or more URI References
 <projectDesc>
    <p>
        <ref target="http://korpling.org/ridges/" />
        The RIDGES project (Register in Diachronic German Science) is an investigation into the development
            of the German scientific language in the early modern and modern periods,
            ranging from the mid 15th to the 20th century. The LAUDATIO project
            (www.laudatio-repository.org) hosts and curates the RIDGES Herbology
            corpus in cooperation with the LangBank project (sfs.uni-tuebingen.de/langbank).
    </p>
</projectDesc>


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 annotation.

  • ‼️ 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.
      • type specifies the kind of corpus revision undertaken. This is not ingested/shown in LAUDATIO.
      • 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="9.0" type="Creation" when="2020-03-31" who="NA">Annotation was added to the corpus.</change>
</revisionDesc>