magarcia/Yumml.md

## yumml-spec.md

      
    Raw
  

              yumml-spec.md
            
          
  title
  spoiler
  date
  tags
  
  
  YumML - Yet Another Recipe Metadata Language
  Yet Another Recipe Metadata Language - you know, for food.
  2011-09-21
  
  
  food
  YumML
  
  
Version

Version: 0.1

Date: 2011-09-21

Author: Paul Jenkins
Table of Contents


Version
Table of Contents
Version History
Introduction
Basic Example
Extended Example
Specification

IDs
Header
Ingredients
Method


Packaging

Version History

0.1 - Initial draft
Introduction

From YAML.org

What It Is: YAML is a human-friendly data serialization standard for all programming languages.

YumML (the sound you make when you eat a recipe made from Yet Another Recipe Metadata Language), is based on YAML instead of XML to create a human and system readable format.
YumML has three level of detail - Basic/Required, Optional and Extended. The Basic/Required is the minimum that YumML recipes and parsers/programs must support.
Optional values are as the name implies, optional for recipes and parsers, but recommended for both. Optional values include:

duration of each step,
an image of the overall product or of each step,
what tools are required for the recipe

While they aren't required, they can make recipes much easier to follow.
Extended detail is metadata about the recipe, helping link steps to ingredients and which steps can be done in a parallel fashion. While this metadata generally should not be exposed to the end user in a YumML application, it is useful for generating graphs in the Tabular Recipe Notation style.
Basic Example

This is an abridged recipe, cutting out steps and ingredients. This is by design to show off the basic and required form of a YumML recipe. You can find the full basic example recipe in it's own YumML file
name: Mrs Fields Choc-Chip Cookies
time: 25 minutes
ingredient:
  - qty: 2.5
    unit: cups
    item: plain flour

  - qty: .5
    unit: tsp
    item: bi-carb of soda

method:
  - step: Mix flour, bi-carb soda, and salt in a large bowl
  - step: Blend sugars with electric mixer, add margarine to form a grainy paste
Extended Example

Like the above basic example, this is an abridged extended example.
You can find the full extended example recipe in it's own YumML file
name: Mrs Fields Choc-Chip Cookies
date: 2011-09-21
time: 25 minutes
ingredient:
  - qty: 2.5
    unit: cups
    item: plain flour
    id: 1

  - qty: .5
    unit: tsp
    item: bi-carb of soda
    id: 2

  - qty: .25
    unit: tsp
    item: salt
    id: 3

method:
  - step: Mix flour, bi-carb soda, and salt in a large bowl
    uses: 1,2,3
    id: 11

  - step: Blend sugars with electric mixer, add margarine to form a grainy paste
    uses: 4,5,6
    id: 12
Specification

The two examples above should demonstrate that there are three main sections
to a YumML recipe - the header, the ingredients list, and the method (or
instruction/steps) listing.
IDs

Extended Only

Adding identifiers to the steps and ingredients sections makes each recipe more
complex, but creates huge potential for the way to present the data by linking
ingredients to steps, and ordering/arranging steps together. In particular,
Michael Chu (of Cooking For Engineers) has the fantastic Tabular Recipe
Notation and creating a data format that can output that table format would be
difficult without being able to identify where each ingredient or step comes
into the process.
Here's an example of the Tabular Recipe Notation for the above recipe


    flour
    mix
    
    
    Add & Stir
    Blend
    Bake @ 160c
 for 18-20mins
    Transfer to cooling rack


    bicarb


    salt


    brown sugar
    
    blend
    
    Add & Stir


    white sugar


    margarine


    eggs
    
    
    beat


    vanilla


    golden syrup


    choc chips


This is a (relatively) complex example showing steps involving one or more
ingredients and some steps having the output of a previous step, but it doesn't
show steps being executed simultaneously.
There is no need to restrict identifiers to a particular format - they can be
alphanumeric (a->z, 0->9), sequential (1,2,3,4...), random or GUIDs - just so
long as they're unique.
Header

name: Mrs Fields Choc-Chip Cookies
date: 2011-09-21
time: 25 minutes
serves: 1
makes: 25
tags:


cookies - chocolate


name, name of the recipe


Optional: date


Optional: time, how long the recipe should take


Optional: serves, how many people the recipe should serve - best suited for 'meal' recipes

OR


Optional: makes, how many items it makes - best suited for baking (ie, 25 cookies could serve 25 people 1 cookie each, or 1 person with 25 cookies over several days)


Ingredients

- qty: 2.5
  unit: cups
  item: plain flour
  id: 1

qty, quantity should be listed in decimal format (not fractional) for ease of conversion
unit, quantity without a qualifier (cups, tsp, tbsp, lbs, g, kg, mL, L) means nothing.
item, the actual ingredient name
Extended: id. See IDs

Method

Each step (or instruction) in any recipe has a basic "do foo with bar", but there is further metadata you could attach with each step.
- step: Mix flour, bi-carb soda, and salt in a large bowl
  tools: large bowl, spoon
  image: mixing.jpg
  brief: mix
  id: 4
  uses: 1,2,3
  duration: 1
  timer: 120

step is the full description/instruction for that particular step
Optional: tools are what utensils/tools are being used in that step. This could potentially be used to create a filter of recipes based on what utensils you do or don't have.
Optional: image would represent a relative or absolute path to a photo associated with that step. Depending on the complexity or ambiguity of a recipe, visual aids often help.
Extended: id. See IDs
Optional: uses a list of comma separated ingredient ID's. That is for this step, it'd use the ingredients labeled 1, 2 and 3.
Optional: duration should be listed in minutes

Packaging

