RecipeML Specification

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.

0. Introduction
- 0.1 Specification Approach
- 0.2 Terminology
- 0.3 Generally Applicable Attributes
- 0.4 Internet Media Type
1. Structure Elements
- 1.1 recipeml Element
- 1.2 meta Element
- 1.3 menu Element
- 1.4 recipe Element
2. Head Elements
- 2.1 head Element
- 2.2 title Element
- 2.3 subtitle Element
- 2.4 version Element
- 2.5 source Element
- 2.6 srcitem Element
- 2.7 categories Element
- 2.8 cat Element
- 2.9 preptime Element
- 2.10 yield Element
3. Equipment Division Elements
- 3.1 equipment Element
- 3.2 equip-div Element
- 3.3 tool Element
4. Ingredient Division Elements
- 4.1 ingredients Element
- 4.2 ing-div Element
- 4.3 ing Element
- 4.4 alt-ing Element
- 4.5 modifier Element
- 4.6 item Element
- 4.7 prep Element
- 4.8 ing-note Element
- 4.9 prodcode Element
5. Direction Division Elements
- 5.1 directions Element
- 5.2 dir-div Element
- 5.3 step Element
- 5.4 substep Element
- 5.5 action Element
- 5.6 condition Element
- 5.7 setting Element
- 5.8 toolref Element
- 5.9 ingref Element
- 5.10 steptime Element
6. Nutrition and Diet-Exchange Elements
- 6.1 nutrition Element
- 6.2 nutrient-group Element
- 6.3 nutrient Element
- 6.4 n-name Element
- 6.5 percent Element
- 6.6 diet-exchanges Element
- 6.7 exchange Element
7. Measurement and Utility Elements
- 7.1 description Element
- 7.2 note Element
- 7.3 amt Element
- 7.4 qty Element
- 7.5 range, q1, and q2 Elements
- 7.6 size Element
- 7.7 unit Element
- 7.8 time Element
- 7.9 timeunit Element
- 7.10 temp Element
- 7.11 tempunit Element
- 7.12 frac, n, and d Elements
- 7.13 sep Element
- 7.14 brandname, mfr, and product Elements
- 7.15 span Element
Appendix A. DTDs
Appendix B. References

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].

Internationalization (i18n) Attributes

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

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.

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:

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.

Content

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

The recipeml element can contain:

zero or more meta elements, followed by
one (and only one) of menu or recipe.

Attributes

<!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.

Examples

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

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.

Content

<!ELEMENT meta EMPTY>

The meta element is empty.

Attributes

<!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
	content	CDATA	#REQUIRED	
	scheme	CDATA	#IMPLIED	
	lang	CDATA	#IMPLIED >

name: 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.".
content: 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.

Examples

<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."/>

Examples

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

1.4 `recipe` Element

The recipe element contains the content of a recipe.

Content

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

The recipe element must contain:

one head element, followed by
zero or more description elements, followed by
an optional equipment element, followed by
one ingredients element, followed by
one directions element, followed by
an optional nutrition element, followed by
an optional diet-exchanges element.

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.

Content

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

The head element contains:

one (and only one) title element, followed by
an optional subtitle element, followed by
an optional version element, followed by
an optional source element, followed by
an optional categories element, followed by
zero or more preptime elements, followed by
an optional yield element.

Attributes

None.

Examples

<head>
  . . . head content . . .
</head>

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.

Content

<!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:

zero or more brandname elements,
zero or more span elements,
zero or more frac elements,
zero or more sep elements.

Attributes

<!ATTLIST title
    %common.att; >

See Common Attributes.

Examples

<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.

Content

<!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:

zero or more brandname elements,
zero or more span elements,
zero or more frac elements,
zero or more sep elements.

Attributes

<!ATTLIST subtitle
    %common.att; >

See Common Attributes.

Examples

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

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.

Content

<!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:

zero or more span elements,
zero or more frac elements,
zero or more sep elements.

Attributes

<!ATTLIST srcitem
    %common.att;
    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.

Examples

<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>
</source>

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.

Content

<!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:

zero or more amt elements,
zero or more time elements,
zero or more temp elements,
zero or more span elements,
zero or more frac elements,
zero or more sep elements.

Attributes

<!ATTLIST description
    %common.att; >

