Recipe Markup Language (RecipeML)

Working Draft 8 April 2001 (incomplete)

This version:
Latest version:
Previous version:
James Saiya, FormatData


This specification defines the Recipe Markup Language (RecipeML), a means to represent food preparation recipes in the Extensible Markup Language (XML).

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained by FormatData.

Editors notes appear in this style, preceded by two '@' symbols. Reader comments on notes which raise open issues are welcome and encouraged. Use the Web forum or e-mail address below.

Public discussion on RecipeML takes place on the Web forum

Please report errors in this document to


0. Introduction

0.1 Specification Approach

RecipeML documents are XML documents as defined by the XML 1.0 specification [XML].

For describing the syntax of RecipeML documents, this specification uses an XML Document Type Definition (DTD) (see Appendix A.1)

0.2 Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. However, for readability, these words do not appear in all uppercase letters in this specification.

0.3. Generally Applicable Attributes

Nearly all elements in RecipeML share a set of attributes. The definitions of these attributes will not be repeated in the element descriptions. There are four major groups of generally applicable attributes:

Core Attributes

These attributes apply to nearly all RecipeML elements. They are similar to the ones defined in HTML 4.01; id and class are covered in section 7.5.2, and title is covered in section 7.4.3 of [HTML].

Used to give a unique identifier to an element. Values for id must be unique across all elements in a single document and are of type ID as defined in [XML] section 3.3.1.
Used to allow selector-based style specification. Note that generic XML processors applying CSS stylesheets to a RecipeML document might not, and probably will not, employ the dot (.) notation used by HTML browsers for class attributes. See [CSS2] section 5.8. Values for class are of type NMTOKEN as defined in [XML] section 3.3.1. @@ Currently defined as NMTOKEN in RecipeML version 0.5 -- may be redefined as NMTOKENS in a later version.
Used to provide an "advisory title" or "amplification" for the element. User agents (browsers) are not required to do anything in particular with its value, although a common practice is to display the title as a "tool tip" (a short message that appears when the pointing device pauses over an object). Values for title are of type CDATA as defined in [XML] section 3.3.1.

Internationalization (i18n) Attributes

Used to specify the natural (human) language of the content of an element, including any contained elements unless those are overridden by their own xml:lang attribute. The value of this attribute is defined in [RFC1766] or its successor on the IETF Standards Track. See [XML] section 2.12 for a full definition including formatting rules for language identifiers.


<title xml:lang="es">Arroz con Pollo</title>

Common Attributes

This attribute group applies to most RecipeML elements. It includes the core attributes (id, class, title) and the i18n attributes (xml:lang).

Measurement Attributes

Used to define the measurement system used by any measurements (volume, temperature, etc.) in the content of an element. This also applies to the content of any contained elements (unless overridden by a system attribute in the contained element). The possible values are:
United States Customary System of weights and measures (ounces, inches, °F, etc.). Weights are avoirdupois.
The British Imperial System of weights and measures. This varies from "US" in some volume units; weights (mass) and lengths are the same as in "US".
Metric system (liters, centimeters, °C, etc.).
International System of Units, a formalized version of the metric system often used in science (included for completeness). See
Used for any system not represented here.
These values are case sensitive. If the system attribute is not present, the measurement system is undefined. Each RecipeML implementation may choose to use this information as it sees fit.

Division Attributes

This attribute group applies to the division elements: equip-div, ing-div, and dir-div. It includes the core attributes (id, class, title), the i18n attributes (xml:lang), the measurement attributes (system), and the type attribute.

Used to specify the purpose of the division element in which it is used. The possible values are:
If there is more than one division of a given type (i.e., more than one group of ingredients) one of the divisions may be considered the "main" division. For instance, if, in a recipe for pastry, there is a group of ingredients for the pastry itself and another group for the frosting, the pastry group could be given type="main" and the frosting group type="titled".
If a division is used to describe a variation (i.e., a group of directions for high-altitude cooking), it would be given type="variation". There can be more than one variation division of each type (equipment, ingredients, directions) in a recipe.
If an element such as equpment is broken into divisions using equip-div elements, each division (with the possible exception of a "main" division) should be given a title with a title element. In this case the equip-div element should have the attribute specification type="titled".
If the type attribute is not present, the default value is "titled".

