Introduction aux schémas et au modèle TEI

Si ce chapitre essaie de présenter tous les principes à l'œuvre dans la création des schémas et leur fonctionnement général, il n'entre pas dans les détails concrets de leur création ni même de la syntaxe de leurs langages. Il a été envisagé pour comprendre les principes de la validation et comme une entrée vers le modèle général de la TEI, un détour, certes abstrait, mais à notre avis nécessaire pour s'engager dans la voie de la TEI.

La DTD

La DTD ou Document Type Definition définit une structure et une série de règles pour l'usage des éléments et des attributs dans un document XML. Elle est héritée de l'environnement SGML et est particulièrement adaptée pour de petits modèles, car relativement simple à écrire. Elle se débute avec l'appellation <!DOCTYPE> qui doit être suivie directement par le nom de l'élément racine. Ensuite, entre crochets, on peut déclarer les contraintes. Ces dernières spécifient comment les éléments s'emboîtent entre eux, l'ordre éventuel des éléments et la présence de texte brut. Elles définissent aussi, pour chaque élément, les attributs autorisés et les attributs obligatoires. Enfin, elle permet de définir des raccourcis pour certaines entités, grâce à <!ENTITY>.

<!DOCTYPE NEWSPAPER [

<!ELEMENT NEWSPAPER (ARTICLE+)>
<!ELEMENT ARTICLE (HEADLINE,BYLINE,LEAD,BODY,NOTES)>
<!ELEMENT HEADLINE (#PCDATA)>
<!ELEMENT BYLINE (#PCDATA)>
<!ELEMENT LEAD (#PCDATA)>
<!ELEMENT BODY (#PCDATA)>
<!ELEMENT NOTES (#PCDATA)>

<!ATTLIST ARTICLE AUTHOR CDATA #REQUIRED>
<!ATTLIST ARTICLE EDITOR CDATA #IMPLIED>
<!ATTLIST ARTICLE DATE CDATA #IMPLIED>
<!ATTLIST ARTICLE EDITION CDATA #IMPLIED>

<!ENTITY NEWSPAPER "Vervet Logic Times">
<!ENTITY PUBLISHER "Vervet Logic Press">
<!ENTITY COPYRIGHT "Copyright 1998 Vervet Logic Press">
]>

Source: W3 schools

Elle peut se déclarer directement dans un fichier XML, ou dans un document propre, dont le suffixe sera alors .dtd.

<!DOCTYPE TEI SYSTEM "digital-areal.dtd">

Ce que l'on ne peut pas faire avec une DTD

La DTD présente néanmoins quelques limites:

pas de gestion des espaces de nom
pas de typage précis du contenu des éléments (chaîne de caractères de texte, nombre entier, etc.) ou de leur sens (date, heure, nom, etc.), si l'on peut typer les attributs, cela reste de l'ordre du général
peu de contraintes sur les éléments (nombre d'occurrences, élément racine, etc)
pas écrite en XML

Ce que permet de faire la DTD

Par contre, la DTD permet de déclarer des entités, ce qui est absent de tous les langages de schéma, et dont nous verrons un exemple dans le chapitre 5 pour les allographes.

Les schémas XML

Un schéma définit un modèle de document que l'on peut ensuite utilisé pour vérifier les documents produits, c'est-à-dire que l'on vérifie qu'un document respecte une liste de contraintes fixées. Les schémas sont apparus avec le passage à l'XML et ont été introduits pour combler certaines limites des DTD, dont l'utilisation était surtout concomitante avec le SGML. Leur modèle est normé par le W3C. Ils s'écrivent en suivant les règles de la syntaxe XML, ce qui permet de les parser et de les transformer avec les mêmes technologies que les autres documents XML. Ils répondent en cela à une volonté d'établir une documentation lisible à la fois pour la machine et par l'homme.

Il est ainsi plus simple à échanger et à conserver qu'un fichier issu d'un traitement de texte ou un PDF.
Il offre plus de possibilités pour fixer des contraintes:
- il détermine les éléments et les attributs qui peuvent être utilisés dans le document
- il fixe le nombre et l'ordre des éléments enfants et des attributs
- il caractérise le type de donnée que peut contenir un élément ou un attribut
- il contient les valeurs par défaut ou les valeurs fixes ou une liste de valeurs fixes pour les éléments ou les attributs.

Les formats de schéma

XML Schema (.xs ou .xsd)
- en particulier si l'on souhaite faire un typage très fin des données
RelaxNG (REgular LAnguage for Xml Next Generation)
- deux syntaxes : compacte (.rnc) ou XML (.rng)
- lié historiquement à la TEI
- simple, souple et très largement utilisé, y compris par d'autres langages XML normés (Docbook, OpenDocumentFormat, EAD3)
Schematron
- une version 1.0 sous ISO
- définit des tests et contraintes de contenu absents des autres langages, grâce à XPath, qui permet de se concentrer sur des parties spécifiques du document et de les confronter à des données structurées extérieures

Combiner les schémas?

Pour un projet, on travaille avec un ou plusieurs schémas; par exemple, en RelaxNG pour définir les éléments et les attributs, mais avec les types XSD et des contraintes Schematron. Dans le repository, vous avez des exemples de schémas faits pour DHARMA:

RelaxNG en format XML, avec des lignes de Schematron

<define name="tei_gap">
   <element name="gap">
      <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0">indicates a point where material has been omitted in a transcription, whether for editorial reasons described in the TEI header, as part of sampling practice, or because the material is illegible, invisible, or inaudible. [3.4.3. Additions, Deletions, and Omissions]</a:documentation>
      <zeroOrMore>
         <choice>
            <ref name="tei_model.descLike"/>
            <ref name="tei_model.certLike"/>
         </choice>
      </zeroOrMore>
      <pattern xmlns="http://purl.oclc.org/dsdl/schematron"
               id="dharma-gap-gap-constraint-rule-13">
         <sch:rule xmlns="http://www.tei-c.org/ns/1.0"
                   xmlns:sch="http://purl.oclc.org/dsdl/schematron"
                   context="tei:gap">
            <sch:report test="@quantity and @extent">gap may have @quantity (a figure) or
                         @extent (a descriptive text value) but not both</sch:report>
            <sch:report test="@quantity and not(@unit)">If gap has @quantity then @unit is
                         required</sch:report>
            <sch:report test="not(@reason='ellipsis') and ancestor::tei:supplied[not(@reason='undefined')]">gap may not appear within supplied text</sch:report>
            <sch:report test="@precision and not(@quantity)">@precision can be use only with
                         @quantity</sch:report>
            <sch:report test="ancestor::tei:div[@type='aparatus'] and not(@reason)">Only @reason
                         is mandatory in
                         div[@type='translation']</sch:report>
         </sch:rule>
         <sch:rule xmlns="http://www.tei-c.org/ns/1.0"
                   xmlns:sch="http://purl.oclc.org/dsdl/schematron"
                   context="tei:gap[@reason='ellipsis']">
            <sch:report test="not(ancestor::tei:div[@type='apparatus'] or ancestor::tei:div[@type='translation'])"> The element gap with @reason='ellipsis' can only be used inside the
                         apparatus or in translation.</sch:report>
         </sch:rule>
         <sch:rule xmlns="http://www.tei-c.org/ns/1.0"
                   xmlns:sch="http://purl.oclc.org/dsdl/schematron"
                   context="tei:gap[@unit='component']">
            <sch:assert test="parent::tei:seg[@type='component']">Gap with the attribute
                         @unit="component" can only be used inside seg with the
                         @type="component". </sch:assert>
         </sch:rule>
         <sch:rule xmlns="http://www.tei-c.org/ns/1.0"
                   xmlns:sch="http://purl.oclc.org/dsdl/schematron"
                   context="tei:gap[@unit='line' and @quantity] ">
            <sch:assert test="@precision='low' or child::tei:certainty">The element gap with
                         @quantity and @unit="line" expect either the use of @precision="low" or
                         the element certainty.</sch:assert>
         </sch:rule>
      </pattern>
      <ref name="tei_att.dimensions.attribute.quantity"/>
      <optional>
         <attribute xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
                    name="precision"
                    a:defaultValue="low">
            <a:documentation/>
            <choice>
               <value>low</value>
               <a:documentation/>
            </choice>
         </attribute>
      </optional>
      <optional>
         <attribute name="unit">
            <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0">names the unit used for the measurement</a:documentation>
            <choice>
               <value>character</value>
               <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
               <value>component</value>
               <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
               <value>line</value>
               <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
               <value>page</value>
               <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
               <value>plate</value>
               <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
               <value>folio</value>
               <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
            </choice>
         </attribute>
      </optional>
      <optional>
         <attribute xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
                    name="extent"
                    a:defaultValue="unknown">
            <a:documentation>indicates the size of the object concerned using a project-specific vocabulary combining quantity and units in a single string of words.</a:documentation>
            <choice>
               <value>unknown</value>
               <a:documentation/>
            </choice>
         </attribute>
      </optional>
      <attribute name="reason">
         <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0">gives the reason for omission</a:documentation>
         <choice>
            <value>lost</value>
            <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
            <value>illegible</value>
            <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
            <value>omitted</value>
            <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
            <value>ellipsis</value>
            <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
            <value>undefined</value>
            <a:documentation xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"/>
         </choice>
      </attribute>
      <empty/>
   </element>
</define>

Schematron autonome avec des ajouts de Schematron Quick Fix

<sch:pattern>
    <sch:rule context="t:bibl[parent::t:listBibl[@type='primary']]">
        <sch:assert test="./@n" sqf:fix="add-siglum">@n mandatory in
            the primary bibliography to declare
            sigla</sch:assert>

        <sqf:fix id="add-siglum">
            <sqf:description>
                <sqf:title>Add @n for the siglum</sqf:title>
            </sqf:description>
            <sqf:add node-type="attribute" target="n"/>
        </sqf:fix>
    </sch:rule>
</sch:pattern>

ODD

Lorsque l'on travaille avec la TEI, nous sommes rapidement confrontés à l'ODD: One Document Does it all. Il s'agit d'un document qui centralise la documentation, le schéma de validation d'un projet et parfois les règles de transformation et à partir duquel on génère ou regénère plusieurs formats aussi bien pour la documentation (en XHTML, PDF, ODT, EPUB, DOCX ...) que pour les schémas (RelaxNG XML ou compact, XML Schema ou DTD).

NB: L'ODD peut se présente avec une extension de fichier .odd, mais le plus souvent il se trouve en format .xml ce qui pourrait faire émerger des confusions lorsque l'on recherche un fichier.

Créer un ODD

Il est assez rare que l'on crée un fichier ODD à la main et ex nihilo. Quelques outils ont été mis en place pour faciliter son écriture:

Roma, un outil maintenu par la TEI pour faire des schémas et des documentations en différents formats. Il est recommandé de faire une sauvegarde ODD, car l'outil ne prend que ce format en entrée et est donc nécessaire pour travailler ces schémas en plusieurs séances de travail ou juste pour faire des reprises.
Utiliser les feuilles de style oddbyexample pour créer un fichier ODD.

Le modèle TEI

Il s'agit d'un modèle abstrait de données, soit un ensemble de concepts, ainsi que les différentes relations entre ceux-ci. Il faut donc distinguer ce modèle de ses implémentations techniques, qu'elles soient générales par l'importation de modules entiers comme celui du théâtre ou de la transcription, ou particulières avec une sélection d'éléments pour correspondre aux besoins d'un projet.

Les modules

Les modules correspondent aux chapitres des Guidelines. Ils définissent des composantes du modèle (éléments, classes, macros), les spécifications techniques et peuvent se concevoir comme des blocs que l'on conserve ou que l'on supprime notamment par rapport aux schémas.

les obligatoires:

tei (déclaration des classes, macros et types)
textstructure (éléments de la structure du fichier)
core (ensemble des éléments considérés comme basiques et communs à tous les encodages)
header (métadonnées)

les spécialisés:

analysis (analyse linguistique);
certainty (certitude et responsabilité) ;
corpus (corpus) ;
drama (théâtre) ;
figures (tableaux, figures et formules) ;
gaiji (caractères non standard) ;
iso-fs (structures de traits) ;
linking (liens, segmentation, alignements) ;
msdescription (description des manuscrits) ;
namesdates (noms, dates, lieux) ;
nets (graphes, réseaux, arbres) ;
textcrit (apparat critique) ;
transcr (transcription) ;
verse (poésie).

Les classes

Les classes organisent les éléments et les attributs du modèle TEI et permettent de fixer les propriétés et les règles d'héritage partagées par plusieurs éléments et attributs.
Les classes sont identifiables par le préfixe att. pour les attributs et par model. pour les modèles d'éléments.

Les macros

Les macros sont des raccourcis qui permettent de spécifier le contenu, en particulier pour le contenu d'un élément ou pour les valeurs d'un attribut. Elles sont employées lors de la création des schémas. Elles débutent par le préfixe macro..

Lire et comprendre la documentation: un exemple avec l'élément body

<body>

<body> (text body) contains the whole body of a single unitary text, excluding any front or back matter. [4. Default Text Structure]
Module	textstructure
Attributes	Attributes att.global (@xml:id, @n, @xml:lang, @xml:base, @xml:space) (att.global.rendition (@rend, @style, @rendition)) (att.global.linking (@corresp, @synch, @sameAs, @copyOf, @next, @prev, @exclude, @select)) (att.global.analytic (@ana)) (att.global.facs (@facs)) (att.global.change (@change)) (att.global.responsibility (@cert, @resp)) (att.global.source (@source)) att.declaring (@decls)
Contained by	textstructure: floatingText text
May contain	analysis: interp interpGrp span spanGrp certainty: certainty precision respons core: bibl biblStruct cb cit desc divGen ellipsis gap gb head index l label lb lg list listBibl meeting milestone note noteGrp p pb q quote said sp stage dictionaries: entry entryFree superEntry drama: camera caption castList move sound spGrp tech view figures: figure notatedMusic table header: biblFull iso-fs: fLib fs fvLib linking: ab alt altGrp anchor join joinGrp link linkGrp timeline msdescription: msDesc namesdates: listEvent listNym listObject listOrg listPerson listPlace listRelation nets: eTree forest graph listForest tree spoken: annotationBlock incident kinesic pause shift u vocal writing tagdocs: classSpec constraintSpec dataSpec eg egXML elementSpec listRef macroSpec moduleSpec outputRendition schemaSpec specGrp specGrpRef textcrit: app listApp listWit witDetail textstructure: argument byline closer dateline div div1 docAuthor docDate epigraph floatingText opener postscript salute signed trailer transcr: addSpan damageSpan delSpan fw listTranspose metamark space substJoin
Example	<body> <l>Nu scylun hergan hefaenricaes uard</l> <l>metudæs maecti end his modgidanc</l> <l>uerc uuldurfadur sue he uundra gihuaes</l> <l>eci dryctin or astelidæ</l> <l>he aerist scop aelda barnum</l> <l>heben til hrofe haleg scepen.</l> <l>tha middungeard moncynnæs uard</l> <l>eci dryctin æfter tiadæ</l> <l>firum foldu frea allmectig</l> <trailer>primo cantauit Cædmon istud carmen.</trailer> </body>
Content model	<content> <sequence> <classRef key="model.global" maxOccurs="unbounded" minOccurs="0"/> <sequence minOccurs="0"> <classRef key="model.divTop"/> <alternate maxOccurs="unbounded" minOccurs="0"> <classRef key="model.global"/> <classRef key="model.divTop"/> </alternate> </sequence> <sequence minOccurs="0"> <classRef key="model.divGenLike"/> <alternate maxOccurs="unbounded" minOccurs="0"> <classRef key="model.global"/> <classRef key="model.divGenLike"/> </alternate> </sequence> <alternate> <sequence maxOccurs="unbounded" minOccurs="1"> <classRef key="model.divLike"/> <alternate maxOccurs="unbounded" minOccurs="0"> <classRef key="model.global"/> <classRef key="model.divGenLike"/> </alternate> </sequence> <sequence maxOccurs="unbounded" minOccurs="1"> <classRef key="model.div1Like"/> <alternate maxOccurs="unbounded" minOccurs="0"> <classRef key="model.global"/> <classRef key="model.divGenLike"/> </alternate> </sequence> <sequence> <sequence maxOccurs="unbounded" minOccurs="1"> <classRef key="model.common"/> <classRef key="model.global" maxOccurs="unbounded" minOccurs="0"/> </sequence> <alternate minOccurs="0"> <sequence maxOccurs="unbounded" minOccurs="1"> <classRef key="model.divLike"/> <alternate maxOccurs="unbounded" minOccurs="0"> <classRef key="model.global"/> <classRef key="model.divGenLike"/> </alternate> </sequence> <sequence maxOccurs="unbounded" minOccurs="1"> <classRef key="model.div1Like"/> <alternate maxOccurs="unbounded" minOccurs="0"> <classRef key="model.global"/> <classRef key="model.divGenLike"/> </alternate> </sequence> </alternate> </sequence> </alternate> <sequence maxOccurs="unbounded" minOccurs="0"> <classRef key="model.divBottom"/> <classRef key="model.global" maxOccurs="unbounded" minOccurs="0"/> </sequence> </sequence> </content>
Schema Declaration	element body { tei_att.global.attributes, tei_att.declaring.attributes, ( tei_model.global, ( tei_model.divTop, ( tei_model.global \| tei_model.divTop ) )?, ( tei_model.divGenLike, ( tei_model.global \| tei_model.divGenLike )* )?, ( ( tei_model.divLike, ( tei_model.global \| tei_model.divGenLike )* )+ \| ( tei_model.div1Like, ( tei_model.global \| tei_model.divGenLike )* )+ \| ( ( tei_model.common, tei_model.global* )+, ( ( tei_model.divLike, ( tei_model.global \| tei_model.divGenLike )* )+ \| ( tei_model.div1Like, ( tei_model.global \| tei_model.divGenLike )* )+ )? ) ), ( tei_model.divBottom, tei_model.global* )* ) }

TEI Conformance

La notion de TEI Conformance correspond à un ensemble de règles et de contraintes devant permettre l'échange et le traitement des fichiers dans un cadre commun. Ce n'est pas une mesure ou un jugement des mérites académiques d'un document. Il est défini par la TEI comme étant:

un XML bien formé
un XML valide par rapport à un schéma, qui est un dérivé des Guidelines TEI.
conforme au modèle abstrait de la TEI
une utilisation conforme des espaces de noms
une documentation par le biais d'un ODD, conforme aux attentes fixées par la TEI.

Cela signifie qu'il faut adhérer aux définitions des éléments TEI, afin de ne pas altérer leur dimension sémantique, et qu'il vaut mieux éviter d'élargir l'appréciation d'un élément de la TEI. Il est plutôt recommandé d'être plus restrictif, ou au moins équivalent, afin de ne pas basculer dans une modification "sale" (unclean modification) de la TEI. Cela ne veut pas dire que ce choix est intrinsèquement mauvais, ou qu'il n'est pas nécessaire, mais qu'il empêche la validation par le schéma de la TEI dans sa forme originelle.

NB: il y a aujourd'hui plus de 600 éléments disponibles dans le modèle TEI. Aucun projet ne les mobilise tous; c'est pourquoi le modèle théorique est souvent "réduit" aux seuls éléments nécessaires aux objectifs d'un projet. Cela peut aussi s'accompagner de la création d'éléments propres à un projet, lorsque la TEI n'offre pas de solution, ou que l'on ne les trouve pas satisfaisants. Un exemple: le projet Menota. Les éléments créés fonctionnent avec l'espace de nom me:

<me:all> pour encoder les allitérations dans un vers
<me:ass> pour encoder les changements de rythmes dans un vers
<me:textSpan/> pour encoder des structures qui se chevauchent
- @me:category pour qualifier le type de l'élément problématique par rapport à la structure. La liste des valeurs d'attributs est fermée.

C'est pourquoi un travail de modélisation est nécessaire lorsque l'on établit un modèle TEI pour un ou des corpus. La modélisation est une : « opération par laquelle on établit le modèle d'un système complexe, afin d'étudier plus commodément et de mesurer les effets sur ce système des variations de tel ou tel de ses éléments composants » Source: J. Giraud, P. Pamart, J. Riverain, Les nouveaux mots « dans le vent », Paris, France, 1974.

Penser son schéma

Fabriquer son schéma revient à établir une modélisation particulière du modèle TEI. Il doit être conforme à ce modèle de départ, tout en étant adapté à votre corpus et à ses objectifs. Nous synthétisons et suivons ici les grandes lignes et étapes données par Jean-Baptiste Camps.

Quelques éléments pour établir son modèle

définir des éléments en partant des sources et des informations qu'elles comportent
définir le contenu des documents, pour faciliter le travail d'encodage, assurer l'homogénéité et, ainsi, permettre les traitements ultérieurs
en cas de création de nouveaux éléments, utiliser des noms clairs aux définitions explicites
établir une documentation
Ce n'est pas seulement un modèle théorique et abstrait, il doit être confronté aux sources et évoluer en cas de besoin

Modifications possibles du modèle TEI lors de la création de son schéma

suppression d'éléments
changement de nom d'éléments (unclean modification)
modification d'un modèle de contenu
modification d'une liste d'attributs ou de valeurs d'attributs ou d’un type de contenu
modification de l'appartenance à une classe
ajout de nouveaux éléments