B1Introduction to MEI

1.1.1Acknowledgments

Many institutions and individuals assisted in the preparation of these Guidelines and in the overall development of the Music Encoding Initiative framework and community.

Grateful acknowledgment is given to the following institutions for their generous contributions: the Akademie der Wissenschaften und der Literatur (AdW) in Mainz for serving as hosting institution for the MEI Community, and the National Endowment for the Humanities (NEH) and the Deutsche Forschungsgemeinschaft (DFG) for their joint financial support of the MEI project in its early stages. We thank several institutions that hosted Music Encoding Conferences or other MEI-related meetings in the past: The AdW Mainz, the University of Virginia Library, the Biblioteca Umanistica of the Università degli Studi Firenze, McGill University Montréal, the Centre d’études supérieures de la Renaissance Tours, the Maryland Institute for Technology in the Humanities (MITH) in College Park, the Oxford e-Research Centre, the Universität Paderborn and the Österreichische Akademie der Wissenschaften Wien in conjunction with the Universität Wien and the Mozarteum Salzburg. We also thank all other institutions that allow their researchers to invest time into both the community and the encoding framework. It is their interest that makes MEI an incredible platform for interchange and scholarly progress.

The Text Encoding Initiative is also owed a special debt of gratitude. In addition to providing much of the inspiration for MEI, the TEI organization supplied funding for the MEI Technical Group in its efforts to adopt ODD. The editors of these Guidelines are grateful for those of the TEI, which provided a stellar exemplar and from which we have borrowed shamelessly.

MEI has been a community-driven effort for more than a decade, and many individuals have provided significant and much-appreciated commitments of time and energy to the development of MEI: Nikolaos Beer; Vincent Besson; Benjamin W. Bohl; Margrethe Bue; Donald Byrd; Irmlind Capelle; Tim Crawford; David A. Day; Giuliano Di Bacco; Norbert Dubowy; Richard Freedman; Ichiro Fujinaga; Andrew Hankinson; Maja Hartwig; Kristin Herold; Franz Kelnreiter; Johannes Kepper; Robert Klugseder; Zoltán Kőmíves; David Lewis; Urs Liska; Elsa De Luca; Erin Mayhood; Stefan Morent; Stefan Münnich; Markus Neuwirth; Kevin Page; Daniel Pitti; Laurent Pugin; Klaus Rettinghaus; Kristina Richts; Daniel Röwenstrunk; Perry Roland; Craig Sapp; Agnes Seipelt; Eleanor Selfridge-Field; Christine Siegert; Peter Stadler; Axel Teich Geertinger; Martha Thomae; Joachim Veit; Raffaele Viglianti; Thomas Weber; and Sonia Wronkowska.

Thanks to Bernhard R. Appel; Richard Chesser; Morgan Cundiff; J. Stephen Downie; Oliver Huck; Fotis Jannidis; John Rink; Federica Riva; Frans Wiering and Barbara Wiermann for providing expertise on a wide range of topics related to music notation modelling.

Also thanks to Syd Bauman, Terry Catapano, and Sebastian Rahtz for their invaluable problem-solving assistance during the development of the 2010 RNG schema. Thanks to Sebastian Rahtz and James Cummings of the Text Encoding Initiative (TEI) for their help with making ODD work with MEI, their assistance in more closely aligning MEI and TEI, and their quick responses to questions and Roma bug reports.

Finally, the members of the Music Encoding Initiative would like to thank Perry Roland for his foresight, engagement and dedication in laying the foundations of this initiative.

1.1.2About version 5.1

Following release 5.0 from September 2023, Release 5.1 of MEI focuses primarily on maintenance fixes of the guidelines and the development infrastructure, and on consistency, with only limited changes to the specifications. Perhaps the most important additions are the enhancements for the MEI tablature module, particularly the support for German Lute Tablature (GLT). Notable fixes to the guidelines include correcting the description of the @optimize attribute on <scoreDef> to clarify that empty staves are not displayed when its value is set to true. The Release Managers for MEI 5.1 were the Technical Co-Chairs, Benjamin W. Bohl and Stefan Münnich.

