EAD Application Guidelines for Version 1.0

Chapter 7: EAD Linking Elements

7.1. Introduction

Linking elements perform three functions in encoded finding aids:

7.1.1. The Structure of Links

In an SGML-based encoding scheme like EAD, linking elements and attributes are required in order to effect any link that the encoder wishes to establish. The link itself is really two things: (1) the declaration, through the use of a linking element, that a relationship exists between the information encoded in one element and that available someplace else; and (2) an address, or the name of a resource that can be resolved to an address, for the destination of the link being established, which is supplied as a value of an attribute in the linking element.

Designated elements within encoded documents or entire documents themselves can serve as resources in a link, either as sources or as destinations. When you establish a link by placing a linking element in an encoded finding aid, that element generally serves as the source resource for the link. Each linking element has a group of linking attributes that provide further information regarding the link. Some of these attributes provide addresses for the destination resource for the link, while others provide information about how the link is intended to behave when the document instance is output to some display mechanism. The functionality of various linking attributes will be discussed below in the context of the various EAD linking elements with which they can be used.

It is important to stress that software must interpret the values of linking attributes and stylesheet instructions to actually effect these linking capabilities. Version 1.0 of EAD was designed specifically to support linking as defined in the XLink and XPointer specifications currently in draft format. (108) However, there currently are no commercially available software packages that implement certain linking attributes available in EAD. The discussion in this chapter relates to the broad functionality of the various linking elements and attributes in EAD, and not to the specifics of how a particular delivery system will translate or implement these encoded links. The chapter does provide some recommendations regarding attributes that archivists should consider using at a minimum when establishing links in EAD-encoded finding aids.

7.1.2. Characteristics of Links

The following 15 elements in EAD can be used to establish links:

Thirteen manage links directly, while two (<daogrp> and <linkgrp>) are wrapper elements that consolidate multiple, related links. These 15 elements have several significant characteristics.

Conceptually, a link has four facets, each of which has only two or three possible values. Different linking elements possess different combinations of these facet values. In any given situation, the encoder of a finding aid will select the proper linking element based on these characteristics and on other considerations that will be described later in this chapter. These are the significant characteristics of links:

