Copyright © 2002 FormatData, All Rights Reserved. Software licensing rules apply.
This specification defines the Recipe Markup Language (RecipeML), a means to represent food preparation recipes in the Extensible Markup Language (XML).
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 http://www.formatdata.com/dessert/forum.html.
Please report errors in this document to recipeml@formatdata.com.
equipment Elementequip-div Elementtool Elementdirections Elementdir-div Elementstep Elementsubstep Elementaction Elementcondition Elementsetting Elementtoolref Elementingref Elementsteptime Elementnutrition Elementnutrient-group Elementnutrient Elementn-name Elementpercent Elementdiet-exchanges Elementexchange Elementdescription Elementnote Elementamt Elementqty Elementrange, q1, and q2 Elementssize Elementunit Elementtime Elementtimeunit Elementtemp Elementtempunit Elementfrac, n, and d Elementssep Elementbrandname, mfr, and product Elementsspan ElementRecipeML 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)
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.
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:
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].
id must be unique across all elements in a single document and are of type ID as defined in [XML] section 3.3.1.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.title are of type CDATA as defined in [XML] section 3.3.1.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.Example:
<title xml:lang="es">Arroz con Pollo</title>
This attribute group applies to most RecipeML elements. It includes the core attributes (id, class, title) and the i18n attributes (xml:lang).
system attribute in the contained element). The possible values are:
"US""Imperial""US" in some volume units; weights (mass) and lengths are the same as in "US"."metric""SI""other"system attribute is not present, the measurement system is undefined. Each RecipeML implementation may choose to use this information as it sees fit.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.
"main"type="main" and the frosting group type="titled"."variation"type="variation". There can be more than one variation division of each type (equipment, ingredients, directions) in a recipe."titled"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".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.
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:
application/x-recipe+xmlFormatData plans to register under the vendor tree the MIME type:
application/vnd.recipe+xmlIn the future, FormatData may register a MIME type in the IETF tree, if the IETF sees fit to allow this.
This section covers the elements which represent the overall structure of a RecipeML document.
recipeml ElementThe 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; >
Also see Common Attributes.
meta ElementThe 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.
<!ELEMENT meta EMPTY>
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 content CDATA #REQUIRED scheme CDATA #IMPLIED lang CDATA #IMPLIED >
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.content attribute. See the xml:lang attribute for the formatting of values.<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."/>
menu ElementThe 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:
head element, followed bydescription elements, followed byrecipe elements.<!ATTLIST menu %common.att; %measurement.att; >
See Common Attributes and Measurement Attributes.
<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>
recipe ElementThe recipe element contains the content of a recipe.
<!ELEMENT recipe (head, description*, equipment?, ingredients, directions, nutrition?, diet-exchanges?)>
The recipe element must contain:
head element, followed bydescription elements, followed byequipment element, followed byingredients element, followed bydirections element, followed bynutrition element, followed bydiet-exchanges element.<!ATTLIST recipe %common.att; %measurement.att; >
See Common Attributes and Measurement Attributes.
head ElementThe 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:
title element, followed bysubtitle element, followed byversion element, followed bysource element, followed bycategories element, followed bypreptime elements, followed byyield element.None.
title ElementThe 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:
brandname elements,span elements,frac elements,sep elements.<!ATTLIST title
%common.att; >
See Common Attributes.
subtitle ElementThe 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:
brandname elements,span elements,frac elements,sep elements.<!ATTLIST subtitle
%common.att; >
See Common Attributes.
version ElementThe 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.
source ElementThe 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:
srcitem elements.@@ need to include %inline.class; in the element content.
<!ATTLIST source
%common.att; >
See Common Attributes.
srcitem ElementThe 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:
span elements,frac elements,sep elements.<!ATTLIST srcitem
%common.att;
type CDATA #IMPLIED >
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.
categories ElementThe categories element contains a list of categories that apply to the recipe. This can be any categorization. Types of categories can be (but are not limited to) meal (e.g., dinner, lunch), course (entree, dessert), main ingredient (pasta, beef), and nation or culture of origin (also referred to as "cuisine"). See the type atttribute of the cat element for more information on types.
Also see cat element.
<!ELEMENT categories (#PCDATA | cat)*>
The categories element contains character data as defined in [XML] section 2.4, intermingled with the following elements in any order:
cat elements.<!ATTLIST categories
%common.att;
content NMTOKENS #IMPLIED >
Also see Common Attributes.
cat ElementAllows for the markup of individual categories within the content of the categories element.
<!ELEMENT cat (#PCDATA)>
The cat element contains character data as defined in [XML] section 2.4.
<!ATTLIST cat
%common.att;
type CDATA #IMPLIED >
cat element content. Some example values: meal, course, ingredient, cuisine.Also see Common Attributes.
See example 2.7 (categories element).
preptime ElementThe preptime element represents a time period involved in the preparation process.
@@TBD
<!ENTITY % time.cont '(time, (sep?, time)*)'> <!ELEMENT preptime (%time.cont;)>
The preptime element contains:
time elementssep element between any pair of time elements.<!ATTLIST preptime
%common.att;
type CDATA #REQUIRED >
Also see Common Attributes.
The yield element @@finish this paragrah
<!ELEMENT yield (#PCDATA | qty | range | unit)*>
The yield element contains character data as defined in [XML] section 2.4, intermingled with the following elements:
The DTD syntax@@(?) does not allow for character data to be mixed with element data that follows a particular structure, however, this specification mandates that there be only one qty or range element and one unit element in a yield element.
@@ fix this paragraph
<!ATTLIST yield
%common.att; >
See Common Attributes.
xxxx ElementThe 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:
span elements,frac elements,sep elements.<!ATTLIST xxxx
%common.att; >
See Common Attributes.
ingredients ElementThe contents of the ingredients element is the section of the recipe that contains the list or lists (see ing-div) of ingredients. (Alternatively, the ingredients can be listed among the steps in the directions section. See 5.1 directions element.)
@@ the ingredients element should be made optional in the recipe element in the next version
<!ELEMENT ingredients (ing-div+ | (note*, ing, (note | ing)*))>
The ingredients element must contain either:
ing-div elements,or a sequence of:
The ing and note elements can be intermixed in any order.
<!ATTLIST ingredients
%common.att;
%measurement.att; >
See Common Attributes and Measurement Attributes.
<ingredients>
<ing> . . . </ing>
. . .
<ing> . . . </ing>
</ingredients>
<ingredients>
<note> . . . </note>
<ing> . . . </ing>
<ing> . . . </ing>
. . .
<note> . . . </note>
</ingredients>
<ingredients>
<ing-div type="main">
<ing> . . . </ing>
<ing> . . . </ing>
</ing-div>
<ing-div type="titled">
<title>Pastry</title>
<ing> . . . </ing>
. . .
</ing-div>
</ingredients>
ing-div ElementThe ing-div element allows the list of ingredients to be broken up into divisions. A typical scenario in which a list of ingredients might be divided would be a recipe for a pie. The ingredients could be grouped according to the parts of the pie: the crust and the filling. See Example 4.2.
<!ELEMENT ing-div (title?, description?, note*, ing, (note | ing)*)>
The ing-div element contains:
title element, followed bydescription element, followed bya sequence of:
The ing and note elements can be intermixed in any order.
<!ATTLIST ing-div
%div.att; >
See Division Attributes.
ing ElementThe ing element contains all of the information about one ingredient in the recipe. This element has a fairly complex structure.
<!ENTITY % amt.cont '(amt, (sep?, amt)*)'> <!ENTITY % ing.cont '((%amt.cont;)?, modifier?, item, prep?, ing-note*, prodcode*)'> <!ELEMENT ing (%ing.cont;, alt-ing*)>
The ing element contains:
amt elementssep element between any pair of amt elements.modifier element, followed byitem element, followed byprep element, followed bying-note elements, followed byprodcode elements, followed byalt-ing elements.<!ATTLIST ing
%common.att;
optional (yes | no) "no" >
Also see Common Attributes.
alt-ing ElementThe alt-ing element contains the information about an ingredient which can be substituted for the ingredient contained in the ing element which contains the alt-ing element.
@@ huh? rework.
<!ENTITY % ing.cont '((%amt.cont;)?, modifier?, item, prep?, ing-note*, prodcode*)'> <!ELEMENT alt-ing (%ing.cont;)>
Content for the alt-ing element is the same as that for the ing element, without the alt-ing element at the end. See 4.3 ing Element.
<!ATTLIST alt-ing
%common.att; >
See Common Attributes.
description ElementThe 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:
amt elements,time elements,temp elements,span elements,frac elements,sep elements.<!ATTLIST description
%common.att; >
See Common Attributes.
note ElementThe 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:
amt elements,time elements,temp elements,span elements,frac elements,sep elements.<!ATTLIST note
%common.att;
type CDATA #IMPLIED >
note element. Recommended values are Note, Tip, Hint, Suggestion, Variation, Technique, or Warning.Also see Common Attributes.
amt ElementThe 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:
qty element, or a range element, or neither, followed bysize element, followed byunit element, followed bysize element.<!ATTLIST amt
%common.att;
%measurement.att;
variation CDATA #IMPLIED >
Also see Common Attributes and Measurement Attributes.
<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)."
qty ElementThe 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.
<!ATTLIST qty
%core.att; >
See Core Attributes.
range, q1, and q2 ElementsThe 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:
q1 element, followed bysep element, followed byq2 element.<!ATTLIST range
%core.att; >
<!ATTLIST q1
%core.att; >
<!ATTLIST q2
%core.att; >
See Core Attributes.
sep ElementThe 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.
<!ELEMENT sep (#PCDATA)>
The sep element contains character data as defined in [XML] section 2.4.
<!ATTLIST sep
%common.att; >
See Common Attributes.
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."
This appendix is normative.
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.
Latin-1 characters
Special characters
Symbols
