hrecipe

2009-02-26T16:12:07Z

Teddyg: /* Implementations */

<entry-title>hRecipe 0.21</entry-title>
{{Template:DraftSpecification}}
{{TOC-right}}
http://www.livingathome.de/test/recipe/hRecipe.png

[[recipe|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 ===
* [[User:ThomasLoertsch | Thomas Loertsch]] ([http://www.essen-und-trinken.de Gruner+Jahr])
=== Authors ===
* [[User:Phae|Frances Berriman]] (BBC)
* [[User:BenWard|Ben Ward]]
* [[User:TobyInk|Toby Inkster]]

=== Contributors===
[[User:AndyMabbett|Andy Mabbett]], [[User:Phae|Frances Berriman]], [[User:IamCam|Cameron Perry]], [[User:JohnLeMasney|John LeMasney]], [[User:Tantek|Tantek Çelik]], [[User:SudarshanP|SudarshanP]], [[User:CiaranMc|Ciaran McNulty]], [[User:LeeJordan|Lee Jordan]], [[User:RobertBachmann|Robert Bachmann]], [[User:JeffMcNeill|jeffmcneill]], [[User:ManuSporny|Manu Sporny]], [[User:RyanKing|Ryan King]], HollyMarieKoltz, Straup, [[User:ChristopheDucamp|Christophe Ducamp]], Mercman, [[User:Yde|Yde]], [[User:AmeerDawood|Ameer Dawood]], Scottk, [[User:Lee_Jordan|Lee Jordan]], MonroAlmon, EstevaoSamuel, [[User:Brian|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 [[recipe-feedback|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 ===

hRecipe is a format to annotate descriptions and lists of ingredients for the preparation of food and meals. Recipes consistently share several common elements and fields. hRecipe has been based on this minimal common subset.

=== Out of scope ===

Recipes that are not for stuff that's meant to be eaten by humans are out of scope.

== Format ==

{{rfc-2119-intro}}

=== 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. 
Some fields are marked ''experimental'' since they exceed the minimum set of elements needed to describe a recipe but still are very commonly used on the web. It's not sure if they are relevant enough for inclusion in the format. Implementation and general uptake of these elements will be observed and inform further decisions. So their use is not at all discouraged - but use them with care and be prepared for their eventual removal from the final spec.

=== Schema ===

The hRecipe schema consists of the following elements:

* '''hrecipe'''
** '''fn'''. required. text. the name of the recipe. re-used from [[hCard]].
** '''ingredient'''. required. 1 or more. text with optional valid (x)HTML markup.
*** '''''value''''' and '''''type'''''. optional. re-used from [[hCard]]. [experimental]
** '''''yield'''''. optional. text.
** '''''instructions'''''. optional. text with optional valid (x)HTML markup.
** '''''duration'''''. optional. 1 or more. text (see [[ISO-31-1]] duration brainstorming). re-used from [[hCalendar]].
** ''photo''. optional. 1 or more. using any element containing a URL, such as IMG. re-used from [[hCard]]. [experimental]
** ''summary''. optional. text. re-used from [[hCalendar]]. [experimental]
** ''author''. optional. 1 or more. re-used from [[hAtom]] using [[hCard]]. [experimental]
** ''published''. optional. re-used from [[hAtom]]. [experimental]
** ''nutrition''. optional. 1 or more. [experimental]
*** ''value'' and ''type''. optional. re-used from [[hCard]]. [experimental]
** ''tag''. optional. 1 or more. re-used from [[rel-tag]]. [experimental]

=== Field details ===

Class names <code>fn</code>, <code>photo</code>, <code>value</code> and <code>type</code> are reused from [[hCard]] <code>duration</code> and<code>summary</code> are reused from [[hCalendar]], <code>author</code> and <code>published</code> are reused from [[hAtom]], <code>tag</code> is reused from [[rel-tag]].

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 <code>hrecipe</code>

==== fn ====

The title of a single recipe. 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 <code>fn</code>.
* A Recipe {{must}} include a <code> fn </code>.
* 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 <code>ingredient</code>.
* A Recipe {{must}} include one or more <code>ingredient</code>s.
* The field {{may}} include valid HTML markup (e.g. a list of ingredients).
* The element {{may}} include the fields <code>value</code> and <code>type</code> following the conventions outlined in [[hCard]]. In this case each ingredient should be marked up with it's own <code>ingredient</code> element. These subelement is considered ''experimental'' and may be removed from the final specification or replaced by 'num' and 'unit' from [[measure]].

==== 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 <code>yield</code>.
* A Recipe {{may}} include a <code>yield</code>.

==== instructions ====

The method of the recipe.

* The element is identified by the class name <code>instructions</code>.
* A Recipe {{may}} include a <code>instructions</code> element.
* The field {{may}} include valid HTML markup e.g. paragraphs or a list of steps.

==== duration ====

The time it takes to prepare the meal described by the recipe. Multiple duration 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 <code>duration</code>.
* A Recipe {{may}} include one or more <code>duration</code>s.
* The element {{must}} follow the conventions outlined in [[hCalendar]].

==== photo ====

Accompanying image.

* The element is identified by the class name <code>photo</code>.
* 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]].
* The element is considered ''experimental'' and may be removed from the final specification.

==== summary ====

The summary provides a short introduction to or an accompanying statement about the recipe.

* The element is identified by the class name <code>summary</code>.
* A Recipe {{may}} include a <code>summary</code>.
* The element {{must}} follow the conventions outlined in [[hCalendar]].
* The element is considered ''experimental'' and may be removed from the final specification.

==== author ====

An Author is the person who authored the recipe.

* The element is identified by class name <code>author</code>.
* A Recipe {{may}} include one or more <code>author</code> elements.
* The contents of the element {{must}} follow the conventions outlined in [[hCard]].
* The element is considered ''experimental'' and may be removed from the final specification.

==== published ====

The date the recipe was published.

* The element is identified by the class name <code>published</code>.
* A Recipe {{may}} include a <code>published</code> date.
* The element {{must}} follow the conventions outlined in [[hAtom]].
* The [[datetime-design-pattern]] {{should}} be used to encode the published datetime.
* The element is considered ''experimental'' and may be removed from the final specification.

==== nutrition ====

Nutritional information like calories, fat, dietary fiber etc.

* The element is identified by class name <code>nutrition</code>.
* A Recipe {{may}} include one or more <code>nutrition</code> elements.
* The element {{may}} include the fields <code>value</code> and <code>type</code> following the conventions outlined in [[hCard]]. In this case each nutritional information item should be marked up with it's own <code>nutrition</code> element. These subelement is considered ''experimental'' and may be replaced by 'num' and 'unit' from [[measure]].
* The element is considered ''experimental'' and may be removed from the final specification.

==== tag ====

A keyword indicating a subject or an important aspect of the recipe like it's main ingredient, type of meal etc.

* The element is identified by class name <code>tag</code>.
* A Recipe {{may}} include one or more <code>tag</code> elements.
* The element {{must}} follow the conventions outlined in [[rel-tag]].
* The element is considered ''experimental'' and may be removed from the final specification.

=== Version history ===

* Version 0.2: From [http://microformats.org/wiki/index.php?title=hrecipe&oldid=37357 Version 0.1] some elements have been renamed to strenghten re-use of established elements: '''fn''' for '''hRecipe-title''', '''summary''' for '''hRecipe-summary''', '''duration''' for '''preparation-time''', '''value''' and '''type''' for '''num''' and '''unit'''. Also some elements have been marked '''experimental''' because of concerns of element bloat. See the [[hrecipe-issues]] page for a more thorough discussion. Draft 0.1 was already a result of long lasting efforts. Nonetheless after publishing of it there has been a lively debate about some properties. Since they mostly could be resolved version 0.2 is considered fairly stable now, although of course you never know ;-)
* Version 0.21 changed the status of ingredient/value and ingredient/type to ''experimental'', mentioning that there still is discussion if they should be replaced by 'num' and 'unit' from [[measure]] (which is still in brainstorming) .

=== Parser Processing Notes ===

None so far.

=== Semantic XHTML Design Principles ===

{{semantic-xhtml-design-principles}}

==== More Semantic Equivalents ====

For some properties there is a more semantic equivalent, and therefore they get special treatment, e.g.:

* For "photo", use <code><img class="photo" src="..." alt="" /></code>

==== 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. <code><nowiki>I like Kartoffelknödel best.</nowiki></code>
*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 <code><abbr></code> element is used for a property, then its '<code>title</code>' 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 <code><a></code> 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 <code>href="..."</code> attribute provides the property value.
# For other properties, the element's content is the value of the property.

If an <code><img></code> element is used for the 'photo' property, it {{must}} use the property value provided by the <code>src="..."</code> attribute as property value.

If an <code><object></code> element is used for the 'photo' property, it {{must}} use the property value provided by the <code>data="..."</code> attribute as property value.

=== Notes ===

This section is informative.

*Non so far.

== XMDP Profile ==

<pre>
<dl class="profile">
<dt>class</dt>
<dd>
<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>.
<dl>
<dt>hrecipe</dt>
<dd>
Used to identify and describe metadata associated with instructions for creating meals, drinks or food-based items.
</dd>
<dt>fn</dt>
<dd>
The title of the recipe.
</dd>
<dt>ingredient</dt>
<dd>
Describes the ingredient(s) used in the recipe.
</dd>
<dt>yield</dt>
<dd>
Specifies the quantity produced by the recipe.
</dd>
<dt>instructions</dt>
<dd>
The method of the recipe.
</dd>
<dt>duration</dt>
<dd>
The time it takes to prepare the meal described by the recipe.
</dd>
<dt>photo</dt>
<dd>
Accompanying image.
</dd>
<dt>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>nutrition</dt>
<dd>
Nutritional information like calories, fat, dietary fiber etc.
</dd>
<dt>tag</dt>
<dd>
Keyword(s) describing the recipe.
</dd>
</dl>
</dd>
</dl>
</pre>

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

<pre><nowiki><div class="hrecipe">
Pommes Frites

Pommes frites originate in outer space. They are served hot. 
This recipe is only an example. Don't try this at home!

Thomas Loertsch
Published <abbr class="published" title="2008-10-14T10:05:37-01:00">14. Oct 2008</abbr>
<img src="/img/pommes.png" class="photo" width="100" height="100" alt="Pommes Frites"/>

500
gramme
potatoes, hard cooking.

<ul class="instructions">
<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>
Enough for 12 children.
Preparation time is approximately
90 <abbr title="minutes">min</abbr>.

Add
5 <abbr class="unit" title="minutes" >min</abbr>
for preparing the Ketchup.

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

Pommes Frites have more than
1000
Joule
Energy.

</div>
</nowiki></pre>


== Examples in the wild ==

This section is '''informative'''.

'''Wild Mushroom, Pancetta & Truffle Risotto''' by Toby Inkster
* [http://tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ Marked up as hRecipe] using the September 2007 draft format
* [http://srv.buzzword.org.uk/recipebook/tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ RecipeBook XML] output from Cognition.
* [http://srv.buzzword.org.uk/rdf-xml/tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ RDF/XML] and [http://srv.buzzword.org.uk/turtle/tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ Turtle] output from Cognition.

== Implementations ==

This section is '''informative'''.

* Cognition
As of September 2008, [http://buzzword.org.uk/cognition/ Cognition] has experimental support for this format. ([http://buzzword.org.uk/cognition/uf-plus.html#hrecipe Details of support].) Recipes may be exported in [[recipe-formats#RecipeBook_XML|RecipeBook XML]] format or RDF.


* It's Ripe!
As of January 2009, [http://itsripe.com/recipes/ http://itsripe.com] supports hRecipe for recipe pages and will soon add support in lists.

== References ==

=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://gmpg.org/xmdp/ XMDP]
* [[hcard|hCard]]
* [[abbr-design-pattern]]
* [[datetime-design-pattern]]

=== Informative References ===
* [http://www.w3.org/TR/REC-CSS1 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.
* [http://www.w3.org/TR/1998/NOTE-datetime-19980827 W3C NOTE-datetime-19980827]
* [http://www.w3.org/Consortium/Patent-Policy-20040205/ W3C Patent Policy]
* Other recipe metadata efforts. See [[recipe-formats]].
* [[grouping-examples]]
* [[grouping-brainstorming]]
* [[xoxo|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 ===

{{MicroFormatPatentStatement}}

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

* [[User:Phae|Frances Berriman]] (BBC)
* [[User:BenWard|Ben Ward]]
* [[User:TobyInk|Toby Inkster]]
* [[User:ThomasLoertsch | Thomas Loertsch]] ([http://www.essen-und-trinken.de Gruner+Jahr])

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.

==related pages==
* [[hrecipe-issues|hRecipe issues]] - issues regarding the hRecipe draft
* [[hrecipe-feedback|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.

[[Category:Draft Specifications]]

Microformats Wiki - User contributions [en]

hrecipe