13Linking Data

This chapter describes the use of elements in MEI for linking and referencing. This includes the elements, models, and attributes that are part of the 'MEI.ptrref' module. This module contains declarations, techniques and approaches to establish references within a single MEI document, or to link out from one MEI document to another or to other external sources. This chapter also addresses possibilities to link into an MEI document from external sources which makes MEI highly interoperable and serviceable in the context of Linked (Open) Data approaches.

An element is a ‘link’ when it has an attribute whose value is a reference to the ID of one or more other elements (cross-reference). These link elements indicate an association between themselves (or one of their ancestors) and one or more other entities, either inside the same document or elsewhere. An association between two elements in the same document is said to be an ‘internal’ link, while an association that involves an entity outside the current document is called an ‘external’ link. However, either of the elements discussed in the following section can be used for either purpose.

13.1.1General Relationships Between Elements

MEI offers several attributes in the att.linking class for the description of basic relationships:

@
copyof (att.linking)
Points to an element of which the current element is a copy.
@
sameas (att.linking)
Points to an element that is the same as the current element but is not a literal copy of the current element.
@
corresp (att.linking)
Used to point to other elements that correspond to this one in a generic fashion.
@
next (att.linking)
Used to point to the next event(s) in a user-defined collection.
@
prev (att.linking)
Points to the previous event(s) in a user-defined collection.
@
precedes (att.linking)
Points to one or more events in a user-defined collection that are known to be successors of the current element.
@
follows (att.linking)
points to one or more events in a user-defined collection that are known to be predecessors of the current element.
@
synch (att.linking)
Points to elements that are synchronous with the current element.

The att.alignment class contains an attribute for describing temporal relationships:

@
Indicates the point of occurrence of this feature along a time line. Its value must be the ID of a when element elsewhere in the document.

The att.dataPointing class provides an attribute for pointing from the header into the music content:

@
Used to link metadata elements to one or more data-containing elements.

To reference images, the att.facsimile class provides an attribute for pointing to surface and zone elements:

@
Points to one or more images, portions of an image, or surfaces which correspond to the current element.

These attributes accommodate the encoding of linkages between the element carrying the attribute and one or more other elements. All of them use URIs to establish the connection. While the examples below illustrate relationships between musical events, the use of the aforementioned attributes is not restricted to musical events. On the contrary, these attributes can be used to capture information about relations between any elements.

Using the attributes above makes it possible to create relationships between events, which are often widely-spaced in both encoded order and time. The attributes allow a large number of connections, enhancing the informational content, and therefore the potential usefulness, of the encoding.

The copyof attribute points to an element of which the current element is a copy. It can be used to repeat a note, for example, without encoding the whole note element again. The copy is a ‘deep’ one; that is, the copyof attribute copies all attributes and child elements which belong to the copied element, such as the dur and oct attributes of a copied note. The value of the copyof attribute must be a URI, which usually refers to an element in the current document. The following example demonstrates use of the copyof attribute:

<section>
<measure n="1">
<staff n="1">
<layer>
<note xml:id="analysis.note1_1" dur="4" oct="4" pname="g"/>
</layer>
</staff>
</measure>
<measure n="2">
<staff n="1">
<layer>
<note copyof="#analysis.note1_1"/>
</layer>
</staff>
</measure>
</section>
Listing 420.

In this example, the note in the second measure has exactly the same characteristics as the note in the first measure.

Using copyof is not limited to copying events. The copyof attribute can also be used to copy an entire measure or staff. When there are many repeated features, the use of the copyof greatly reduces encoding effort. The image and the following encoding of the beginning of Schubert’s Erlkönig illustrates the benefit of using the copyof attribute.

example
Figure 128. First measure of Schubert’s Erlkönig
<measure>
<staff n="1">
<layer>
<tuplet num="3" num.visible="true" xml:id="analysis.tup1">
<chord dur="8">
<note oct="3" pname="g"/>
<note oct="4" pname="g"/>
</chord>
<chord dur="8">
<note oct="3" pname="g"/>
<note oct="4" pname="g"/>
</chord>
<chord dur="8">
<note oct="3" pname="g"/>
<note oct="4" pname="g"/>
</chord>
</tuplet>
<tuplet copyof="#analysis.tup1" xml:id="analysis.tup2"/>
<tuplet copyof="#analysis.tup1" xml:id="analysis.tup3"/>
<tuplet copyof="#analysis.tup1" xml:id="analysis.tup4"/>
</layer>
</staff>
</measure>
Listing 421.