With MEI 5.1, five additional elements have been added to the schema: <tuning>, <course>, <string>, <tabDurSym>, and <tabGrp>. All of these elements are used to encode tablature notation. The use of these elements, including relevant attributes, is documented in the largely rewritten chapter B7 Repertoire: String Tablature of these Guidelines. The existing att.stringtab.tuning [not available in this MEI customization] attribute class has been deprecated in favor of these additions and will be removed in a future version of MEI.

The new att.dataSelecting class (currently available only on <symbolDef>) introduces an XPath-based selection mechanism to identify elements to which certain features apply.

All controlevents (see 1.3.2 Events and Controlevents, technically implemented through membership in the att.controlEvent class) are now member of att.color, enabling color customization through the @color attribute. Similarly, directive-like elements (<bend>, <breath>, <caesura>, <cpMark>, <fermata>, <fing>, <fingGrp>, <harm>, <harpPedal>, <metaMark>, <mordent>, <octave>, <ornam>, <trill>, and <turn>) are now member of the att.verticalGroup class, which gives them access to the @vgrp attribute, facilitating vertical alignment.

Minor changes include the addition of @visible and @enclose on <meterSigGrp>.

1.1.3About version 5.0

Release 5.0 of MEI focuses primarily on the guidelines, development infrastructure, and consistency, with only limited changes to the specifications. Perhaps the most important additions are the introduction of the MEI Basic customization, and the availability of an auto-generated PDF version of the Guidelines (see below for more details on both). The Release Managers for MEI 5.0 were the Technical Co-Chairs, Benjamin W. Bohl and Stefan Münnich.

1.2.1Definitions and Parameters

