Introduction

When describing metadata for digital images in TEI (Text Encoding Initiative), the facsimile element is used. Particularly in IIIF (International Image Interoperability Framework) compatible digital archives, it is important to properly describe references to manifests, canvases, and the Image API.

This article introduces how to define the constraints needed for facsimile descriptions as a schema using ODD (One Document Does it all).

Guidelines Followed

This ODD is based on the “Linking with IIIF Images” specification introduced in the Japanese TEI guidelines:

By creating data that conforms to this guideline, image display becomes possible in TEI Viewer for EAJ. The TEI Viewer can display TEI text and IIIF images in coordination, using information from facsimile elements to map text and images.

Design Goals

A schema was designed to meet the following requirements:

  1. Clarification of required information: Defining minimum necessary information such as image coordinates and identifiers as required attributes
  2. IIIF compatibility: Optionally describing references to manifests, canvases, and Image API
  3. Reusability: Sharable across multiple projects as an independent ODD file
  4. Viewer compatibility: Reliably recording information necessary for display in TEI Viewer for EAJ

Minimal Description Example

<f/afcas<cis/smusiirumlf<rieagflcraeseac>apemuh>eliAxcs=="s"0ah"mtetuAplssy=:="/"h/0te"txpalsmr:px/l=/e"e.5xo6ar0mg0p/"lieil.irofyr/=gm"/a4in0mi0af0ge"es/tx0.m0jl1s:.oitndi"=f>""p/1>">

Complete Description Example (Including IIIF References)

<f/afcas<cis/smusiirumlf<rieagflcraeseac>apemush>elaiAxmcs=e="Aus"0srah"=lmt"=etuh"Aplthssytt=:=pt"/"sph/0:ste"/:tx//pale/smrxe:pxax/l=ma/e"pme.5lpxo6elar0.emg0o.p/"roligreil/g.ircofyair/=nmgm"va/a4agin0semi0//af0p0ge"10es"1t.0.xt0jmi1slf.o:tnifi"duf>=l""lp1f"u>ll/0/default.jpg"

ODD Definition Explanation

1. facsimile Element

<e/l<<<<eedcc/a/lmelo<ct<aeesaneota/tmncstlnLt<<atet>seetitdd/tLnSFenmesDea<dtitpastentestdaDsSec>ntfcaatetpcsmt>m>ttaf>eioRoiRyat>cimdeddepRy>diefeefeepel==ne>fene"k"tr>trer=ek=ieye"ne"mp=pscyfal"lae=agasam"cecuceUtsereAReii"f"sLimn/a>"dif>ctaloemoter"oa"mdI.ameIpmti=Iooin"FidoOrnencemt=.cpae"ulnrcIrai"hnscf/ac=ee>nl""sgu1ted"u<"es/>smadagerxeseO=cfc">ecorupertns"c=>e"utnoboIuInIdFedm"a/n>ifest.</desc>

Key points:

  • Requires at least one surface element (minOccurs="1")
  • Sets sameAs attribute for IIIF manifest reference as optional

2. surface Element

<e/l<<<<eedcc/a/lmelo<ct<<<<<<aeesaneota/a/a/a/a/a/tmncstlnLt<at<<at<<at<<at<<at<<atet>seetitdttddttddttddttddttddtLnSIenmesDetDeatDeatDeatDeatDeatitpmstentesDestDestDestDestDestDsSea>ntfcefcaefcaefcaefcaefcaetpcgmt>m>f>tf>tf>tf>tf>tf>eeoRoiI>iUy>iUy>iLy>iLy>iRy>cideddDdppdppdopdopdep>dsefeeepeepeeweeweefeeu==ntne>ne>ne>ne>ne>nr"k"thtr<tr<tr<tr<tr<tfrer=a=-d=-d=-d=-d=ed=aeye"t"la"la"ra"ra"na"cp=pxuetuetlitlitsctsel"lmulfalfargargaaeau.agalnxtRytRxhRyhRmRrcrc:i"e"e"te"teeUefCeaeiqXfYfffARfao"p"dummmXmYsLcn/h>"eockockokok"ket>ildoedoedcedcete"acmyeoyeoyeoyeoymoyi"o=r==r==o==o=o=mndi"d""d""r""r"dI"osmedritritrdtrdteItdi=eeneeneeieeie=Ieecn"npaipaipnipni"Fi=oOrtltdltdladladrd"oceiaeaaeaataataecacrcpfctctcetcetpathdulie(ae(aeaealnaairae"r."r."(."(.av.nnscsenenrnrncapga=euquuquueuueuesoet""tsumsumsqmsqm"i"e1haieaieaueauen>"uegrrgrrgirgiruotiseeieeierierispenmai=dc=dc=ec=ecatrfagm")"")""d""d"gi"oxear<r<r)/r)/eo/rO=geee<>e<>=n>mc"eqdqdq/<q/<"a<acr"e/"e/"d/"d/ol/tues>sd>sd>ed>edp)dirqucacasasat<aos"r>t>tctct"/tn=>faa>a>a>da"attttetaucyyyysynneppppcpdbeeee>eo(>>>>>rurenefdqeeurdie"rn/ec>de)<t/odeIsIcI>Fcanvas.</desc>

