12.3.5. att.canonical

att.canonical provides attributes that can be used to associate a representation such as a name or title with canonical information about the object being named or referenced. [14.1.1. Linking Names and Their Referents]

Module tei — Specification

Members att.naming[att.personal[forename name orgName persName placeName surname] affiliation author editor education nationality occupation pubPlace residence socecStatus state trait] authority bibl biblStruct catDesc date faith principal publisher resp respStmt term title

Attributes

key

provides an externally-defined means of identifying the entity (or entities) being named, using a coded value of some kind.

Status	Optional
Datatype	teidata.text
`<author> <name key="Hugo, Victor (1802-1885)" ref="http://www.idref.fr/026927608">Victor Hugo</name> </author>`
Note	The value may be a unique identifier from a database, or any other externally-defined string identifying the referent. No particular syntax is proposed for the values of the key attribute, since its form will depend entirely on practice within a given project.

ref

(reference) provides an explicit means of locating a full definition or identity for the entity being named by means of one or more URIs.

Status	Optional
Datatype	1–∞ occurrences of teidata.pointer separated by whitespace
`<name ref="http://viaf.org/viaf/109557338" type="person">Seamus Heaney</name>`
Note	The value must point directly to one or more XML elements or other resources by means of one or more URIs, separated by whitespace. If more than one is supplied the implication is that the name identifies several distinct entities.

Example

In this contrived example, a canonical reference to the same organisation is provided in four different ways.

<author n="1">
 <name ref="http://nzetc.victoria.ac.nz/tm/scholarly/name-427308.html"
  type="organisation">New Zealand Parliament, Legislative Council</name>
</author>
  
<author n="2">
 <name ref="nzvn:427308"
  type="organisation">New Zealand Parliament, Legislative Council</name>
</author>
  
<author n="3">
 <name ref="./named_entities.xml#o427308"
  type="organisation">New Zealand Parliament, Legislative Council</name>
</author>
  

<author n="4">
 <name key="name-427308"
  type="organisation">New Zealand Parliament, Legislative Council</name>
</author>

The first presumes the availability of an internet connection and a processor that can resolve a URI (most can). The second requires, in addition, a <prefixDef> that declares how the nzvm prefix should be interpreted. The third does not require an internet connection, but does require that a file named named_entities.xml be in the same directory as the TEI document. The fourth requires that an entire external system for key resolution be available.

Note

The key attribute is more flexible and general-purpose, but its use in interchange requires that documentation about how the key is to be resolved be sent to the recipient of the TEI document. In contrast values of the ref attribute are resolved using the widely accepted protocols for a URI, and thus less documentation, if any, is likely required by the recipient in data interchange.

These guidelines provide no semantic basis or suggested precedence when both key and ref are provided. For this reason simultaneous use of both is not recommended unless documentation explaining the use is provided, probably in an ODD customization, for interchange.