See the descriptions of the division elements (equip-div, ing-div, dir-div) for more information on their use.

0.4 Internet Media Type

The general recommended MIME labeling (see [RFC2046]) for XML-based applications is specified in [RFC3023]. Based on this RFC, the MIME type for RecipeML documents prior to registering with IETF shall be:

FormatData plans to register under the vendor tree the MIME type:

In the future, FormatData may register a MIME type in the IETF tree, if the IETF sees fit to allow this.

1. Structure Elements

This section covers the elements which represent the overall structure of a RecipeML document.

1.1 recipeml Element

The recipeml element is the document element. The document element is the top-level element; i.e., it contains all other elements in a RecipeML document.


<!ELEMENT recipeml (meta*, (menu | recipe))>

The recipeml element can contain:


<!ATTLIST recipeml 
	version NMTOKEN #FIXED "0.5"
	generator CDATA #IMPLIED
	%common.att; >
version (optional)
The version of RecipeML in which the document instance is coded. This attribute is optional, but if included, its value must match the version of any DTD used to validate the document. For this revision of the specification, the version number is "0.5."
generator (optional)
The name (and optionally, version number) of the program that was used to create the document instance. @@ Should this attribute be removed? Perhaps this data could be represented in a processing instruction? @@ This could also be represented as an FPI.

Also see Common Attributes.


Example 1.1
<recipeml version="0.5" generator="RecipeWriter v1.0" xml:lang="en">
  . . .

1.2 meta Element

The meta element contains a piece of information (called metadata) that is used to categorize, locate, and otherwise describe an instance of the RecipeML document as a whole.

The Dublin Core Metadata Element Set [DCORE] is used as a framework for describing metadata elements. (Note that the use of the word element in relation to the Dublin Core is not the same as an XML element.)

Keep in mind that a RecipeML document can contain one or more recipes each which can have descriptive information. This information is put into the head element of each menu or recipe.



The meta element is empty.


<!ATTLIST meta 
	name	(DC.Title | DC.Subject | DC.Description | DC.Type | 
		 DC.Source | DC.Relation | DC.Coverage | 
		 DC.Creator | DC.Publisher | DC.Contributor | DC.Rights | 
		 DC.Date | DC.Format | DC.Identifier | DC.Language)	#REQUIRED
One of a set of 15 names which come from the Dublin Core Metadata Element Set. Each of the names is an element name as defined by [DCORE], proceeded by the string "DC.".
The value of the metadata. See [DCORE] for recommendations on how to format these values.
scheme (optional)
The format of the data in the content attribute. The value of this attribute should be taken from a fixed set of tokens @@ most likely provided by the Dublin Core initiative - TDB.
lang (optional)
The natural (human) language of the data in the content attribute. See the xml:lang attribute for the formatting of values.


Example 1.2
<meta name="DC.Title" content="Mock Apple Pie"/>
<meta name="DC.Creator" content="Ruth Sterling"/>
<meta name="DC.Source" content="To Serve Man"/>
<meta name="DC.Identifier" content="ISBN 0-914845-49-7" scheme="ISBN"/>
<meta name="DC.Publisher" content="Twilight Press"/>
<meta name="DC.Date" content="July 1958"/>
<meta name="DC.Rights" 
  content="Copyright 1958, Twilight Press, Los Angeles, CA."/>

1.3 menu Element

The menu element allows a RecipeML document to contain a collection of recipes, usually organized as a multi-course meal.


<!ELEMENT menu (head, description*, recipe*)>

The menu element contains:


<!ATTLIST menu 
	%measurement.att; >

See Common Attributes and Measurement Attributes.


Example 1.3
<menu xml:lang="en-US">
    <title>Easy Luncheon for Four</title>
    Keeping your party small allows time for good conversation
    or business planning.
  <recipe><head><title>Carrot Soup</title></head>
    . . .
  <recipe><head><title>Chicken Salad in Pineapple Shells</title></head>
    . . .
  <recipe><head><title>Old Fashioned Cheesecake</title></head>
    . . .

1.4 recipe Element

The recipe element contains the content of a recipe.


<!ELEMENT recipe (head, description*, equipment?, ingredients, directions, 
	nutrition?, diet-exchanges?)>

The recipe element must contain:


<!ATTLIST recipe 
	%measurement.att; >

