hrecipe: Difference between revisions
(→Schema: author reused from hAtom) |
(→Field details: author reused from hAtom) |
||
Line 72: | Line 72: | ||
=== Field details === | === Field details === | ||
Class names | Class names <code>photo</code> and <code>note</code> are reused from [[hCard]], <code>num</code>, <code>unit</code> and <code>item</code> are reused from [[measure]], <code>author</code> and <code>published</code> are reused from [[hAtom]]. | ||
The fields of the hRecipe schema represent the following: | The fields of the hRecipe schema represent the following: |
Revision as of 17:13, 6 January 2009
<entry-title>hRecipe 0.1</entry-title> This document represents a draft microformat specification. Although drafts are somewhat mature in the development process, the stability of this document cannot be guaranteed, and implementers should be prepared to keep abreast of future developments and changes. Watch this wiki page, or follow discussions on the #microformats IRC channel to stay up-to-date.
hRecipe is a simple, open, distributed format, suitable for embedding information about recipes for cooking in (X)HTML, Atom, RSS, and arbitrary XML. hRecipe is one of several microformats open standards. This page and Microformat is in the public domain.
hRecipe Microformat Draft Specification
Editor
Authors
Contributors
Andy Mabbett, Frances Berriman, Cameron Perry, John LeMasney, Tantek Çelik, SudarshanP, Ciaran McNulty, Lee Jordan, Robert Bachmann, jeffmcneill, Manu Sporny, Ryan King, HollyMarieKoltz, Straup, Christophe Ducamp, Mercman, Yde, Ameer Dawood, Scottk, Lee Jordan, MonroAlmon, EstevaoSamuel, Brian Suda, SteveL, JohnLeMasney,
Microformats #Copyright and #Patents statements apply.
Introduction
The hRecipe microformat is designed for the mark-up of instructions for creating meals, drinks or food-based items.
It is difficult for a browser to extract semantic information about a recipe described on a web page. Metadata such as author and name and details such as ingredients, method, preparation time etc provide relevant information about the recipe.
Having such information marked up can provide a number of benefits to the viewer. If a web browser understands that a particular web page contains a recipe with specific characteristics, it can produce richer interactions. For example, specific searches may be performed for ingredients or authors via general search services such as Google and Wikipedia. Additionally, classification by crawlers can become more accurate. If there are 20 recipes found on a page, and they all contain a certain ingredient, it can be assumed that the page is not only about cooking, but also about that particular ingredient.
In order to enable and encourage the sharing, distribution, syndication, and aggregation of recipes, the authors propose the hRecipe microformat, an open standard for distributed recipe metadata. The authors have researched both numerous recipe-examples in the wild and earlier attempts at recipe-formats, and have designed hRecipe around a simple minimal schema for recipe content. Feedback is encouraged on the hRecipe feedback page.
Inspiration and Acknowledgments
Many thanks to the various individuals that did research and proposed ideas and discussion related to the hRecipe-format and recipes in general.
Scope
Recipes consistently share several common elements and fields. Where possible hRecipe has been based on this minimal common subset.
Out of scope
Elements that are too specific have been omitted from hRecipe. It is important that hRecipe be kept simple and minimal from the start. Additional features can be added as deemed necessary by practical implementation experience.
Format
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 RFC 2119.
In General
The hRecipe format is based on a set of fields common to numerous recipe sites and formats in use today on the web. Where possible field names have been chosen based on those defined by related microformat standards.
Schema
The hRecipe schema consists of the following elements:
- hrecipe
- recipe-title required. text.
- recipe-summary. optional. text.
- author. optional. 1 or more. re-used from hAtom using hCard.
- published. optional. re-used from hAtom.
- photo. optional. 1 or more. using any element containing a URL, such as IMG. re-used from hCard.
- ingredient required. 1 or more. text with optional valid (x)HTML markup.
- method. optional. text with optional valid (x)HTML markup.
- yield. optional. text.
- preparation-time. optional. 1 or more. text (see ISO-31-1 duration brainstorming).
- note. optional. text. re-used from hCard.
- tag. optional. 1 or more. re-used from rel-tag.
- nutrition. optional. 1 or more.
- num, unit and item. optional. re-used from measure.
Field details
Class names photo
and note
are reused from hCard, num
, unit
and item
are reused from measure, author
and published
are reused from hAtom.
The fields of the hRecipe schema represent the following:
hRecipe
A hRecipe is used to identify and describe values and metadata typically associated with a recipe.
- A hRecipe element is identified by class name
hrecipe
recipe-title
The title of a single recipe is a short textual description used to identify the work among interested parties. This can be the name of a meal or a short description regarding it's ingredients.
- The element is identified by class name
recipe-title
. - A Recipe MUST include a
recipe-title
.
recipe-summary
The summary provides a short introduction or an accompanying statement about the recipe.
- The element is identified by the class name
recipe-summary
. - A Recipe MAY include a
recipe-summary
.
author
An Author is the person who authored the recipe.
- The element is identified by class name
author
. - A Recipe MAY include one or more
author
elements. - The contents of the element MUST follow the conventions outlined in hCard.
published
The date the recipe was published.
- The element is identified by the class name
published
. - A Recipe MAY include a
published
date. - The element MUST follow the conventions outlined in hAtom.
- The datetime-design-pattern SHOULD be used to encode the published datetime.
photo
Accompanying image.
- The element is identified by the class name
photo
. - A Recipe MAY include one or more photo elements.
- The element SHOULD use an <img> element.
- The element MAY use any other element that contains a URL, such as <a> or <object>, but it is not recommended.
- The contents of the element MUST follow the conventions outlined in hCard.
ingredient
Describes one or more ingredients used in the recipe.
- The element is identified by the class name
ingredient
. - A Recipe MUST have one or more
ingredient
s. - The field MAY include valid HTML markup (e.g. a list of ingredients).
- The element MAY include the fields
num
,unit
anditem
following the conventions outlined in measure. In this case each ingredient should be marked up with it's owningredient
element. - The element MAY include a
note
detailing the ingredient, which MUST follow the conventions outlined in hCard.
method
The method of the recipe.
- The element is identified by the class name
method
. - A Recipe MAY include a
method
. - The field MAY include valid HTML markup e.g. paragraphs or a list for steps in the method.
yield
Specifies the quantity produced by the recipe, like how many persons it satisfyies or how many pieces can be made of it.
- The element is identified by the class name
yield
. - A Recipe MAY include a
yield
.
preparation-time
The time it takes to prepare the meal described by the recipe. Multiple preparation-time fields can be used to denote e.g. time for preparing a dough, time needed for the dough to raise, time to bake the dough, time for decorating the cake etc.
- The element is identified by the class name
preparation-time
. - A Recipe MAY include one or more
preparation-time
s. - Each Preparation Time element MAY include a
note
to specify their respective purpose, which MUST follow the conventions outlined in hCard.
nutrition
Nutritional information like calories, fat, dietary fiber etc.
- The element is identified by class name
nutrition
. - A Recipe MAY include one or more
nutrition
elements. - The element MAY include the fields
num
,unit
anditem
following measure.
Parser Processing Notes
None so far.
Semantic XHTML Design Principles
Note: the Semantic XHTML Design Principles were written primarily within the context of developing hCard and hCalendar, thus it may be easier to understand these principles in the context of the hCard design methodology (i.e. read that first). Tantek
XHTML is built on XML, and thus XHTML based formats can be used not only for convenient display presentation, but also for general purpose data exchange. In many ways, XHTML based formats exemplify the best of both HTML and XML worlds. However, when building XHTML based formats, it helps to have a guiding set of principles.
- Reuse the schema (names, objects, properties, values, types, hierarchies, constraints) as much as possible from pre-existing, established, well-supported standards by reference. Avoid restating constraints expressed in the source standard. Informative mentions are ok.
- For types with multiple components, use nested elements with class names equivalent to the names of the components.
- Plural components are made singular, and thus multiple nested elements are used to represent multiple text values that are comma-delimited.
- Use the most accurately precise semantic XHTML building block for each object etc.
- Otherwise use a generic structural element (e.g.
<span>
or<div>
), or the appropriate contextual element (e.g. an<li>
inside a<ul>
or<ol>
). - Use class names based on names from the original schema, unless the semantic XHTML building block precisely represents that part of the original schema. If names in the source schema are case-insensitive, then use an all lowercase equivalent. Components names implicit in prose (rather than explicit in the defined schema) should also use lowercase equivalents for ease of use. Spaces in component names become dash '-' characters.
- Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use
<abbr>
instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human readable equivalent into the element itself. Further informative explanation of this use of<abbr>
: Human vs. ISO8601 dates problem solved
More Semantic Equivalents
For some properties there is a more semantic equivalent, and therefore they get special treatment, e.g.:
- For "photo", use
<img class="photo" src="..." alt="" />
Language
- To explicitly convey the natural language that an recipe is written in, use the standard (X)HTML 'lang' or 'xml:lang' attribute on the element with class="hrecipe"
- e.g.
<p>I like <span class="hrecipe" lang="de"><span class="fn">Kartoffelknödel</span></span> best.</p>
- e.g.
- If portions of an hRecipe (e.g. an ingredient name) are in a different language to the rest of the hRecipe, use the 'lang' or 'xml:lang' attribute on those portions.
- hRecipe parsers which need to handle the native language of hRecipe MUST process the standard (X)HTML 'lang' or 'xml:lang' attribute as specified.
- hRecipe parsers which need to handle native language MAY traverse up the DOM to discover the native language of the page and apply that to the hRecipe if no other language is specified on the hRecipe.
Human vs. Machine Readable
If an <abbr>
element is used for a property, then its 'title
' attribute is used for the value of the property, instead of the contents of the element, which can then be used to provide a user-friendly alternate presentation of the value.
If an <a>
element is used for one or more properties, it MUST be treated as follows:
- For the 'photo' property and any other property that takes a URL as its value, the
href="..."
attribute provides the property value. - For other properties, the element's content is the value of the property.
If an <img>
element is used for the 'photo' property, it MUST use the property value provided by the src="..."
attribute as property value.
If an <object>
element is used for the 'photo' property, it MUST use the property value provided by the data="..."
attribute as property value.
Notes
This section is informative.
- By marking up audio content with the hAudio microformat, the expectation is communicated that information about the content MAY be indexed. This has no impact on the copyright of the content itself which the publisher may explicitly specify using the rel-license microformat.
XMDP Profile
<dl class="profile"> <dt>class</dt> <dd><p> <a rel="help" href="http://www.w3.org/TR/html401/struct/global.html#adef-class"> HTML4 definition of the 'class' attribute.</a> This meta data profile defines some 'class' attribute values (class names) and their meanings as suggested by a <a href="http://www.w3.org/TR/WD-htmllink-970328#profile"> draft of "Hypertext Links in HTML"</a>.</p> <dl> <dt>hrecipe</dt> <dd> Used to identify and describe metadata associated with instructions for creating meals, drinks or food-based items. </dd> <dt>recipe-title</dt> <dd> The title of the recipe. </dd> <dt>recipe-summary</dt> <dd> The summary provides a short introduction or an accompanying statement about the recipe. </dd> <dt>author</dt> <dd> The person who authored the recipe.. </dd> <dt>published</dt> <dd> The date that the recipe was made available to the public. </dd> <dt>photo</dt> <dd> Accompanying image. </dd> <dt>ingredient</dt> <dd> Describes the ingredient(s) used in the recipe. </dd> <dt>method</dt> <dd> The method of the recipe. </dd> <dt>yield</dt> <dd> Specifies the quantity produced by the recipe. </dd> <dt>preparation-time</dt> <dd> The time it takes to prepare the meal described by the recipe. </dd> <dt>nutrition</dt> <dd> Nutritional information like calories, fat, dietary fiber etc. </dd> </dl> </dd> </dl>
Examples
This section is informative.
Here will be a few examples of recipes, from real web sites, showing how they could be easily enhanced to use hRecipe. In the meantime the following contrieved example will have to do.
<div class="hrecipe"> <p class="recipe-title">Pommes Frites</p> <p class="recipe-summary"> Pommes frites originate in outer space. They are served hot.<br /> This recipe is only an example. Don't try this at home! </p> <p class="vcard fn">Thomas Loertsch</p> <p>Published <abbr class="published" title="2008-10-14T10:05:37-01:00">14. Oct 2008</abbr></p> <img src="/img/pommes.png" class="photo" width="100" height="100" alt="Pommes Frites"/> <p class="ingredient hmeasure"> <span class="num">500</span> <span class="unit">gramme</span> <span class="item">potatoes</span>, <span class="note">hard cooking</span>. </p> <ul class="method"> <li>First wash the potatoes.</li> <li>Then slice and dice them and put them in boiling fat.</li> <li>After a few minutes take them out again.</li> </ul> <p>Enough for <span class="yield">12</span> children.</p> <p class="preparation-time hmeasure">Preparation time is approximately <span class="num">90</span> <abbr class="unit" title="minutes">min</abbr>. </p> <p class="preparation-time hmeasure">Add <span class="num">5</span> <abbr class="unit" title="minutes" >min</abbr> for <span class="note">preparing the Ketchup</span>. </p> <p>This recipe is <a href="http://www.eut.de/tags/difficulty/easy" rel="tag">easy</a> and <a href="http://www.eut.de/tags/tastyness/delicious" rel="tag">delicious</a>.</p> <p class="nutrition hmeasure"> Pommes Frites have more than <span class="num">1000</span> <span class="unit">Joule</span> <span class="type">Energy</span>. </p> </div>
Examples in the wild
This section is informative.
Wild Mushroom, Pancetta & Truffle Risotto by Toby Inkster
- Marked up as hRecipe using the September 2007 draft format
- RecipeBook XML output from Cognition.
- RDF/XML and Turtle output from Cognition.
Implementations
This section is informative.
- Cognition
As of September 2008, Cognition has experimental support for this format. (Details of support.) Recipes may be exported in RecipeBook XML format or RDF.
References
Normative References
Informative References
- CSS1
- ISO.8601.1988
- International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO Standard 8601, June 1988.
- W3C NOTE-datetime-19980827
- W3C Patent Policy
- Other recipe metadata efforts. See recipe-formats.
- grouping-examples
- grouping-brainstorming
- XOXO
Copyright
This document and hAudio specification was placed into the public domain on 2008-11-14 by the authors. There are no usage, distribution, re-printing, or any other restrictions of any kind with regards to the text or content of this specification.
Patents
This specification is subject to a royalty free patent policy, e.g. per the W3C Patent Policy, and IETF RFC3667 & RFC3668.
Public Domain Release
The authors and editors of this page due hereby relinquish their copyright on the document and release the text of this page into the public domain.
Work in progress
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.
- hRecipe issues - issues regarding the hRecipe draft
- hRecipe feedback - general feedback regarding hRecipe
Per the microformats process, the recipe effort developed
- recipe-examples
- recipe-formats
- recipe-brainstorming (see also recipe-brainstorming-archive)
- recipe-issues
towards the development of this draft.