This example can be reduced further by using copyof inside the initial tuplet to represent the repeated chords:

<measure>
<staff n="1">
<layer>
<mRest/>
</layer>
</staff>
<staff n="2">
<layer>
<tuplet num="3" num.visible="true" xml:id="analysis.tup5">
<chord dur="8" xml:id="analysis.t1c1">
<note oct="3" pname="g"/>
<note oct="4" pname="g"/>
</chord>
<chord copyof="#analysis.t1c1"/>
<chord copyof="#analysis.t1c1"/>
</tuplet>
<tuplet copyof="#analysis.tup5" xml:id="analysis.tup6"/>
<tuplet copyof="#analysis.tup5" xml:id="analysis.tup7"/>
<tuplet copyof="#analysis.tup5" xml:id="analysis.tup8"/>
</layer>
</staff>
<staff n="3">
<layer>
<mRest/>
</layer>
</staff>
</measure>
Listing 422.

While copyof signifies a duplicate copy of an element, the sameas indicates that the current element represents exactly the same entity as the one referenced in sameas. Use of sameas is used for describing the same entity from multiple perspectives, e.g., the same event in two layers.

While copyof and sameas have defined semantics, the corresp may be used to create user-defined relationships between elements. The example below demonstrates the encoding of a relationship between the third note and the fermata, even though the fermata is not placed directly above the note.

<measure n="1" right="end">
<staff n="1">
<layer n="1">
<note dur="4" oct="4" pname="c" xml:id="analysis.note1"/>
<note dur="4" oct="4" pname="d" xml:id="analysis.note2"/>
<note dur="2" oct="4" pname="e" xml:id="analysis.note3"/>
</layer>
</staff>
<fermata corresp="#analysis.note3" place="above" tstamp="4.75"/>
</measure>
Listing 423.

The corresp attribute only marks the correspondence between the current element and one or more other entities. To describe the nature of the correspondence, one must use annot.

One possible usage of corresp is to link related editorial markup. Because of the hierarchical nature of XML it may be necessary to split related editorial markup into multiple elements. In the following example, corresp is used to encode the relationship between those elements.

example
<mei meiversion="5.1-dev">
<meiHead>
<fileDesc>
<titleStmt>
<title>Example of attribute corresp</title>
</titleStmt>
<pubStmt>
<date isodate="2024">2024</date>
<respStmt>
<corpName>Music Encoding Initiative (MEI)</corpName>
</respStmt>
<availability>
<useRestrict label="license" auth="https://spdx.org/licenses/" codedval="ECL-2.0">
<p>Educational Community License v2.0</p>
</useRestrict>
</availability>
</pubStmt>
<seriesStmt>
<title>MEI guidelines examples</title>
</seriesStmt>
<notesStmt>
<annot>Usage of attribute corresp with editorial markup.</annot>
</notesStmt>
</fileDesc>
</meiHead>
<music>
<body>
<mdiv>
<score xml:id="score-1286820719">
<scoreDef xml:id="scoredef-1058976644" key.mode="major" keysig="1s" meter.count="6" meter.unit="8">
<staffGrp xml:id="staffgrp-0664100862" bar.thru="true">
<staffDef xml:id="staffdef-1106436456" n="1" lines="5" clef.shape="F" clef.line="4">
<instrDef xml:id="instrdef-0137914882" midi.channel="0" midi.instrnum="0" midi.volume="68.00%"/>
</staffDef>
</staffGrp>
</scoreDef>
<section xml:id="Tema">
<measure xml:id="measure-2058315290" n="1">
<staff xml:id="staff-0363750297" n="1">
<layer xml:id="layer-1609584463" n="1">
<note xml:id="note-0434568382" dur="8" oct="3" pname="g" stem.dir="down"/>
<unclear xml:id="uu01ius1" corresp="#uvvet6x2">
<note xml:id="note-1576381641" dur="4" oct="4" pname="d" stem.dir="down"/>
</unclear>
<note xml:id="note-0740487248" dur="8" oct="3" pname="a" stem.dir="down"/>
<note xml:id="note-2110615453" dur="4" oct="4" pname="d" stem.dir="down"/>
</layer>
</staff>
<slur xml:id="slur-0198912827" startid="#note-0434568382" endid="#note-1576381641" curvedir="above"/>
<unclear xml:id="uvvet6x2" corresp="#uu01ius1">
<dynam xml:id="dynam-1643328657" place="below" staff="1" tstamp="2.000000" vgrp="40">sf</dynam>
</unclear>
<slur xml:id="slur-0701442771" startid="#note-0740487248" endid="#note-2110615453" curvedir="above"/>
<dynam xml:id="dynam-1610913814" place="below" staff="1" tstamp="5.000000" vgrp="40">sf</dynam>
</measure>
</section>
</score>
</mdiv>
</body>
</music>
</mei>
Listing 424.
<measure n="1">
<staff n="1">
<layer n="1">
<note xml:id="note-0000000434568382" dur="8" oct="3" pname="g" stem.dir="down"/>
<unclear xml:id="uu01ius1" corresp="#uvvet6x2">
<note xml:id="note-0000001576381641" dur="4" oct="4" pname="d" stem.dir="down"/>
</unclear>
<note xml:id="note-0000000740487248" dur="8" oct="3" pname="a" stem.dir="down"/>
<note xml:id="note-0000002110615453" dur="4" oct="4" pname="d" stem.dir="down"/>
</layer>
</staff>
<slur startid="#note-0000000434568382" endid="#note-0000001576381641" curvedir="above"/>
<unclear xml:id="uvvet6x2" corresp="#uu01ius1">
<dynam place="below" staff="1">sf</dynam>
</unclear>
<slur startid="#note-0000000740487248" endid="#note-0000002110615453" curvedir="above"/>
<dynam place="below" staff="1">sf</dynam>
</measure>
Listing 425.

