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 — The TEI Infrastructure
Members att.naming [att.personal [addName eventName forename genName name objectName orgName persName placeName roleName surname] affiliation author birth bloc climate collection country death district editor education event geogFeat geogName institution nationality occupation offset origPlace population pubPlace region repository residence rs settlement socecStatus state terrain trait] actor authority catDesc correspDesc date distributor docAuthor docTitle faith funder material meeting object objectType post principal publisher relation resp respStmt sponsor term time title unitDecl unitDef
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 customizaiton, for interchange.