Key points:

  • Makes xml:id and coordinate attributes (ulx, uly, lrx, lry) required (usage="req")
  • Requires at least one graphic element
  • Sets sameAs attribute for IIIF canvas reference as optional

3. graphic Element

<e/l<<<eedca/lmelt<<aeesata/a/tmncsLt<<at<<atet>sitddttddtLnSIesDeatDeatitpmstestDestDsSeafcaefcaetpcgmm>tf>tf>eeooiRy>iFy>cidddepdup>dreeefeeleee==ne>nl>nf""tr<t<terr=ed=Ud=ree"na"Ra"eppsctuLtgnllaeararcaamRloRaecceUe"fep.eeARffh""sLmtiU/>"kohkcR>tedee"Lmoyeyo==I=mtdi""I"ooemtrItd=aeeFeeI"gipi=IredlId"IeaamacFpftcathliaegaaIal."e.nmceppgaeouAoeg"(isPi"ernaIn>uetgtAsqeeePaur=orIgi""p"er/ot/o=e>pi>r"d<to<r)"n/ie.d>admqalaa"St)tg>pa.aeet<tcy/yfipdpifeeely>s>ec.t><h/edebsacs>eURLoftheIIIFImageAPI.</desc>

Key points:

  • Makes sameAs attribute required: always records the canonical URL of the image file
  • url attribute is optional: allows describing IIIF Image API URL with parameters (e.g., /full/full/0/default.jpg)

Design Philosophy of Attributes

Role of sameAs Attribute

The sameAs attribute is used to record the canonical identifier of a resource:

ElementContent of sameAs Attribute
facsimileIIIF manifest URL
surfaceIIIF canvas URL
graphicBase URL of image file (e.g., .tif)

Distinguishing from url Attribute

In graphic elements, sameAs and url can be used together:

  • sameAs: Canonical URL of the image (e.g., https://example.org/image/001.tif)
  • url: Full URL of the IIIF Image API (e.g., https://example.org/image/001.tif/full/full/0/default.jpg)

This allows separate management of image identification and actual access URLs.

Example Validation Results

When validation is performed with this schema, incomplete descriptions are detected with errors like the following:

eerrrroorr::eelleemmeenntt""sgurrafpahciec""mmiissssiinnggrreeqquuiirreeddaattttrriibbuuttees""slarmxe"A,s""lry","ulx"and"uly"

Usage with TEI Viewer for EAJ

TEI data conforming to this ODD can be displayed with images in TEI Viewer for EAJ. The viewer provides the following features:

  • Coordinated display of TEI text and IIIF images
  • Image switching via the facs attribute of pb elements
  • Identifying image regions using coordinate information from surface elements

By defining required attributes in the schema, it is guaranteed that information necessary for display in the viewer is reliably recorded.

Summary

Using TEI ODD, the following constraints were achieved for IIIF-compatible facsimile descriptions:

  1. Guaranteed required information: Prevents omission of coordinate information and image references
  2. Flexible extensibility: IIIF-related information is optional, allowing gradual adoption
  3. Reusability: Shareable across multiple projects as an independent ODD module
  4. Viewer compatibility: Guarantees display in TEI Viewer for EAJ

Schema design using ODD is an effective approach for quality management and standardization of XML data. By conforming to the Japanese TEI guidelines, interoperability with tools within the ecosystem is also ensured.