The next and prev attributes point to elements which follow or precede the current element in some fashion other than that indicated by encoding order. The use of these attributes helps to avoid confusion in the sequence of events, for example, in voice leading across layers or staves, when the encoding reflects the physical arrangement of voices. In the second measure of the following example, the target of the next attribute occurs after the pointing element in time, but before it in encoding order:

example
Figure 129. Bach Chorale, Ach Gott, vom Himmel sieh' darein, m. 6-7
<measure n="6" xml:id="analysis.m_sc_62">
<staff n="1">
<layer n="1">
<note dur="4" oct="4" pname="g" xml:id="analysis.n_sc_63_3"/>
<note dur="4" oct="4" pname="a" xml:id="analysis.n_sc_65_3"/>
<note dur="4" fermata="above" oct="4" pname="b" xml:id="analysis.n_sc_67_3"/>
<note dur="4" oct="4" pname="g" xml:id="analysis.n_sc_68_3"/>
</layer>
<layer n="2">
<beam>
<note dur="8" oct="4" pname="e" xml:id="analysis.n_sc_63_2"/>
<note dur="8" oct="4" pname="g" xml:id="analysis.n_sc_64_2"/>
</beam>
<beam>
<note dur="8" oct="4" pname="f" xml:id="analysis.n_sc_65_2"/>
<note dur="8" oct="4" pname="e" xml:id="analysis.n_sc_66_2"/>
</beam>
<note accid="s" dur="4" next="#analysis.n_sc_68_2" oct="4" pname="d" xml:id="analysis.n_sc_67_2"/>
<beam>
<note dur="8" oct="4" pname="e" xml:id="analysis.n_sc_68_1"/>
<note accid="n" dur="8" oct="4" pname="d" xml:id="analysis.n_sc_69_1"/>
</beam>
</layer>
</staff>
<staff n="2">
<layer n="1">
<note dur="4" oct="3" pname="b" xml:id="analysis.n_sc_63_1"/>
<note dur="4" oct="4" pname="c" xml:id="analysis.n_sc_65_1"/>
<note dur="4" oct="3" pname="f" xml:id="analysis.n_sc_67_1"/>
<note dur="4" oct="3" pname="b" xml:id="analysis.n_sc_68_2"/>
</layer>
<layer n="1">
<beam>
<note dur="8" oct="3" pname="e" xml:id="n_sc_63_0"/>
<note dur="8" oct="3" pname="d" xml:id="n_sc_64_0"/>
</beam>
<note dur="4" oct="3" pname="c" xml:id="n_sc_65_0"/>
<note dur="4" fermata="below" oct="2" pname="b" xml:id="n_sc_67_0"/>
<note dur="4" oct="3" pname="e" xml:id="n_sc_68_0"/>
</layer>
</staff>
</measure>
<measure n="7" xml:id="m_sc_70">
<staff n="1">
<layer n="1">
<beam>
<note dur="8" oct="4" pname="a" xml:id="analysis.n_sc_71_3"/>
<note dur="8" oct="4" pname="b" xml:id="analysis.n_sc_72_3"/>
</beam>
<note dur="4" oct="5" pname="c" xml:id="analysis.n_sc_73_3"/>
<note dur="4" oct="4" pname="b" xml:id="analysis.n_sc_75_3"/>
<beam>
<note dur="8" oct="5" pname="c" xml:id="analysis.n_sc_76_3"/>
<note dur="8" oct="4" pname="b" xml:id="analysis.n_sc_77_3"/>
</beam>
</layer>
<layer n="2">
<space dur="4"/>
<note dur="4" oct="4" pname="a" xml:id="analysis.n_sc_73_2"/>
<note accid="s" dur="4" oct="4" pname="g" xml:id="analysis.n_sc_75_2"/>
<note dur="4" oct="4" pname="a" xml:id="analysis.n_sc_76_2"/>
</layer>
<layer n="3">
<beam>
<note dur="8" oct="4" pname="c" xml:id="analysis.n_sc_71_1"/>
<note dur="8" oct="4" pname="d" xml:id="analysis.n_sc_72_1"/>
</beam>
<note dur="4" oct="4" pname="e" xml:id="analysis.n_sc_73_1"/>
<note dur="4" oct="4" pname="e" xml:id="analysis.n_sc_75_1"/>
<beam>
<note dur="8" oct="4" pname="e" xml:id="analysis.n_sc_76_1"/>
<note dur="8" oct="4" pname="d" xml:id="analysis.n_sc_77_1"/>
</beam>
</layer>
</staff>
<staff n="2">
<layer n="1">
<note dur="4" next="#analysis.n_sc_73_2" oct="3" pname="a" xml:id="analysis.n_sc_71_2"/>
</layer>
<layer n="2">
<note accid="n" dur="4" oct="3" pname="f" xml:id="n_sc_71_0"/>
<beam>
<note dur="8" oct="3" pname="c" xml:id="n_sc_73_0"/>
<note dur="8" oct="3" pname="d" xml:id="n_sc_74_0"/>
</beam>
<note dur="4" oct="3" pname="e" xml:id="n_sc_75_0"/>
<beam>
<note dur="8" oct="2" pname="a" xml:id="n_sc_76_0"/>
<note dur="8" oct="2" pname="b" xml:id="n_sc_77_0"/>
</beam>
</layer>
</staff>
</measure>
Listing 426.