A music notation document is one that contains music notation; that is, any one of a number of "visual analogues of musical sound, either as a record of sound heard or imagined, or as a set of visual instructions for performers." (Ian D. Bent, et al. "Notation." Grove Music Online. Oxford Music Online. 25 May 2010. http://www.oxfordmusiconline.com/subscriber/article/grove/music/20114.) However, MEI’s understanding is more inclusive than this restrictive definition, i.e., Braille certainly qualifies as music notation documents.

The encoding scheme permits both the creation of new music notation documents and the conversion of existing ones from print and other electronic formats. However, conversion of existing documents may require revisions in content or rearrangement of information.

1.2.2General Principles

MEI may be used to encode both primary sources of music notation, such as an autograph or published score, and secondary sources, such as a scholarly edition based on one or more primary sources. The format encompasses both use cases, and the encoder must choose the elements and attributes most appropriate in each case. These Guidelines aim to provide guidance on that task.

As an encoded representation of one or more music notation documents, an MEI file may be employed as a surrogate for the original materials.

Although the encoding scheme does not define or prescribe intellectual content for music notation documents, it does define content designation and is intended to be used with available data content standards. MEI identifies the essential data elements within music notation documents and establishes codes and conventions necessary for capturing and distinguishing information within those elements for future action or manipulation. While there are a few elements that ought to appear in any MEI document, various intellectual, technical, and economic factors influence the level of detail of analysis and encoding actually undertaken. Taking this into consideration, the encoding scheme is designed with a minimum of required elements and allows for progressively more detailed levels of description as desired.

The encoding scheme preserves and enhances the current functionality of existing music notation documents. It permits identification of document structures and content that support description, navigation, analysis, and online and print presentation.

The encoding scheme is intended to facilitate interchange between notational tools. It aims to assist in the creation of more effective and consistent encoding, encourage the creation of cooperatively-created and widely available databases of music notation documents, and permit the reuse of encoded data for multiple output purposes. It will also ensure that machine-readable music notation documents will outlive changing hardware and software environments because they are based on a platform-independent standard.

1.2.3Structural Features

The encoding scheme is based on eXtensible Markup Language (XML), a text-based format for representing structured information. It is expressed as a One Document Does-it-all (ODD) document. For more information on ODD, please refer to 1.3.5 Customizing MEI.

Related or complementary standards, such as the Text Encoding Initiative (TEI) Guidelines for Electronic Text Encoding and Interchange, the Encoded Archival Description (EAD), MARC 21 Format for Bibliographic Data, existing notation encoding schemes, etc. have been consulted and employed as appropriate. For example, the data model includes a header that is comparable to the TEI header, and TEI and EAD naming conventions and tag structures have been used whenever feasible. However, while some feature names are similar, or even the same, it is important to recognize that MEI and TEI have different semantic scope. Obviously, a note element in MEI does not carry the same meaning as the element of the same name in TEI. Perhaps less obviously, a phrase in music notation is unrelated to a textual phrase.

With respect to metadata, MEI recognizes the close relationship between the metadata content found in the MEI header and that of catalog records, authority records, and finding aids. Therefore MEI provides ways of indicating in the encoding the corresponding fields of other metadata standards.

To ensure broad international and multi-repertoire application of MEI, existing musical terminology was used in building the data model where practical. When appropriate, a more neutral terminology was used to facilitate sharing of concepts and thus stressing the commonalities between different repertoires. Finally, extensive use of attributes and clearly-defined classification mechanisms in the schema permits the refinement of element meanings within specific musical, geographic, or temporal contexts.

1.2.4Control and Maintenance

The Music Encoding Initiative Community has given itself By-laws, which regulate all essential properties and procedures. The community elects a Board, which in turn governs and represents the community. The Board consists of nine elected members, with three seats standing for election for three year terms each year. Everyone registered to the MEI-L mailing list is eligible to vote for the Board.

In addition to the Board, there is a Technical Team, which is open for anyone interested to work on the maintenance and improvement of MEI itself. The Technical team will assist Interest Groups and other interested community members in an advisory capacity on how to further develop MEI for both existing and new fields of application.

1.3.1Musical Domains

The term "music" has many different notions, ranging from audible sounds over written performance instructions or transcriptions of such events to conceptual rulesets that establish different theories of what music is, and what is allowed in music. In 1965, Milton Babbitt distinguished between graphemic, acoustic and auditory aspects of music (Babbitt, Milton: "The Use of Computers in Musicological Research", in: Perspectives of New Music 3/2 (1965), p. 76).

Various music encoding formats took up this distinction, most notably, the Standard Music Description Language (SMDL) (ISO/IEC DIS 10743). While the format itself was hardly ever used for its impractical implementation details, parts of its design certainly influenced the development of other formats, including MEI. In a documentation draft (http://xml.coverpages.org/smdl10743-pdf.gz, p.5), SMDL identifies four different musical domains:

logical domain: The logical domain is the basic musical content – the essence from which all performances and editions of the work are derived, including virtual time values, nominal pitches, etc. The logical domain is describable as "the composer’s intentions with respect to pitches, rhythms, harmonies, dynamics, tempi, articulations, accents, etc.," and it is the primary focus of SMDL. It can also be described as "the abstract information common to both the gestural and visual domains." […]

gestural domain: The gestural domain is comprised of any number of performances, each of which may specify how and when components of the logical domain is rendered in a specific performance, including all the means whereby the performer actually expresses (acoustically instantiates) the music (intonation, agogic and dynamic stress, etc.). The gestural domain is perhaps most succinctly described as "the information added by performers," or "how the music actually sounds during particular performances." […]

visual domain: The visual domain is comprised of any number of scores, each of which somehow specifies exactly how components of the logical domain is rendered visually in some particular printable (and/or displayable) edition, including such graphical details as symbology, symbol sets, fonts, page layout, beaming conventions and exceptions, etc. The visual domain is perhaps most succinctly described as "the information added by human editors, engravers, and typesetters," or "how the music actually looks in some particular edition." […]

analytical domain: The analytical domain is comprised of any number of theoretical analyses and/or commentaries, each of which somehow specifies opinions, exegeses, etc. about any or all of the information in the other three domains. […]

On a generic level, MEI follows the same definition, and it definitely shares the same terminology. However, not all four domains are available throughout the MEI schema, and quite frequently, two domains fall together in MEI. Very often, MEI prioritizes the visual domain over the gestural domain by (partly) conflating the logical and the visual domains. For example, MEI utilizes the @pname (pitch name) attribute on notes to capture the written pitch of a note, whereas the sounding pitch may be described with the @pname.ges attribute. Here, the logical and visual domains go without a special indication, whereas the gestural domain is identified by a special suffix. However, in case of transposing instruments, additional markup (namely the attributes @trans.diat and @trans.semi from MEI’s attribute class att.staffDef.log) will create a distinction between the logical and visual domain (see chapter 4.2.2 Defining Score Parameters for CMN). In that case, @pname will be restricted to the visual domain, while the logical aforementioned attributes provide additional information for the logical domain.

Even though the technical implementation of MEI prioritizes the visual domain to some degree, this does not mean that any given encoding has to provide visual information. MEI takes no assumption on what data is required: While an Optical music recognition (OMR) project may generate strictly visually oriented data only, another project focussed on audio transcriptions may generate gestural data only. A third project could integrate both approaches.

In order to avoid ambiguous encodings, MEI is very strict and specific on the scope of its individual markup elements. For an encoder, the suffixes mentioned above provide clear hints on which domain is addressed by specific markup: Many attributes carry a suffixed .log (logical), .ges (gestural), .vis (visual), or .anl (analytical) in their name. In addition, the internal structure of MEI heavily relies on those different domains. When customizing MEI (see chapter 1.3.5 Customizing MEI), it is possible to turn off either visual or gestural domain encoding completely. That way, MEI allows to address the four most eminent musical domains specifically and independent of each other.

1.3.2Events and Controlevents

MEI differentiates between two essential aspects of music notation: Events and ControlEvents. There are other examples for such a separation of concerns with regard to music. In Greg’s Copy-Text Theory (W.W. Greg: The Rationale of Copy-Text, 1950), a distinction between primary and secondary text is made; similar attempts have been made for music specifically.

In MEI, elements describing the basic musical text are referred to as Events. They are the building blocks for the stream of music – mostly those are <note>s, <rest>s, and <chord>s. In contrast, ControlEvents make no independent contribution to that flow of music. Instead, they provide additional information about the encoded Events, they control their performance. Examples for such ControlEvents are <dynam>ic markings, <tempo>s indications, or performance <dir>ectives. Depending on the encoding strategy used, <slur>s and <tie>s often also fall into this category (they may be encoded as attributes instead, in which case they become a property of the basic events). Simply put, Events describe what needs to be performed, and ControlEvents indicate how it needs to be performed. In (B4 Repertoire: Common Music Notation-based) MEI, Events are nested inside a <layer> element, while ControlEvents are direct children of the first <measure> they apply to, following all <staff> elements there. These structural differences result in different markup concepts. As Events are encoded inside <layer>s, their semantic position inside the encoded work can be derived from their structural position – the measure, staff and layer they’re nested in, and within that layer by their position inside the sequence of all layer children. As mentioned above, it is highly recommended to encode ControlEvents inside the first measure they apply to, but they still require references to the actual events they apply to. There are two common concepts to provide such a connection, both of which offering specific benefits and drawbacks. A technically very stable connection between ControlEvents and Events can be established by using pointers. In this case, all events that need to be referenced need an @xml:id attribute, which holds a globally unique identifier for this very element. The referencing controlevent then uses a @startid and, if necessary, @endid attribute to create a link to where in the stream of music it is supposed to start or end.

In the example above, the <dynam> element references the second quarter in the given measure. Additional attributes like @place may be used to describe the position of the forte indication within the score. A <hairpin> element may use the @endid attribute to indicate the duration of the hairpin using the same mechanism as above.

A ControlEvent encoded like above will be strictly tied to the referenced Events – if their position inside the XML document changes for whatever reason, they will keep that connection. This means that the semantic position to which they are bound may change without affecting the binding. An example could be an inserted additional note in front – the dynamic marking would not start on the second quarter, but perhaps on the third instead.

As this behavior may not be desired in all cases, an alternative binding between ControlEvents and Events is possible, relying on timestamps instead. This mechanism is illustrated in the following example:

Here, no @xml:id is required on notes. Instead, the <dynam> element uses the @staff and @layer attributes to indicate to which set of events the following @tstamp attribute refers to.

This mechanism actually depends on what has been only recommended above: placing the controlevent inside the measure where it starts. The @startid reference mechanism would work equally well if all controlevents where positioned in the very first or last measure, or actually even inside a separate file. The @tstamp references however would not, they depend on correct placement of the controlevents inside the XML tree. For consistency, it is therefore recommended to always use this placement.

The benefit of this concept is that controlevents are tied to a semantic position, but not necessarily to a given XML element. The forte may still be placed on the second quarter, even though the composer may have replaced that quarter G4 with a different pitch and / or duration. Actually, it is not required that an Event can be found at the position indicated by a timestamp. This may be useful to encode a slur ending at an arbitrary position between two events, or dynam markings spread across otherwise empty measures.

If the ending of a ControlEvent shall be given by timestamp, the @tstamp2 attribute is used.

Because of potential inconsistencies, an encoding should not offer both @startid and @tstamp or @endid and @tstamp2. Though not being recommendable, it is possible to mix @startid with @tstamp2 and @tstamp with @endid. In general, it is easier for software to process @startid and @endid. When no other arguments apply, using @xml:id-based pointers is therefore the most common way to connect ControlEvents with Events.

The details on how timestamps are calculated and used in MEI are given in 1.3.3 Timestamps in MEI.

1.3.3Timestamps in MEI

In MEI, timestamps are treated in a slightly simplified way: they have no notion of beat. Instead, timestamps rely solely on the numbers given in the meter signature. In a measure of 4/4, timestamps will range from 1 to 4. The second eighth note will be 1.5 in this case. If the same measure would be given in 2/2, it would be 1.25 instead.

At this point, MEI uses real numbers only to express timestamps. In case of (nested or complex) tuplets, this solution is inferior to fractions because of rounding errors. It is envisioned to introduce a fraction-based value for timestamps in a future revision of MEI. For now, it is recommended to round the fractional part of the number to no more than five digits to avoid such problems.

Durations may also be expressed based on timestamps. In this case, the values are a combination of the count of measures that need to be moved forward to reach the measure in which an encoded feature ends, and the timestamp within that measure.

Sometimes, timestamps are used to indicate positions where no music Events are located (see 1.3.2 Events and Controlevents). Therefore, the allowed range of timestamps stretches from 0 to the current meter count + 1. By definition, a timestamp of 0 indicates the position of the left bar line, while a timestamp of 5 (in case of a 4/4 meter) indicates the right bar line. This makes it possible to encode open-ended slurs in a graphical way. However, it should be kept in mind that such timestamps may not be converted to @startid and @endid, and not every application may be able to render them correctly, even though they are perfectly valid MEI, and sometimes are necessary to faithfully transcribe a source.

1.3.4MEI Customizations

MEI is an encoding framework, not a data format. This means that MEI provides recommendations for encoding music documents, but it depends on the encoder’s needs and requirements to which features and solutions are appropriate to the task and should be used. MEI offers specific models for different notation types and music repertoires, but it is rarely advisable to use them all side by side in one encoding.

In order to use MEI, it is advised to use a restricted version of the schema, which will make it easier both for an encoder and a reader of the encoded files. MEI provides a number of pre-defined customizations, which focus on specific uses of MEI while still maintaining a great level of flexibility. For projects that need even better control over their data, it is highly recommended to create a more specific customized version of MEI (see chapter 1.3.5 Customizing MEI). The following customizations are provided with every release of MEI:

mei-cmn: For most users, this will be the best starting point into music encoding with MEI. The mei-CMN customization targets at documents that use Common Western Music Notation. The specific rules for that notation are specified in chapter B4 Repertoire: Common Music Notation, even though other chapters of these Guidelines apply as well.

mei-Mensural: For documents written in Mensural Notation (both black and white), MEI offers the mei-Mensural customization. The specific rules for that notation are specified in chapter B5 Repertoire: Mensural Notation, even though other chapters of these Guidelines apply as well.

mei-Neumes: This customization allows to encode medieval Neume Notation with MEI. The specific rules for that notation are specified in chapter B6 Repertoire: Neume Notation, even though other chapters of these Guidelines apply as well. Please note that the mei-Neumes customization has undergone significant changes from MEI version 3 to version 4.

mei-basic: As an encoding framework, MEI offers multiple approaches to encode certain features at various levels of detail. While this flexibility is at the core of MEI and often required for research projects, it is an obstacle when developing software and converters for MEI. The mei-Basic customization is a subset of MEI which restricts it to one way of encoding for every feature of music notation. It covers Common Western Music Notation only, and excludes all editorial markup. In essence, it has the same functionality as most other music encoding formats like MusicXML or MNX. The purpose of mei-Basic is to serve as common ground for data interchange, both between projects using different customizations of MEI, and other encoding schemes.

mei-all: This is the full definition of MEI. It includes all different repertoires, which has certain side effects and enables encoding options that are neither intended nor advocable. For example, in mensural notation music is organized by staves. In contrast, Common Music Notation utilizes measures, which in turn contain staves. These staves have a different meaning here, and are modeled differently in MEI. mei-all mixes those models and thus invites encoding errors. In general, you should almost never use mei-all except for testing purposes.

mei-all_anyStart : This customization includes all of mei-all, but extends it even further so that it allows any MEI element as root of conforming MEI instances. In regular MEI, the only allowed starting elements are <mei>, <meiHead>, <music> and <meiCorpus>. The sole purpose of this customization is to simplify validation at tutorial sessions and other educational purposes. It should not be used in production.

The first three customizations provide good starting points to encode music from the respective repertoires. They may also serve as template for further, project-specific customizations. The latter two customizations target very specific use cases and should not be used by default.

1.3.5Customizing MEI

In production, it is best to use a customized version of MEI, restricted to the very needs of a project. Such a custom schema will guide the encoders and will help to ensure consistency and data quality throughout a project’s files. A customization typically provides a subset of MEI’s encoding models (typically starting from one of the official customizations mentioned in chapter 1.3.4 MEI Customizations), with only one solution for any given situation being allowed. The customization will help to reflect the scope of a project into its data: Only those aspects of music notation a project is interested in will be allowed, so that the absence of a specific information can not be misunderstood as an oversight of the encoders. Larger editorial projects like Complete Works editions typically use Editorial Guidelines (german: Editionsrichtlinien) for the same purposes: (internal) quality control and (external) documentation. In that sense, MEI customizations may serve as Editorial Guidelines in digital form.

MEI is implemented in ODD (One Document Does-it-all). ODD, is another XML-based markup language developed and maintained by the TEI. TEI’s documentation for ODD can be found in the TEI Guidelines chapter 22: Documentation Elements, chapter 23: Using the TEI, and the Getting Started with P5 ODDs" document.

1.3.5.2Quick Extensions using the Type Attribute

In MEI, the @type attribute is available on almost every element.

@

@type (att.typed)

Designation which characterizes the element in some sense, using any convenient classification scheme or typology that employs single-token labels.

@type is a built-in, easy to use extension mechanism, as it allows for the addition of almost any kind of data to any given element.

In the example above, the scribe uses two different ways to write 16th notes for the Canto and Alto voices. In the following measure, he uses the same way again, leaving it unclear if there is any meaning associated with the form written.

If a project wants to preserve this observation, ib order to be able to get back to it later, compiling all such cases and search for potentially meaningful patterns, it is possible to flag one or both of these notes with a @type attribute. Such a solution could be as follows:

<!-- Canto note -->

<note dur="16" type="regularShape"/>

<!-- Alto note -->

<note dur="16" type="weirdShape"/>

While not using dedicated new markup for this information, it is possible to query a file for all the notes having a @type of weirdShape (or any other value), using standard XPath queries. In other words, a (here deliberately informal) description of an additional feature not covered by regular MEI has been added to the encoding of the note, which is fully accessible to further investigation and / or processing. Please note that it is not required to add @type to all notes, so it would be equally possible to add it just to the "special" notes or elements, and then later query for the absence of a given type value.

The datatype of @type allows for a series of multiple string values, making it possible to capture any number of additional features not catered for by regular MEI.

1.3.5.4Extensions introducing New Markup

Sometimes, 1.3.5.2 Quick Extensions using the Type Attribute and 1.3.5.3 Extensions based on Classification are not sufficient to adequately capture certain situations. This is usually the case when existing MEI elements do not offer the amount of structure or specifity needed to address the feature in question with attribute-based approaches only.

The following example is a hyphothetical extension to MEI. It is actually not considered a generally useful addition – if so, it would have been added already. However, it may make sense under certain conditions, and so this example is just an example for the process of extending MEI with new markup – it is not necessarily an example of a particularly convincing extension.

Consider a project that wants to encode a music document written in multiple colors. Here is an excerpt of that document, used for the purposes of this example:

MEI is capable of capturing the color of a note, using the @color attribute.

<note color="colorful"/>

However, with a value of colorful (or any other single string), it is not possible to explicitly identify the different colors for notehead, stem and flag independently. If that music document would reflect some fictional 20th century piece where color of these parameters would indicate some meaningful feature (performing forces, dynamics, …), it would be necessary to capture the color at a higher resolution. One potential way to do that would be to go for dedicated child elements:

<note>

<head color="blue"/>

<stem color="red"/>

<flag color="green"/>

</note>

This encoding would now capture the colors of the various note components correctly, but following to the arguments provided in chapter 1.3.5.1 Terminology and Workflows, would be considered an incorrect extension to MEI: Neither the <stem> and <flag> elements are actually part of MEI, and the <head> element is actually not meant for noteheads, but headings – even when adding @color to it, it would be severe tag abuse to use it for the purpose at hand. Instead, the new child elements of <note> should be put in a separate namespace:

<note> <ex:noteHead color="blue"/> <ex:stem color="red"/> <ex:flag color="green"/> </note>

The three child elements are now referencing a (yet to be defined) separate namespace, making it clear they are not part of regular MEI. Please note that the notehead is also avoiding the name of the <head> element to minimize the risk of confusion on the encoder's side.

The definition of one such new element could be as follows:

<elementSpec ident="noteHead" module="MEI.visual" prefix="ex_" ns="https://www.example.com/mei/proposals">


<desc xml:lang="en">This element describes the visual appearance of a note head.</desc>




<classes>

<memberOf key="att.common"/>

<memberOf key="att.color"/>

</classes>




<content>

<empty/>


 </content>


</elementSpec>

This <tei:elementSpec> would be inserted in an ODD customization file, that would then be compiled against the MEI sources to create a new MEI profile supporting this new element (see the MEI repository for details about the technical procedures). While this definition is quite similar to the definition of other elements in the MEI sources, there are some important attributes to note. First of all, the @mode attribute with add value is necessary to insert an element in a customization – it means that this element will be added compared to what is in the ODD sources the customization is applied to. The @ns attribute will actually move the new element to a different namespace, while the @prefix attribute will specify how this new element may be addressed within the ODD file (more on that below). It has no meaning for files using this modified model. Please also note that the new element, despite being in a separate namespace, may fully utilize existing MEI attribute classes.

With the new <ex:noteHead> element being defined, it is now necessary to make it available somewhere within MEI, in this case as a child of the regular <note> element. For this purpose, the customization could also update the specification of that element:

<elementSpec ident="note" module="MEI.shared" mode="change">
 <content> <rng:zeroOrMore> <rng:choice> <rng:ref name="model.noteModifierLike"/>
 <!-- omitted for brevity --> <rng:ref name="ex_noteHead"/> </rng:choice> </rng:zeroOrMore> </content> <remarks xml:lang="en">
 <p> The <gi scheme="MEI">note</gi> element may have an additional <gi>noteHead</gi> child element in our project, which is meant to … </p>
 </remarks> 
</elementSpec>

Here, the existing <tei:elementSpec> is updated using the change @mode. This means that original child elements are overwritten with the specifications provided within the customization, leaving all others unchanged. For the purposes of this example, it is sufficient to just update the <tei:content>, where an additional rng:ref [not available in this MEI customization] with @name ex_noteHead is inserted. This refers to the @prefix attribute given for the new <noteHead> element above, and will make this newly specified element available as child inside <note>.

When changing existing MEI elements, it is recommended to add a <tei:remarks> element which explains the changes made and thus provides documentation for the specific use of this element and how it differs from common use.

Another, perhaps more elegant way to insert the new element into the MEI model which does not require to change existing elements would be to make the new element a member of the model.noteModifierLike class, as in the following example:

<elementSpec ident="noteHead" module="MEI.visual" prefix="ex_" ns="https://www.example.com/mei/proposals">


<desc xml:lang="en">This element visually describes a notehead.</desc>




<classes>

<memberOf key="att.common"/>

<memberOf key="att.color"/>

<memberOf key="model.noteModifierLike"/>

</classes>




<content>

<empty/>


 </content>


</elementSpec>

Since members of that class are already allowed as child elements of <note>, the new <noteHead> element will be allowed there as well. Please note that it is not necessary to offer both options, and using classes may result in a number of additional places where elements are allowed, which may or may not be appropriate. Also, sometimes there are no adequate classes available, so this is just illustrating potential solutions.

It is equally possible to extend MEI with new attributes. Following the same arguments, these attributes should also be put in a separate namespace. Note that the following approach could also serve as an alternative strategy to encode the color of the different components of our colorful music document.

<attDef ident="headColor" usage="opt" mode="add" ns="https://www.example.com/mei/proposals"> <gloss xml:lang="en">Color of a noteHead.</gloss>
 <desc xml:lang="en">Describes the color of a note head.</desc> <datatype>
 <rng:ref name="data.COLOR"/>
 </datatype> 
</attDef>

This new attribute could then either be added to an existing or new attribute class, or could be made available on <note> directly. An encoding using this attribute might then look like so:

<note ex:headColor="blue"/>

Using ODD customizations, it is also possible to restrict or extend allowed values of attributes. While this is not documented in the current version of these Guidelines, it is important to point out that it technically not possible to indicate which values are not included in regular MEI, as neither XML Namespaces nor similar mechanisms can be applied to those new values. It is therefore important to exercise extra diligence when documenting such extensions to the schema.

Extending MEI should not be taken lightly, and should always be based on intense interchange with the MEI Community. Adding new markup to the schema is often a tempting solution, but it comes at the risk of weakening the standard through competing solutions. In general, extensions should only be made when either the community agrees on the proposed solution, ensuring interoperability between similar projects, or when the proposed markup is for internal use only, and not expected to be taken up by others at all. Very often, less invasive but equally target-oriented approaches can be found. In case of the colorful example above, it might be equally adequate to address the situtation by using @type (or @class):

<note type="noteHead:blue stem:red flag:green"/>