Destination locationInternal or External(See section
ExtentSimple, Locator or Extended(See section
Source locationInline or Out-of-line(See section
ContentsEmpty or With text(See section

Attributes play a very important part in linking elements. TARGET, HREF and ENTITYREF are used to provide destination addresses for links. ACTUATE, SHOW and BEHAVIOR work together to govern the way in which processing software presents links to end users. ROLE, TITLE, CONTENT-ROLE, CONTENT-TITLE and other attributes specific to EAD's linking elements provide additional specificity regarding the nature of links or the resources that participate in them. Destination Location
Links can be either internal or external to an encoded document instance. When encoding a finding aid you might use an internal link from an appropriate point within the Description of Subordinate Components <dsc> element to reference the text of an access restriction encoded at the collection level. Within the same finding aid, you might use an external link to provide a pointer to the encoded finding aid for a collection of related materials. You might also use an external link to provide a pointer to a digitized facsimile of a photograph or other item contained in the collection being described. Extent
All of the linking examples discussed in the previous paragraph are single-direction links that can be traversed only from source to destination, as illustrated in figure

An encoder can create a link to and from a destination by establishing two single-direction links that can be traversed in opposite directions, as illustrated in figure

The direction of link traversal in both figures is indicated by arrows. Some software may support the ability to traverse a link from source to destination and back to source without encoding two single-direction links for this purpose.

The focus of this linking discussion will be on simple links, since they are universally supported by SGML-aware software applications. Most of the links that an encoder creates in an EAD instance will be simple links. Simple links have these features:

All other types of links are considered extended links. The concept of extended links is currently being clarified and expanded in work on XLink, the linking component of XML, and will be discussed only briefly. EAD has one main category of linking elements that are always extended, the bundling linking elements <linkgrp> and <daogrp>, which will be discussed in greater detail in section 7.3.5 and section 7.3.6. They are considered extended links because they do not themselves contain a destination resource for the established link, but rather bundle multiple locator elements (<extrefloc>, <daoloc>) containing addresses for the link's multiple destinations. The attribute XLINK:FORM, which supplies the designation of each linking element as simple, extended or locator, is discussed in section 7.2.4. Source Location
An inline link is one in which the linking element in the encoded document participates as one of the resources of the link, usually as the source. An out-of-line link is one that does not participate as a resource in the link being established. This is a new and at this point in time a somewhat theoretical concept that is being developed as part of the XLink specification. Out-of-line links, when systems are developed to support them, will allow you to establish a link between two or more external documents that you do not have the capability of editing directly. (109) This might facilitate, for example, the development of annotation servers to manage "post-it" note commentaries for Web sites. One possible application of this technology for archival information servers could be to provide K-12 teachers with the capability to create a network of links between encoded finding aids-stored and managed externally to the finding aids themselves-that are geared specifically toward student assignments. The concept of out-of-line linking is introduced here so that readers of these Guidelines will have a passing familiarity with it as they encounter it in the XML literature, and so that they can understand the choices available for the value of the attribute INLINE (discussed in section 7.2.4). For all practical purposes though, current users of EAD should use the default value of "true" for the INLINE attribute, meaning that the link is inline. Contents
Sometimes linking elements are used only as pointers to other locations. No caption or explanation of the link is required. In other scenarios, some explanatory text regarding the link is required. Certain linking elements are designated for each of these situations. Those not intended to include explanatory or descriptive content are defined in the DTD as EMPTY (see section 6.3 for a discussion of empty elements). Often the choice of one element over another will depend on whether a textual description of some sort is required or not.

7.1.3. Linking Element Use

Table 7.1.3a lists the 15 linking elements available in EAD arranged according to the characteristics just described. (110)

Simple Links

Simple links are inline.

Extended Links

Extended links can either be inline or out-of-
These locator links must be bundled using <linkgrp> or <daogrp>.

Internal linksWith text<ref><refloc>
External linksWith text<archref>, <bibref>, <dao>(111) , <extref>, <title><daoloc>, <extrefloc>
Empty <extptr><extptrloc>
Table 7.1.3a. EAD linking elements categorized by significant characteristics. Since currently available software does not generally support the use of extended links, EAD implementers should consult with their systems expert prior to employing the linking elements shown in the shaded area.

As mentioned above, the use of any one of these elements(112) signals the establishment of a link between the information being encoded and information available somewhere else. That somewhere else may be within the same finding aid, on the same server, or on some other server available via the Internet.

The following discussion of various linking options will proceed from the simple to the complex. Additionally, it will first describe linking options that any SGML or XML system should be able to support and will then move to an abbreviated discussion of the more complex options that eventually will take advantage of the currently incomplete and unimplemented XLink and XPointer specifications in XML. It bears emphasis here that Version 1.0 of the EAD DTD was designed to support fully XML-compliant encoding when that specification is completely developed and when software is readily available to support its implementation. The degree to which a particular repository will want to take full advantage of many of the more complex linking capabilities in EAD is a decision that will need to be taken in consultation with persons possessing expertise in whatever local delivery system that repository chooses to use for its encoded finding aids. In the current environment, archivists are limited to the simpler linking options discussed below.

It should be noted that for the sake of clarity examples in section 7.2, section 7.3, and section 7.4 will only include the linking element attributes being discussed in each particular subsection. Section 7.6, the final section in this chapter, will include several examples of the use of optimally encoded linking elements.

7.2. Internal Linking

Internal linking provides end users with the ability to proceed through the information in an encoded finding aid in a nonlinear way. It also gives you the ability to make explicit connections between related information that appears in different parts of a finding aid. The following sections provide information on the usage of the elements and attributes available in EAD to facilitate internal linking.

7.2.1. Pointer <ptr> and Reference <ref> with the TARGET Attribute

Internal linking within a document, the simplest form of EAD linking, is accomplished through use of the TARGET attribute. This attribute, available on only four elements (<ptr>, <ptrloc>, <ref> and <refloc>), allows you to establish a link to a destination somewhere else within the same finding aid. A TARGET attribute must have an "IDREF" value, which means that it must correspond exactly to a value declared as an ID attribute elsewhere in the same encoded document. This one-to-one correspondence is checked by parsing software while validating the document instance; if such correspondence does not exist, the software will report a validation error.

The ID attribute plays a critical role in internal links. The TARGET attribute on the linking element used to establish a source for an internal link contains the value of the ID attribute for the destination element. Virtually all EAD elements have an ID attribute and therefore may be the target of an internal link. As noted in the general discussion of attributes in section 6.4, the ID attribute has a value designation of "ID", which requires that its value be unique within a particular encoded document instance. Any element containing text that an encoder wishes to make the target of an internal link must be given a unique value using the ID attribute within that element. Once a unique value is assigned, this encoded information can serve as a link target.

To create an internal link, you must do the following:

In figure 7.2.1a, the text of an access restriction note has been encoded at the collection level, and a unique ID value has been established for that note. In both figures below, some elements have been omitted in order to focus on the link-related points being made.

In figure 7.2.1b, a linking element has been used to establish a relationship between access restriction information within the series-level description and the collection-level note illustrated in figure 7.2.1a. This encoding eliminates the need for repetition at various levels of description of the access restriction information.

In order to alert the end user about the availability of a link, the use of the empty element <ptr> might result in the insertion of a link indicator icon in place of <ptr> when this encoded document is displayed. How such an icon is displayed will be determined by the system or display application (a client browser, a stylesheet, or an SGML server).

Alternatively, the link in figure 7.2.1b could have been declared using <ref>, which must contain text or other elements, as shown in the following example with a reencoded excerpt from figure 7.2.1b. The display to an end user would most likely involve highlighting the text contained within the <ref> element to indicate the presence of the link, in the manner of an HTML browser.

	<arrangement><p>The bulk of the contents of the series
	arrived at the repository in chronological order and this arrangement
	has been retained. <ref target="restrict1">The single exception
	is a file of student recommendations on which access restrictions have
	been imposed.</ref> These folders have been temporarily removed
	to a restricted box in the collection.</p></arrangement>

7.2.2. The Nonlinking Bundling Element Pointer Group <ptrgrp>

In some cases you may wish to create multiple, internal, single-direction links from a particular location in the encoded document; this requires that the pointer elements be bundled. EAD includes provisions for both a bundling element for internal links that can be used anywhere in the finding aid (see section 7.2.3), and an element that can be used to bundle internal links only from within the Index Entry <indexentry> tag. Bundling together a group of simple, internal links within an index entry requires the use of a nonlinking element, Pointer Group <ptrgrp>. This might be used in order to provide a name index for a correspondence series that is arranged chronologically. In figure 7.2.2a an encoded container list includes a unique ID value for each <unittitle>. In figure 7.2.2b <ptrgrp> is used within an index of correspondents to bundle multiple internal simple links to the various folders that contain items from each indexed correspondent. The decision regarding which linking element to use in this case would be determined by the need to include the text of the index entry as part of the link indicator in the resulting display (in this case, use <ref>), or not to include the text (in this case, use <ptr>).

		<c02 level="file"><did>
		<unittitle id="corresp197306"><unitdate>
		June-December 1973</unitdate></unittitle>
		<c02 level="file"><did>
		<unittitle id="corresp1974"><unitdate>
		1974</unitdate> </unittitle>
		<c02 level="file"><did>
		<unittitle id="corresp197501"><unitdate>
		January-August 1975</unitdate></unittitle>

	Figure 7.2.2a.  Establishing unique ID values for
			several elements.

		<head>Correspondence Index</head>
		[other possible elements and text ...]
		<indexentry><persname>Doe, Jane S.: </persname>
		<ref target="corresp197306">24 August 1973
		<ref target="corresp1974">28 February and
		16 July 1974</ref>
		<ref target="corresp197501">15 March 1975
		[other possible elements and text ...]

	Figure 7.2.2b. Using a linking attribute to establish a
			link to the ID attribute value encoded in Figure 7.2.2a.

7.2.3. Linking Group <linkgrp> as a Bundling Element for Pointer Location <ptrloc> and Reference Location <refloc>

Outside of the <indexentry> tag, internal links also can be bundled using the Linking Group <linkgrp> element.(113) The linking elements <refloc> and <ptrloc> must be used with <linkgrp> instead of <ref> and <ptr>. Another difference is that <linkgrp>, unlike <ptrgrp>, is a linking element. The link created is considered an extended link. Unlike the example in figure 7.2.2b, in which <ptrgrp> bundles a group of independent simple links, <linkgrp> conceptually creates a single link with the potential for multiple source and destination resources by bundling a group of elements (<ptrloc> or <refloc>) that serve only as locators, providing addresses for the extended link's resources. The <linkgrp> element is used with <ptrloc> and <refloc> to create extended internal links to other information contained in the same encoded finding aid.

Generally the use of <linkgrp> should be reserved for links that themselves have some specific element of commonality, where bundling would enhance the ability of the link destinations to function together. The primary usage of <linkgrp> will likely be for bundling external links (see section 7.3.5). Currently available software may not be capable of implementing <linkgrp> for display to end users, nor are XLink developments, including the concept of extended links, finalized. Archivists interested in the potential use of extended links in their finding aids should follow XLink developments.(114)

7.2.4. The XLINK:FORM and INLINE Attributes

EAD defines two linking attributes that you will not need to include in your document instances at this time. While they may not currently be useful, however, these attributes do introduce concepts that archivists who are interested in XML developments may find helpful. Both of these attributes could be used in either internal or external linking, so this discussion is applicable both here and below in section 7.3 on external links.

The terms "simple," "extended" and "locator" all are values for the attribute XLINK:FORM, which is conditionally available on all EAD linking elements and will in the future allow software to readily recognize a specific link as being of a type defined in the XLink specification. This attribute is specific to XLink functionality in the EAD DTD, and it is characterized as conditionally available because, in order to be used, XML functionality must be "turned on" in the DTD file ead.dtd. In order to do so, you must edit the values of two parameter entity declarations in section "XLINK INCLUSION/EXCLUSION" in the file ead.dtd. These values are encoded as follows when this file is obtained from the official EAD Web site hosted by the Library of Congress:

	<!ENTITY % xlink          'IGNORE'       >
	<!ENTITY % noxlink        'INCLUDE'      >

This means that the XLink functionality is "turned off," which is the default for the EAD DTD because most SGML software cannot handle the colon (:) in the attribute name XLINK:FORM. In order to enable XLink functionality when using XML software in the future, you must change these parameter entity declarations in your local copy of the ead.dtd file so that they appear as follows:

	<!ENTITY % xlink          'INCLUDE'      >
	<!ENTITY % noxlink        'IGNORE'       >

The value of this attribute is declared as FIXED and is set by the DTD for each linking element. Even when the XLink functionality remains "turned off," familiarity with the role that each linking element plays as designated by this attribute can help encoders understand the proper way to use these linking elements in various situations. Table 7.2.4a categorizes the 15 EAD linking elements by the fixed value of their XLINK:FORM attribute.

xlink:form="simple"<archref>, <bibref>, <dao>, <extptr>,
<extref>, <ptr>, <ref>, <title>
xlink:form="extended"<daogrp>, <linkgrp>
xlink:form="locator"<daoloc>, <extptrloc>, <extrefloc>, <ptrloc>,
Table 7.2.4a. Fixed XLINK:FORM attribute values for EAD linking elements.

The attribute INLINE is not specific to XLink functionality, and so it is not turned "on" or "off" in the file ead.dtd. INLINE has a value of either "true" or "false," with the default value being "true," meaning that a link is inline. Unless an encoder wishes to change the value of this attribute to "false" to indicate that a link is out-of-line, the attribute need not be used in encoding (see section for a discussion of inline and out-of-line linking).

The attribute INLINE is available on all simple and extended linking elements as categorized in table 7.2.4a. In extended links, the INLINE attribute, if used, would appear on the bundling element, since INLINE is not an attribute option on individual locator elements. As stated previously, current EAD users need not explicitly encode this attribute. The default value of "true" is recommended until the XLink specification and software that will support out-of-line linking is closer to completion.

7.2.5. The PARENT Attribute on the Container <container> and Physical Location <physloc> Elements

The PARENT attribute is a special case that is only available in the Container <container> and Physical Location <physloc> elements. The PARENT attribute is different from EAD's other linking elements, however, in that no link traversal is involved from a user's perspective. It is intended to make accessible to software information about a "parent" container without having to encode it repeatedly. This attribute is provided so that the ID attribute can be used to create a shortcut when encoding, for example, box and folder information using <container>.

As noted in section, archivists may wish to consider encoding the container and/or folder information for each descriptive component (<c> or <c0x>) below the subseries level, in other words for those hierarchical descriptive components for which box and folder numbers are frequently given in print-based finding aids. A computer processing an encoded document cannot intuit the same meaning from the layout of a container list that a human being processing the same information can. Encoding containment information for each component will insure that container list data will be useful computationally as more sophisticated systems develop in the future for the manipulation and repackaging of data from archival finding aids. Not encoding this information for each component may make it difficult for data to be reused in such systems as they develop.

For example, a person would readily understand, in the following excerpt from a container list, that all three folders are in Box 12:

	Box	Folder	Contents
	12	1	Breakdance, 1989-1991
		2	Fosse, Bob, 1980-1984
		3	Jitterbug, 1938-1942

The problem arises when this same container list is encoded in EAD, as shown in figure 7.2.5a:

		<c02 level="file"><did>
		<container type="box">12</container>
		<container type="folder">1></container>
		<unittitle>Breakdance, <unitdate type="inclusive">
		<c02 level="file"><did>
		<container type="folder">2</container>
		<unittitle><persname>Fosse, Bob</persname>,
		<unitdate type="inclusive">1980-1984</unitdate>
		<c02 level="file"><did>
		<container type="folder">3</container>
		<unittitle>Jitterbug, <unitdate type="inclusive">

	Figure 7.2.5a.  Encoding of container information that may be
			problematic for computer processing and repackaging of
			the data.

To a computer processing this file, the descriptive unit "Fosse, Bob" is housed in a folder but not in a box. This is because the closing of the </c02> for the preceding descriptive unit "Breakdance" effectively cuts off the information about Box 12 for use in the processing of succeeding <c02> components. This may not cause a problem if EAD encoding is used only for generating a linear online finding aid. It could, however, become problematic in the future when application software attempts to extract descriptive component information from an encoded finding aid. This might be required in order to present an end user, as the result of a search, with a hit list of folder-level information across multiple collections and multiple repositories. Such a scenario is currently possible for repositories or consortia with access to a good programmer and an SGML-aware search engine. Even in the linear display of finding aids, however, the encoding in the above example has the potential to generate a display that would force the end user constantly to scroll up and down to find the relevant box number for a particular folder, especially in cases in which a box contains a lot of folders.

The PARENT attribute makes it possible, if you are using a delivery system that is technically capable of supporting its use, to drop the <container type="Box"> encoding from all but the first component that falls within each new box and still provide the computer with the necessary information to process unambiguously the containment information for each descriptive component. Figure 7.2.5b is a reencoding of figure 7.2.5a, demonstrating use of the PARENT attribute:

		 <c02 level="file"><did>
		<container id="box12" type="box">12</container>
		<container type="folder">1</container>
		<unittitle>Breakdance, <unitdate type="inclusive">1989-1991
		<c02 level="file"><did>
		<container parent="box12" type="folder">2</container>
		<unittitle><persname>Fosse, Bob</persname>,
		<unitdate type="inclusive">1980-1984</unitdate></unittitle>
		<c02 level="file"><did>
		<container parent="box12" type="folder">3</container>
		<unittitle>Jitterbug, <unitdate type="inclusive">1938-1942

	Figure 7.2.5b.  Using the PARENT attribute to establish
			containment relationships unambiguously.

The PARENT attribute is declared in the EAD DTD with a value of IDREF, the same as the attribute TARGET. Figure 7.2.5b illustrates declaration of a value for an ID attribute on the <container> tag for the first instance of a new box, which can then be referenced using the PARENT attribute on the <container> tag for each successive folder contained within that box. Software processing a document thus encoded would now have access to the box information for every descriptive component in the box. Currently available commercial application software does not have the capability of utilizing the PARENT attribute, but repositories with in-house SGML programming expertise may be able to take advantage of this attribute to avoid repetitive tagging of containment information.

For delivery systems that cannot support the use of the PARENT attribute but that can suppress the delivery of information encoded with the AUDIENCE attribute set to "internal," an alternative encoding of figure 7.2.5a is provided in figure 7.2.5c. This approach supplies the containment information for each descriptive component and does not utilize the PARENT attribute; by using the AUDIENCE attribute, a stylesheet could be used to create a linear finding aid display that masks repetitious box numbers from the end user.

		 <c02 level="file"><did>
		<container type="box">12</container>
		<container type="folder">1</container>
		<unittitle>Breakdance, <unitdate type="inclusive">
		<c02 level="file"><did>
		<container type="box" audience="internal">12</container>
		<container type="folder">2</container>
		<unittitle><persname>Fosse, Bob</persname>,
		<unitdate type="inclusive">1980-1984</unitdate>
		<c02 level="file"><did>
		<container type="box" audience="internal">12</container>
		<container type="folder">3</container>
		<unittitle>Jitterbug, <unitdate type="inclusive">1938-1942

	Figure 7.2.5c.  Using the AUDIENCE attribute to mask repetitive box
			information included to facilitate computer processing.


Main Menu


  1. Further information on XLink and XPointer, the linking and addressing specifications that are being developed concurrently with XML, is on the World Wide Web Consortium web site, available at: <http://www.w3.org/TR/WD-xlink> for XLink and <http://www.w3.org/TR/WD-xptr> for XPointer.

  2. Charles Goldfarb and Paul Prescod, The XML Handbook (Upper Saddle River, N.J.: Prentice Hall, 1998), 502-505.

  3. The list in figure 9 on page 12 of the EAD Tag Library, Version 1.0 contains two errors. It mistakenly identifies <ptrgrp> as a fifteenth EAD linking element. In fact, <ptrgrp> serves as a bundling element for other linking elements but lacks the necessary attributes to function in the same way as the other elements included in the list. Also, the list in figure 9 omits <title>, which does function as a linking element in EAD.

  4. Note that <dao> is often used empty but may include <daodesc> if the context needed for a link is not provided by other elements. The <dao> element is not technically an empty element because it is not defined as such in the EAD DTD.

  5. With the exception of <archref>, <bibref>, and <title>, as noted in section 7.3.3.

  6. The description of <linkgrp> on page 172 of the Encoded Archival Description Tag Library, Version 1.0 states that this element can only be used "to enable a set of multidirectional, out-of-line links." Please note that <linkgrp> also can in fact be used to bundle inline links, both external and internal.

  7. Current information regarding XLink development by the World Wide Web Consortium is available at: <http://www.w3.org/TR/WD-xlink>.

Table of Contents
Home Page Preface Acknowledgments How to Use
This Manual
Setting EAD
in Context
Creating Finding
Aids in EAD
Authoring EAD
Publishing EAD
EAD Linking

Go to:

Copyright Society of American Archivists, 1999.
All Rights Reserved.

[VIEW OF LC DOME] The Library of Congress

Library of Congress Help Desk (11/01/00)