See Common Attributes.

Examples

<description>
</description>

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.

Content

<!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:

zero or more amt elements,
zero or more time elements,
zero or more temp elements,
zero or more span elements,
zero or more frac elements,
zero or more sep elements.

Attributes

<!ATTLIST note
    %common.att;
    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.

Examples

<note>
</note>

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.

Content

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

The amt element contains:

either a qty element, or a range element, or neither, followed by
an optional size element, followed by
an optional unit element, followed by
an optional size element.

Attributes

<!ATTLIST amt
    %common.att;
    %measurement.att;
    variation CDATA #IMPLIED >

variation (optional): @@TBD.

Also see Common Attributes and Measurement Attributes.

Examples

<amt><qty>3</qty></amt>

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

<amt><range><q1>3</q1><q2>4</q2></range></amt>

specifies the range "3 to 4."

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

<amt><size>small</size></amt>

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:

<amt><qty>3</qty><size>small</size></amt>

as in "3 small apples."

A unit may also be specified with the unit element:

<amt><qty>3</qty><unit>cups</unit></amt>

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

<amt><qty>3</qty><size>small</size><unit>cans</unit></amt>

Size can be more specific:

<amt>
  <qty>3</qty>
  <size><qty>250</qty><unit>ml</unit></size>
  <unit>cans</unit>
</amt>

as in "3 250 ml cans."

A size can also be specified after the unit:

<amt>
  <qty>3</qty>
  <unit>cans</unit>
  <size><qty>250</qty><unit>ml</unit>each</size>
</amt>

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.)

Content

<!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.

Attributes

<!ATTLIST qty
    %core.att; >

See Core Attributes.

Examples

The quantity "3:"

<qty>3</qty>

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

<qty>3<frac><n>1</n><d>2</d></frac></qty>

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.

Content

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

The range element contains:

one (and only one) q1 element, followed by
an optional sep element, followed by
one (and only one) q2 element.

Attributes

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

See Core Attributes.

Examples

The range "3 to 5:"

<range><q1>3</q1><q2>5</q2></range>

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.

Content

<!ELEMENT sep (#PCDATA)>

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

Attributes

<!ATTLIST sep
    %common.att; >

See Common Attributes.

Examples

Separator in a fraction:

<frac><n>1</n><sep>/</sep><d>2</d></frac>

might render as "1/2."

Separator in a range:

<range><q1>3</q1><sep>-</sep><q2>4</q2></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>
<amt><qty>5</qty></amt>

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

Appendix A. DTDs

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 (€ or € or €) is defined as part of the special characters.

Recipe Markup Language (RecipeML)

Working Draft 8 April 2001 (incomplete)

Abstract

Status of this document

Contents

0. Introduction

0.1 Specification Approach

0.2 Terminology

0.3. Generally Applicable Attributes

Core Attributes

Internationalization (i18n) Attributes

Common Attributes

Measurement Attributes

Division Attributes

0.4 Internet Media Type

1. Structure Elements

1.1 recipeml Element

Content

Attributes

Examples

1.2 meta Element

Content

Attributes

Examples

1.3 menu Element

Content

Attributes

Examples

1.4 recipe Element

Content

Attributes

2. Head Elements

2.1 head Element

Content

Attributes

Examples

2.2 title Element

Content

Attributes

Examples

2.3 subtitle Element

Content

Attributes

Examples

2.4 version Element

Content

Attributes

Examples

2.5 source Element

Content

Attributes

Examples

2.6 srcitem Element

Content

Attributes

Examples

0.0 xxxx Element

Content

Attributes

Examples

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

Content

Attributes

Examples

7.2 note Element

Content

Attributes

Examples

7.3 amt Element

Content

Attributes

Examples

7.4 qty Element

Content

Attributes

1.1 `recipeml` Element

1.2 `meta` Element

1.3 `menu` Element

1.4 `recipe` Element

2.1 `head` Element

2.2 `title` Element

2.3 `subtitle` Element

2.4 `version` Element

2.5 `source` Element

2.6 `srcitem` Element

0.0 `xxxx` Element

7.1 `description` Element

7.2 `note` Element

7.3 `amt` Element

7.4 `qty` Element

7.5 `range`, `q1`, and `q2` Elements

7.13 `sep` Element