Optionally, YumML recipes combined with photos/images associated with the recipe
could be packaged into a single file which would be just a renamed zip file
(.YumZ). Any image referenced in the recipe should be relative paths rather
than absolute.
Is there a need for a packaging standard/format for it? It'd be an easy way to
cche it on portable devices if you just had to download a single file then
expand, rather than downloading each. It makes the format more portable but
probably isn't a pressing need.

  
## Yumml.md

      
    Raw
  

              Yumml.md
            
          
  layout
  title
  description
  date
  tags
  
  
  page
  YumML, use YumML, not XML
  Yet Another Recipe Metadata Language - you know, for food.
  2011-09-21
  food yumml
  
  
I won't beat around the bush - existing metadata formats for food recipes suck. Alone that would be my typical bold/arrogant claim, so I present my findings on five different formats (RecipeML, Recipe Exchange Markup Language, CookML and RecipeBook XML) to backup that statement, and then my proposed format. There was a sixth format I was looking into - MealMaster - but the recipe structure doesn't seem to be defined anywhere and as far as I know the only program to use it is MealMaster itself.
###RecipeML###
RecipeML is an XML based format, and this sets a common theme for most of the other recipe metadata formats. XML (and to a lesser degree JSON) are great at machine or system level communication, but they're unwieldy for a human level communication. Build an app on top of the format to read it, and frankly it doesn't matter that much at the end of the day, but it still isn't a perfect system. The problem is creating the recipes in the first place - you either have to generate XML by hand, or use a form to do it which is painful (just for the ingredients list, it would have to be a series of dropdowns for units, lots of add buttons, etc).
RecipeML has been around since 2000, and that age gives it a huge amount of recipes available in that format, which is certainly it's strong point. The format itself isn't badly designed for system communication - it's just when you involve squishy humans that it fails. In all fairness, it hasn't been updated since 2002.
From the examples page
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE recipeml PUBLIC "-//FormatData//DTD RecipeML 0.5//EN" "http://www.formatdata.com/recipeml/recipeml.dtd">
<?xml-stylesheet href="dessert1.css" type="text/css"?>
<recipeml version="0.5">
  <recipe>
    <head>
      <title>The Needless-Markman Hoax Chocolate-Chip Cookie</title>
    </head>
	<ingredients>
      	<ing>
        	<amt><qty>2</qty><unit>cups</unit></amt>
        	<item>butter</item>
      	</ing>
	  	<!-- snip -->
    </ingredients>
    <directions>
      	<step>Measure oatmeal and blend in a blender to a fine powder</step>
		<!-- snip -->
    </directions>
  </recipe>
</recipeml>

It is a verbose format, but there are things to like about it - separating out quantity and unit for each ingredient makes it easy to translate between imperial and metric.
###The Recipe Exchange Markup Language###
From the REML project page

I might have developed against an existing markup languages, but RecipeML is mired in licensing problems, and CookML is written in German.

My reasons for not using CookML are below, but the point about RecipeML is... interesting. I don't know if it does actually have licensing issues - I don't care, but if it is true, it's a good reason not to use it.
What of REML itself? From the sample only found inside a zip file on the project page, listed the ingredients like so:
<ingredient name="Corn flakes" quantity-integer="1">
	<IUnit>
		<IUnitArbitrary>box</IUnitArbitrary>
	</IUnit>
</ingredient>

In addition, I couldn't find anything other than the one sample recipe, so it could very well be a dead format.
###CookML###
I couldn't find an actual example recipe of CookML, but I don't think I need to.

It's XML based
if you thought RecipeML was verbose, the documentation for CookML is at least twice the size
Unlike RecipeML it doesn't seem to have a huge wealth of recipes available

###RecipeBook XML###
Already the title gives away the main issue - it's XML - but RecipeBook XML seems very similar to RecipeML by only adding the equipment used, yet dropping the step definition and lumping all instructions in one block.
##YumML (or Yet Another Recipe Metadata Language)##
Design Considerations

I wanted a format that didn't need a long reference guide (which certainly cut out CookML!)
I wanted something that could be easily read by non-technical people in the 'raw' format, or via an app
I wanted something that could translatable between imperial and metric (in Australia, we use cups for measuring although everything is still metric, yet other places just use metric weights or volumes)
Ideally I wanted the markdown of recipes, while maintaining some form of required structure for easy parsing for apps

From YAML.org

What It Is: YAML is a human friendly data serialization standard for all programming languages.

YumML is based on YAML instead of XML to create a human and system readable format.
Basic Example

This only includes two ingredients, and two steps. This is deliberate to try and keep this post from being massive - see further down for the full recipe.
name: Mrs Fields Choc-Chip Cookies
date: 2011-09-21
time: 25 minutes
ingredient:
    - qty : 2.5
      unit: cups
      item: plain flour

    - qty : .5 
      unit: tsp 
      item: bi-carb of soda

method:
    - step: Mix flour, bi-carb soda, and salt in a large bowl
    - step: Blend sugars with electric mixer, add margarine to form a grainy paste

If you compare this against any XML based format, it's cleaner and easier to read and write, while still maintaining the ability to convert each unit into another form. There is also provision for more detailed
Full Specification

I've split the YumML specs off into a separate page to avoid the ranty bit's on the top of this blog post.
Recipes

There isn't a central repository of YumML recipe's just yet - if there is any interest, I'll build one but first I'm looking at developing various tools for YumML, such as YumML2Html to generate the Tabular Recipe Notation table from CookingForEngineers and display clients for WP7 & Windows with voice controls.
Mrs Fields Choc Chip Cookies (Basic YumML)

Mrs Fields Choc Chip Cookies (Extended YumML)
flour	mix				Add & Stir	Blend	Bake @ 160c for 18-20mins	Transfer to cooling rack
bicarb
salt
brown sugar		blend		Add & Stir
white sugar
margarine
eggs			beat
vanilla
golden syrup
choc chips