This attribute may also be useful to clarify a sequence of entities which occurs across some form of interruption, in this case, notes before and after a system or page break where there is no custos or direct in the source:

<measure n="1">
<staff n="1">
<layer>
<note dur="4" next="#analysis.m1s1e2" oct="4" pname="f" stem.dir="up" xml:id="analysis.m1s1e1"/>
<pb/>
<note dur="8" next="#analysis.m1s1e3" oct="3" pname="b" prev="#analysis.m1s1e1" stem.dir="up" xml:id="analysis.m1s1e2"/>
<note dur="8" oct="4" pname="c" prev="#analysis.m1s1e2" stem.dir="up" xml:id="analysis.m1s1e3"/>
</layer>
</staff>
</measure>
Listing 427.

A one-to-many relationship between the current element and the entities being referred to can be expressed by using a list of space-separated URIs in corresp.

The synch attribute points to an element that is synchronous with; that is, begins at the same moment in time, as the current element. It is useful when the encoding order differs from the order in which entities occur in time.

The when attribute may be used to indicate the point of occurrence of the feature bearing this attribute along a time line. Its value must be the ID of a when element. For more detailed information regarding the use of when, please see 12.2 Performances.

13.2Linking from MEI

This section describes techniques and approaches to establish references within a single MEI document, or to link out from one MEI document to another or to other external sources.

