Recommended XML Annotation of Text Corpora in the Language Bank

Overview

Dokumenttien primääridatan koodaus

Kielipankin tekstikokoelmat ovat jossain määrin eri formaateissa. Suomen ja suomenruotsin dokumentit ovat XML-formaatissa, joka noudattaa muokattua XCES-tekstinkoodausstandardia.

Esimerkki 1 osakokoelmasta Iltalehti 1996:

[...]
  <text lang="FI">
    <body>
      <div type="article">
        <head type="title"> Eikö kukaan halua missiä malliksi?</head>
        <opener>
	  Draamassa, palstoilla, sketseissä, kansantarinoissa elävät
	  virkeää elämäänsä sitkeät uskomukset mm. tiettyjen ammattien
	  kytkeytymisestä tiettyihin ominaisuuksiin. Tyhjäpäisyyden
	  symboleja ovat esimerkiksi olleet kaunis missi ja/tai malli.
	  Yhdet fiksut kauneuden ammattilaiset ovat murentaneet
	  yleistystä. Toiset taas eivät ole siinä onnistuneet.
        </opener>
        <p>
  	  Ex–päätoimittaja, kirjantekijä Riitta Kivilahti,
  	  mallialan tuntija, myöntää, että alan vitsaus on epärealismi
  	  ja itsekritiikittömyys.
        </p>
[...]

Dokumenttien morfosyntaktinen koodaus

Suomen kielen tekstikokoelman dokumenttien XML-koodaus on joko pelkkä tekstirakenteen koodaus (syksyllä 2002: 340 000 dokumenttia, 45 %, katso esimerkki 1) tai sekä tekstirakenteen että morfosyntaksin koodaus (syksyllä 2002: 400 000 dokumenttia, 55 %, katso esimerkki 2). Morfosyntaktinen koodaus on suoritettu automaattisesti Kielikone Oy:n toimittamalla Textmorfo-ohjelmistolla.

Suomenruotsin dokumentit on kaikki morfosyntaktisesti koodattu Lingsoft Oy:n toimittamalla SWECG-ohjelmistolla.

Esimerkki 2 osakokoelmasta Karjalainen 1991:

[...]
  <p>
    <s>
      <w lemma="Hirvi" type="Noun" msd="Part SG">Hirveä</w>
      <w lemma="rasittaa" type="Verb" msd="Imp Act Ind S 3P">rasitti</w>
      <w lemma="myös" type="Adverb" msd="">myös</w>
      <w lemma="suunnaton" type="Adjective" msd="Nom SG">suunnaton</w>
      <w lemma="syylämäärä" type="Noun" msd="Nom SG">syylämäärä</w>
      <w lemma="_PERIOD" type="Delimiter" msd="">.</w>
    </s>
    <s>
      <w lemma="Ne" type="Pronoun" msd="Nom PL P 3P">Ne</w>
      <w lemma="riippua" type="Verb" msd="Imp Act Ind P 3P">riippuivat</w>    
      <w lemma="takajalka" type="Noun" msd="Gen PL">takajalkojen</w>
      <w lemma="etupuoli" type="Noun" msd="Ad SG">etupuolella</w>
      <w lemma="kuin" type="Conjunction" msd="">kuin</w>
      <w lemma="lehmä" type="Noun" msd="Gen SG">lehmän</w>
      <w lemma="utare" type="Noun" msd="Nom PL">utareet</w>
      <w lemma="_PERIOD" type="Delimiter" msd="">.</w>
    </s>
  </p>
[...]

Corpus encoding guidelines

About this section

This section contains information about how to encode corpus files so that they are in the same format as the files at the Language Bank of Finland. The benefit of encoding new corpus files using these standards is that such files can be seamlessly integrated in the Language Bank. (Well, at least from a technical point of view, for copyright issues, see the page with contract templates.)

Requirements

The following requirements must be met if a corpus file is to be considered compatible with the standards used at the Language Bank of Finland:

1. Well-formed and valid (= Language Bank DTD conformant) XML

All corpus files must be well-formed and valid according to the XML DTD used at the Language Bank. (The DTD and the DTD’s documentation can be found here.)

Measure: A validating XML parser must produce zero errors when parsing the corpus files which are encoded according to the XML DTD at the Language Bank.

2. One ”text entity” per file

If possible, store the data in small, logical units, e.g. one newspaper article = one file, one chapter in a book = one file. This will make the use of the files easier and make it easier to write the metadata in the header. If you must mix several textual entities in one file, use the <div> element to separate them from each other.

Measure: There is no real measure, use common sense.

3. Minimum amount of encoding errors

Pay attention to the semantics of your encoding; even if an XML file is parsed successfully, there might be several structural errors in it, like bylines being tagged as subheadings etc. This is in particular important when doing automatic conversion.