See Common Attributes and Measurement Attributes.

2. Head Elements

2.1 head Element

The head element contains elements containing the descriptive information which applies to a recipe or menu as a whole. It is found in the recipe and menu elements.


<!ELEMENT head (title, subtitle?, version?, source?, categories?, 
preptime*, yield?)>

The head element contains:




Example 2.1
  . . . head content . . .

2.2 title Element

The title element contains the title of the recipe. Unlike the title element in HTML ([HTML]), the content of the RecipeML title element is part of the flow of text and is to be displayed as part of the document.


<!ENTITY % inline.class 'span | frac | sep'>

<!ELEMENT title (#PCDATA | brandname | %inline.class;)*>

The title element contains character data as defined in [XML] section 2.4, intermingled with the following elements in any order:


<!ATTLIST title
    %common.att; >

See Common Attributes.


Example 2.2
<title>Elm's Wicked Zucchini Bread</title>

2.3 subtitle Element

The subtitle element contains an additional title for the recipe, often a translation of the content of the title element into a different language.


<!ENTITY % inline.class 'span | frac | sep'>

<!ELEMENT subtitle (#PCDATA | brandname | %inline.class;)*>

The subtitle element contains character data as defined in [XML] section 2.4, intermingled with the following elements in any order:


<!ATTLIST subtitle
    %common.att; >

See Common Attributes.


Example 2.3
<recipe xml:lang="en">
. . .
<title xml:lang="it">Pasta con Aglio e Olio</title>
<subtitle>Pasta with Garlic and Oil</subtitle>
. . .

2.4 version Element

The version element, if present, contains some version identifier for the recipe itself. This would usually take the form of a software revision number (i.e., "1.2"), but can be any string. The content of the version element is typically not displayed as part of the rendered output of the RecipeML document (see rendering), but there is no restriction on this.


<!ELEMENT version (#PCDATA)>

The version element contains character data as defined in [XML] section 2.4.


<!ATTLIST version
    %common.att; >

See Common Attributes.


Example 2.4

<version>Thanksgiving, 1999</version>

<version>with Jill's changes</version>

2.5 source Element

The source element contains credit or source information for the recipe. If displayed as part of the rendered output of the RecipeML document (see rendering), the content normally appears as a footnote.


<!ELEMENT source (#PCDATA | srcitem)*>

The source element contains character data as defined in [XML] section 2.4, intermingled with the following:

@@ need to include %inline.class; in the element content.


<!ATTLIST source
    %common.att; >

See Common Attributes.


Example 2.5
<source>Republished from <span class="booktitle">To Serve Man</span> Copyright &copy; 1958, 
Twilight Press, Los Angeles, CA.</source>

2.6 srcitem Element

The srcitem element is used to further "chunk" the content of the source element so that it may be more usable as machine-processable metadata (see meta element). Its use is optional, though recommended.

The content of srcitem elements will typically be treated as an "inline" element as opposed to a "block" style element. The element content will typically not be rendered differently than surrounding text inside its parent source element, however, for example, a srcitem element with a type attribute value of "DC.Title" might be rendered in italics. See the section on Rendering and Style Sheets.


<!ENTITY % inline.class 'span | frac | sep'>

<!ELEMENT srcitem (#PCDATA | %inline.class;)*>

The srcitem element contains character data as defined in [XML] section 2.4, intermingled with the following elements in any order:


<!ATTLIST srcitem
    type CDATA #IMPLIED >
type (optional)
Identification of the type of content in the srcitem element. Recommended values are Dublin Core element names, i.e., DC.Title, DC.Creator, DC.Publisher, DC.Contributor, DC.Rights, DC.Date, DC.Identifier. See the description of the meta element for more information on the Dublin Core.

Also see Common Attributes.


Example 2.6
<source>Republished from <srcitem type="DC.Title">To Serve Man</srcitem>
  <srcitem type="DC.Rights">Copyright &copy; 1958</srcitem>,
  <srcitem type="DC.Publisher">Twilight Press, Los Angeles, CA.</srcitem>

0.0 xxxx Element

The xxxx element contains


<!ENTITY % inline.class 'span | frac | sep'>

<!ELEMENT xxxx (#PCDATA | %inline.class;)*>

The xxxx element contains character data as defined in [XML] section 2.4, intermingled with the following elements in any order:


<!ATTLIST xxxx
    %common.att; >

See Common Attributes.


Example 0.0

3. Equipment Division Elements

4. Ingredient Division Elements

5. Direction Division Elements

6. Nutrition and Diet-Exchange Elements

7. Measurement and Utility Elements

7.1 description Element

The description element contains some text (typically one or two paragraphs) that serves as a prose introduction to the recipe. The text can describe the flavor or appearance of the food that the recipe is used to create, comment on the preparation process (easy, quick, etc.), or discourse on the origin of the recipe.

In the rendition of a RecipeML document, a description traditionaly appears following the title and before the body. The description element can also be used inside an equip-div, ing-div or dir-div to describe the contents of that division.


<!ENTITY % inline.class 'span | frac | sep'>
<!ENTITY % measure.class 'amt | time | temp'>

<!ELEMENT description (#PCDATA | %measure.class; | %inline.class;)*>

The description element contains character data as defined in [XML] section 2.4, intermingled with the following elements in any order:


<!ATTLIST description
    %common.att; >

See Common Attributes.


Example 7.1

7.2 note Element

The note element contains text (usually about a paragraph) that can serve as additional information to which the reader's attention should be drawn. Note content usually takes the form of an admonition (i.e., a note or warning), tip, hint, suggestion, variation, or recommended technique. The type of note should be indicated in the elements type attribute (see below).

Notes can appear amongst (though not within) ingredients (ings), direction steps, and tool elements in the equipment section.


<!ENTITY % inline.class 'span | frac | sep'>
<!ENTITY % measure.class 'amt | time | temp'>

<!ELEMENT note (#PCDATA | %measure.class; | %inline.class;)*>

The note element contains character data as defined in [XML] section 2.4, intermingled with the following elements in any order:


<!ATTLIST note
    type CDATA #IMPLIED >
type (optional)
Identification of the type of content in the note element. Recommended values are Note, Tip, Hint, Suggestion, Variation, Technique, or Warning.

Also see Common Attributes.


Example 7.2

7.3 amt Element

The amt element is used to contain information about some amount, typically that of an ingredient. The amt element most commonly (in fact, almost always) appears in the description of an ingredient (the ing element); however, the amt element occurs in other places where an amount might appear in the text of a recipe (see the examples below).

The content of the amt element has several parts; each part is optional (athough, the amt element, when present, should contain at least one part). The first part is either qty or range.


<!ELEMENT amt ((qty | range)?, size?, unit?, size?)>

The amt element contains:


    variation CDATA #IMPLIED >
variation (optional)

Also see Common Attributes and Measurement Attributes.


Example 7.3

This is simply the quantity "3", as in the ingredient description: "3 apples."


specifies the range "3 to 4."

An amt can be used to specifiy a size instead of a quantity or range:


could be used in "small apple." A quantity of "1" is to be assumed by the processing software when qty or range is not specified.

A quantity (or range) can be combined with a size:


as in "3 small apples."

A unit may also be specified with the unit element:


qty (or range), size and unit can be used together:


Size can be more specific:


as in "3 250 ml cans."

A size can also be specified after the unit:


as in "3 cans (250 ml each)."

7.4 qty Element

The qty (quantity) element contains a scalar value. A scalar value is some number independent of unit. To associate a quantity with a unit, see amt, size, time, and temp.

Although the DTD allows any number of frac elements to be interspersed in the content of the qty element, this specification limits the number of frac elements contained in a qty element to one. (To specify a range of values, the range element can be used in place of qty in most instances.)


<!ELEMENT qty (#PCDATA | frac)*>

The qty element contains character data as defined in [XML] section 2.4, with the optional inclusion of one frac element.


    %core.att; >

See Core Attributes.


Example 7.4

The quantity "3:"


A qty can contain a fraction. "3 1/2" could be represented:


7.5 range, q1, and q2 Elements

The range element contains a pair of scalar values (cf. qty) which is used to indicate a range such as "3 to 4." The first value in the range is contained in a q1 element, the second in q2. The content model and attributes for q1 and q2 are the same as for the qty element. The q1 and q2 elements in a range may be optionally separated by a sep element.

To associate a range of quantities with a unit, see amt, size, time, and temp.


<!ELEMENT range (q1, sep?, q2)>
<!ELEMENT q1 (#PCDATA | frac)*>
<!ELEMENT q2 (#PCDATA | frac)*>

The range element contains:


<!ATTLIST range
    %core.att; >
    %core.att; >
    %core.att; >

See Core Attributes.


Example 7.5

The range "3 to 5:"


7.13 sep Element

The sep (separator) element is used to contain punctuation or word(s) appearing between elements. The elements surrounding the sep element are usually a pair of values that form a fraction (see frac) or a range (see range). The sep element could also contain a list separator such as a comma (",") in between pairs of list items, such as amt, time or temp elements.

The reason for an element type for separator strings is that this type of character is often inserted into the rendered output by a style sheet. For example, for a frac element, a style sheet to be applied to a RecipeML document might insert a slash ("/") character between the numerator and denominator (n and d elements). Such a style sheet would most likely not pass through the contents of a sep element in a frac element to be rendered, instead substituting its own separator character. The sep element allows those recipe authors who wish to include separator content to do so.

All style sheets writen to be applied to RecipeML content should insert appropriate separator characters, if the style sheet language/system being used has this capabitlity, where sep elements may appear but have been omitted. It is up to the style sheet author as to whether the style sheet(s) will substitute (override) separator content where a sep element is present.



The sep element contains character data as defined in [XML] section 2.4.


    %common.att; >

See Common Attributes.


Example 7.13

Separator in a fraction:


might render as "1/2."

Separator in a range:


might render as "3-4" -- however:

<range><q1>3</q1><sep> to </sep><q2>4</q2></range>

might render as "3 to 4."

Separators in a list:

<amt><qty>3</qty></amt><sep>, </sep>
<amt><qty>4</qty></amt><sep>, or </sep>

might render as "3, 4, or 5."

Appendix A. DTDs

This appendix is normative.

A.1 Document Type Definition

A.2 Entity Sets

The RecipeML entity sets are the same as for HTML 4, but have been modified to be valid XML 1.0 entity declarations. Note the entity for the Euro currency sign (&euro; or &#8364; or &#x20AC;) is defined as part of the special characters.

Appendix B. References

B.1 Normative References

"Date and Time Formats", W3C Note, M. Wolf and C. Wicksteed, 15 September 1997. Revised 27 August 1998. This document is
The Dublin Core. For more information refer to
"Codes for the representation of names of languages", ISO 639:1988. For more information, consult Refer also to
"Codes for the representation of names of countries and their subdivisions -- Part 1: Country codes", ISO 3166-1:1997.
"Data elements and interchange formats -- Information interchange -- Representation of dates and times", ISO 8601:1988.
"Tags for the Identification of Languages", H. Alvestrand, March 1995. RFC1766 is expected to be updated by, currently a work in progress.
"RFC2119: Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997.
Available at:
"RFC2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998.
This document updates RFC1738 and RFC1808.
Available at:
"Extensible Markup Language (XML) 1.0 (Second Edition)", T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, 6 October 2000.
Latest version available at:

B.2 Informative References

"Cascading Style Sheets, level 1", H. W. Lie and B. Bos, 17 December 1996. Revised 11 January 1999. This document is
"Cascading Style Sheets, level 2 (CSS2) Specification", B. Bos, H. W. Lie, C. Lilley, I. Jacobs, 12 May 1998.
Latest version available at:
"Document Object Model (DOM) Level 1 Specification", Lauren Wood et al., 1 October 1998.
Latest version available at:
"HTML 4.01 Specification", D. Raggett, A. Le Hors, I. Jacobs, 24 December 1999.
Latest version available at:
List of registered content types (MIME types). Download a list of registered content types from
"RFC2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", N. Freed and N. Borenstein, November 1996.
Available at Note that this RFC obsoletes RFC1521, RFC1522, and RFC1590.
"RFC3023: XML Media Types", M. Murata, S. St.Laurent, D. Kohn, January 2001.
Available at: Note that this RFC obsoletes RFC2376.
"Namespaces in XML", T. Bray, D. Hollander, A. Layman, 14 January 1999.
XML namespaces provide a simple method for qualifying names used in XML documents by associating them with namespaces identified by URI.
Latest version available at:

Valid XHTML 1.0!