13.2.1Pointers and References

The link elements discussed in this section are the ptr and the ref elements which are declared in the MEI.ptrref module.

Defines a traversible pointer to another location, using only attributes to describe the destination.
Defines a traversible reference to another location. May contain text and sub-elements that describe the destination.

The ptr element is a traversible pointer to another location. It is an empty linking element that uses only attributes to describe its link destination. It cannot contain text or sub-elements to describe the referenced object. The next example shows the use of the ptr element to target a certain identifier (here e.g., a page number, or more precisely, page break elements, pb, bearing these identifiers) from within a list of item descriptions:

<list>
<li>
<!-- item description -->
<ptr target="#p123"/>
</li>
<li>
<!-- item description -->
<ptr target="#p124"/>
</li>
</list>
Listing 428.

The ref element defines a traversible reference to another location. While ptr cannot contain other markup, the ref element can include text or sub-elements that further specify the link destination:

<repository>
<ref target="http://path.to.target/repo1.xml">
<title></title>
<address>
<addrLine></addrLine>
</address>
<identifier></identifier>
</ref>
</repository>
Listing 429.

13.2.2Specifying Link Elements

The ptr and ref elements share a set of common attributes that are inherited from the att.pointing class (a more detailed explanation is provided below):

@
target (att.pointing)
Identifies passive participants in a relationship; that is, the entities pointed "to".
@
targettype (att.pointing)
Characterization of target resource(s) using any convenient classification scheme or typology.
@
xlink:actuate (att.pointing)
Defines whether a link occurs automatically or must be requested by the user.
@
xlink:show (att.pointing)
Defines how a remote resource is rendered.
@
xlink:role (att.pointing)
Characterization of the relationship between resources. The value of the role attribute must be a URI.

In addition to the attributes in the att.pointing class, the mimetype attribute from the att.internetMedia class is also available on ptr and ref (a more detailed explanation is provided below):

@
mimetype (att.internetMedia)
Specifies the applicable MIME (multimedia internet mail extension) type. The value should be a valid MIME media type defined by the Internet Engineering Task Force in RFC 2046.

The att.linking class provides another set of common attributes for linking (see 13.1.1 General Relationships Between Elements):

Additionally, the following attributes are also available on ptr and ref:

Via the att.metadataPointing class:

@
Identifies one or more metadata elements (other than classification terms) within the header, which are understood to apply to the element bearing this attribute and its content.

Via the att.classed class:

@
class (att.classed)
Contains one or more URIs which denote classification terms that apply to the entity bearing this attribute.

Via the att.responsibility class:

@
Indicates the agent(s) responsible for some aspect of the text’s transcription, editing, or encoding. Its value must point to one or more identifiers declared in the document header.

13.2.2.1Define the link element’s target (XPointer mechanism)

The target attribute specifies the destination of a pointer or reference using a method standardized by the W3C consortium, known as the XPointer mechanism. The XPointer framework is described at http://www.w3.org/TR/xptr-framework/. This mechanism permits a range of complexity, from the very simple (a reference to the value of the target element’s xml:id attribute) to the more complex usage of a full URI with embedded XPointers:

<!-- element ID -->
<ptr target="#SA"/>
Listing 430.

<!-- relative URL -->
<ptr target="myFile.xml"/>
Listing 431.

<!-- absolute URL -->
<ptr target="http://www.w3.org/TR/xptr-framework/"/>
Listing 432.

<!-- URL with fragment identifier -->
<ptr target="http://www.w3.org/TR/xptr-xpointer/#xpointer(id('chum')/quote)"/>
Listing 433.

<!-- URN -->
<ref target="urn:isan:0000-0000-9E59-0000-O-0000-0000-2">Spider-Man</ref>
Listing 434.

A target attribute is not required in order to mark the textual content as a cross-reference, as demonstrated in the example below; however, without this attribute the reference will not be resolvable.

<p>See
<ref>Hankinson, Roland, Fujinaga (2011)</ref>
.</p>
Listing 435.

13.2.2.2Define the type of a link element’s target