Measure: If you have less than 1000 files, inspect 10 of them for logical errors. If you have 1000 to 10000 files, inspect 50 of them. If you have even more files, inspect 100 of them. Correct these errors globally (automatically with a script), i.e. in all of your files; it is likely that the errors you have found in a subset of your files, occur as frequently in the files you haven’t inspected as in the inspected ones. Run a few rounds of inspections using different files every time, until less than one tenth of the inspected files contain any visible logical errors.

4. Pretty-printed XML files

Indent the XML files with two spaces for each start tag and going back two spaces for each end tag. Place tags and character data on different lines when applicable.

Measure: Use common sense and compare with the examples linked to below.

5. Use character references, not character entities

In SGML, character references (like –) are common, in the XML files in the Language Bank we are trying to use Unicode conformant character references instead (like ”). This eases up parsing and also possible display of the file in a web browser window. Naturally the standard XML character entites (like & and <) can be used. Such entities that ”come by default” with XML are OK.

Measure: grep ’&[^#]’ files | grep -v ’&’ …

6. Be legal!

The copyright issue is a picky subject. Make sure you have written permisson to publish the corpus files for public (academic/commersial) use. Texts not bound by legal contracts are not incorporated in the Language Bank.

Measure: Follow these corpus contract guidelines and everything will be fine.

Encoding tips

  • Files without linguistic annotation:
    • Encode carefully at least down to the paragraph level. (I.e. any structural data beneath that need not be encoded, e.g. style markings like italics or bold face.)
  • Annotated files:
    • Encode orthographic sentences into =<s>= elements and word tokens into =<w>= elements. Use the lemma attribute for storing the baseform of the word token, the type attribute for storing the part-of-speech and the msd attribute for storing any other morpholsyntactic information about the token. (If the corpus files are to be used with Lemmie, there is a need for thorough documentation of what resides in the msd attribute too.)
    • If you are about to encode your corpus files with richer linguistic annotation than on the word level, please let us know by e-mailing ling…csc.fi. The current DTD probably cannot handle it, but there is no reason a future one shouldn’t!
  • All files:
    • Fill out the header as extensively as possible, i.e. do not leave out metadata. This is important when categorizing the files. Common types of metadata information is for example the author of a text, the category of a newspaper article (e.g. ”sports”), the publication date.

Example file 1

A faked newspaper article without linguistic annotation:

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!DOCTYPE TEI.2 SYSTEM "/usr/lib/sgml/dtd/sktpxml.dtd">
<TEI.2>
  <teiHeader type="text">
    <fileDesc>
      <titleStmt>
        <title>Corpus file 1234</title>
        <respStmt>
          <name>Collin Converter</name>
          <resp>sktp encoding - converted automatically into tei markup</resp>
        </respStmt>
      </titleStmt>
      <extent>
        <wordCount>118</wordCount>
        <byteCount units="bytes">1124</byteCount>
      </extent>
      <publicationStmt>
        <distributor>The department of Whatever, University of Somewhere</distributor>
        <availability status="restricted">	  
          <p>
	    This file can only be used by my friend and neighbor, mr. Jack MacKenzie.
          </p>
	</availability>
        <date>2002-02-07</date>
      </publicationStmt>
      <sourceDesc>
        <p>
	  /proj/corpus/originals/newyorktimes/2002/02/1234.doc
        </p>
        <biblStruct>
          <monogr>
            <author>Michael Knight</author>
            <title>
	      Less goose on the loose
	    </title>
            <imprint>
              <publisher>New York Times</publisher>
              <pubPlace>New York City, NY, USA</pubPlace>
              <date>2002-01-30</date>
            </imprint>
          </monogr>
        </biblStruct>
      </sourceDesc>
    </fileDesc>
    <encodingDesc>
      <classDecl>
      &corpustaxonomy;
      </classDecl>
    </encodingDesc>
    <profileDesc>
      <creation>
        2002-01-29
      </creation>
      <langUsage>
      &corpuslanguages;
      </langUsage>
      <textClass>
        <catRef target="P.M2"/> <!-- P.M2 stands for newspaper article -->
      </textClass>
    </profileDesc>
    <revisionDesc>
      <change>
        <date>2002-02-08</date>
        <respStmt>
          <name>John Doe/name>
          <resp>
	    Found a lot of errors in the encoding, so I removed all dummy tags
	    that screwed up the XML validation.
          </resp>
        </respStmt>
        <item></item>
      </change>
    </revisionDesc>
  </teiHeader>
  <text lang="EN">
    <body>
      <div type="article">
        <head type="title">          
	  Less goose on the loose
        </head>
        <byline>          
	  Michael Knight 
        </byline>
        <opener>
          <s>
	    "There are less goose on the loose in town tonight," says Maryland
	    police official John Dermick to the New York Times.
          </s>
	  <s>
	    "Apparently, they have all moved to the moon."
	  </s>
	</opener>
	<p>
	  <s>
	    The problems started back in 1976 when people had goose as pets.
	  </s>
	  <s>
	    Sometimes, the goose just ran away.
	  </s>
	  <s>
	    This led to a terrible explosion in the amount of goose inhabitants 
	    in New York City.
	  </s>
	</p>
	<p>
	  <s>
	    Well, know when the problems are solved, there is no need to talk 
	    about it any more.
	  </s>
	</p>
	<caption>
	  Police official John Dermick on his daily goose hunt.
	</caption>
      </div>
    </body>
  </text>
</TEI.2>

Example file 2

The same newspaper article as in Example file 1 with linguistic annotation:

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!DOCTYPE TEI.2 SYSTEM "/usr/lib/sgml/dtd/sktpxml.dtd">
<TEI.2>
  <teiHeader type="text">
    <fileDesc>
      <titleStmt>
        <title>Corpus file 1234</title>
        <respStmt>
          <name>Collin Converter</name>
          <resp>sktp encoding - converted automatically into tei markup</resp>
        </respStmt>
      </titleStmt>
      <extent>
        <wordCount>118</wordCount>
        <byteCount units="bytes">1124</byteCount>
      </extent>
      <publicationStmt>
        <distributor>
	  The department of Whatever, University of Somewhere
	</distributor>
        <availability status="restricted">	  
          <p>
	    This file can only be used by my friend and neighbor, 
	    mr. Jack MacKenzie.
          </p>
	</availability>
        <date>2002-02-07</date>
      </publicationStmt>
      <sourceDesc>
        <p>
	  /proj/corpus/originals/newyorktimes/2002/02/1234.doc
        </p>
        <biblStruct>
          <monogr>
            <author>Michael Knight</author>
            <title>
	      Less goose on the loose
	    </title>
            <imprint>
              <publisher>New York Times</publisher>
              <pubPlace>New York City, NY, USA</pubPlace>
              <date>2002-01-30</date>
            </imprint>
          </monogr>
        </biblStruct>
      </sourceDesc>
    </fileDesc>
    <encodingDesc>
      <classDecl>
      &corpustaxonomy;
      </classDecl>
    </encodingDesc>
    <profileDesc>
      <creation>
        2002-01-29
      </creation>
      <langUsage>
      &corpuslanguages;
      </langUsage>
      <textClass>
        <catRef target="P.M2"/> <!-- P.M2 stands for newspaper article -->
      </textClass>
    </profileDesc>
    <revisionDesc>
      <change>
        <date>2002-02-08</date>
        <respStmt>
          <name>John Doe/name>
          <resp>
	    Found a lot of errors in the encoding, so I removed all dummy tags
	    that screwed up the XML validation.
          </resp>
        </respStmt>
        <item></item>
      </change>
      <change>
        <date>2002-02-09</date>
        <respStmt>
          <name>John Doe/name>
          <resp>
	    Encoded the file with the morphological tagger.	    
          </resp>
        </respStmt>
        <item></item>
      </change>
    </revisionDesc>
  </teiHeader>
  <text lang="EN">
    <body>
      <div type="article">
        <head type="title">
	  <s>          
	    <w lemma="little" type="ADV" msd="CMP">Less</w>
	    <w lemma="goose"> type="N" msd="NOM SG">goose</w>
	    <w lemma="on" type="PREP" msd="">on</w>
	    <w lemma="the" type="DET" msd="CENTRAL ART SG/PL">the</w>
	    <w lemma="loose" type="A" msd="ABS">loose</w>
	  </s>
        </head>
        <byline>          
	  <s>
	    <w lemma="michael" type="N" msd="NOM SG">Michael</w>
	    <w lemma="knight" type="N" msd="NOM SG">Knight</w>
	  </s>
        </byline>
	<gap reason="lazyness" />
      </div>
    </body>
  </text>
</TEI.2>

Links

  • The DTD is available at the address: /l/kielipankki/wwwcsc/www.csc.fi/kielipankki/aineistot/ohjeet/xml/dtd/sktpxml.dtd
  • http://www.xml-ces.org/ XCES Corpus Encoding Standard for XML
  • Documentation of the XML DTD used in the Language Bank:
    • Original Location: http://www.csc.fi/kielipankki/aineistot/ohjeet/xml/dtd/DTD-HOME.phtml.en
    • Mirrored to a UNIX location: /l/kielipankki/wwwcsc/www.csc.fi/kielipankki/aineistot/ohjeet/xml/dtd/DTD-HOME.phtml.en
Kuukauden tutkija: Eero Voutilainen

 

Yhteystiedot

Kielipankin tekninen ylläpito:
kielipankki (ät) csc.fi
p. 09 4572001

Aineistoihin ja muuhun sisältöön liittyvät asiat:
fin-clarin (ät) helsinki.fi
p. 029 4140599 / 029 4129317