The targettype attribute allows the target resource to be characterized using any convenient classification scheme or typology. This is often useful when the target requires special processing, e.g., for display purposes. The pointers in the examples below may be formatted differently, e.g., the bibliographic citation may result in special typography while the pointer to the audio file may be used to embed an audio player:

<ptr target="#cit1" targettype="biblioCitation"/>
Listing 436.

<ptr target="http://path.to.resource/myAudio.aiff" targettype="audioClip"/>
Listing 437.

13.2.2.3Define the mimetype of a link element’s target

The function of the mimetype attribute is similar to that of targettype in that they both allow classification of the destination. Unlike targettype, however, mimetype explicitly defines the destination type using a standard taxonomy. Its value should be a valid MIME (Multimedia Internet Mail Extension) type as defined by the Internet Engineering Task Force (IETF) in RFC 2046, available at http://www.ietf.org/rfc/rfc2046.txt. The following are all valid mimetype values:

<ptr mimetype="application/pdf" target="my.pdf"/>
<ptr mimetype="text/xml" target="my.xml"/>
<ptr mimetype="image/png" target="my.png"/>
Listing 438.

As shown above, the ptr element can be used to ‘point to’ a digital image (target="my.png"). However, when the intention is to display a digital image as part of the rendering of an MEI file, the graphic element provides a convenient and recommended alternative:

<graphic mimetype="image/png" target="my.png"/>
Listing 439.

The mimetype attribute is particularly useful for documenting the nature of the destination when the value of target does not provide a filename extension or when the destination is a non-standard file type:

<ptr mimetype="application/pdf" target="myFile1"/>
<ptr mimetype="application/x-myApplicationSpecificFile" target="myFile2"/>
Listing 440.

13.2.2.4Determine the link element’s behaviour

The xlink:actuate and xlink:show attributes are used in conjunction to determine the link’s behavior.

The xlink:actuate attribute defines whether the resolution of a link occurs automatically or must be requested by the user.

The following values are allowed for the xlink:actuate attribute:

‘onLoad’: load the target resource(s) immediately

‘onRequest’: load the target resource(s) upon user request, e.g., after a mouse click

‘none’: do not permit loading of the target resource(s); no other markup is provided to determine appropriate behavior

‘other’: behavior other than permitted by the other values of this attribute; application should look for other markup to determine appropriate behavior

The value none may be used to indicate that the link is un-traversable and no other markup is provided to determine appropriate behavior; it may or may not render the link invisible to the user. When the value of xlink:actuate is other, an application must base a determination of appropriate behavior on factors other than the value of xlink:actuate.

The xlink:show attribute defines how a remote resource is to be rendered. The following values are permitted:

‘new’: target of the link appears in a new window

‘replace’: target of the link replaces the current resource in the same window

‘embed’: the content of the target appears at the point of the link

‘none’: do not permit traversal to the target resource(s); no other markup is provided to determine appropriate behavior

‘other’: behavior other than permitted by the other values of this attribute; application should look for other markup to determine appropriate behavior

The value none may be used to indicate a link that is not displayed or is not displayable and no other markup is provided to determine appropriate behavior. When the value of xlink:show is other, an application must base a determination of appropriate behavior on factors other than the value of xlink:show.

The following example illustrates a pointer that results in the automatic creation of a new window with the content of the target loaded in it:

<ptr mimetype="text" target="http://www.ietf.org/rfc/rfc2046.txt" xlink:actuate="onLoad" xlink:show="new"/>
Listing 441.

13.2.2.5Determine the link element’s role

The xlink:role attribute describes the meaning of resources within the context of a link. It is used to label or describe a link or resource in a human- and machine-readable fashion. The value of xlink:role must be an absolute URI (Uniform Resource Identifier) reference as defined by the Internet Engineering Task Force (IETF) in RFC 3986, available at http://tools.ietf.org/html/rfc3986. The URI reference identifies a resource that describes the intended property. When no value is supplied, no particular role value is to be inferred.

<ptr target="joe.xml" xlink:role="http://www.example.com/linkprops/student"/>
Listing 442.

<ptr target="joe.xml" xlink:role="http://www.example.com/linkprops/instructor"/>
Listing 443.

In the preceding examples, the value of the xlink:role attribute may be used to specify the value of the link target’s role.

13.3Linking and Alignment

The linkAlign module has been deprecated in MEI v3.