techhat / openrecipeformat

Specs and Examples for the Open Recipe Format

Open Recipe Format

In the beginning, there was food. And then there were dishes. And somewhere down the line, people started writing down how to make the dishes. And most of them weren't very good at it. And then they got computers, and they still weren't very good at it.

The Open Recipe Format has been designed to solve some basic needs: accurate and flexible storage of recipes. While there have been attempts in the past to create standardized computer recipe formats, they have so far met with failure. This stems from several problems, all of which stem from a lack of understanding of the tasks at hand (and in most cases, ignorance of which tasks actually need to be addressed).

A significant portion of the population cooks at home, and so most solutions target home cooks. Commercial solutions exist, and address a host of new considerations that are not thought to relate to home cooks. The Open Recipe Format was initially created by a software engineer with a cooking degree and professional kitchen experience. Few, if any, other attempts at writing food software, much less standardized recipe data modeling, can make this claim.

At the heart of the Open Recipe Format is an established file format called YAML. This format was chosen for a variety of reasons:

• It is text-based, and therefore human readable.
• It mimics the internal data structures of several high-level programming languages.
• It can easily be converted to and from other formats, such as the more popular JSON (in fact, JSON is syntactically-correct YAML).
• It is more human readable than JSON.
• It is far more light-weight than other chatty formats, like XML.
• It is far more flexible than legacy formats like EDI.
• As a text-based format, it can be easily managed by revision control software, such as git.

This repository is intended more for programmers than anyone else. As human- readable as the format is, it is likely to be confusing to many in its raw format. The job of the programmer is to use this spec in the development of their own software packages, websites, etc., and provide a friendly interface to the end-user.

Many of the files in this repository are intended to document the Open Recipe Format. Others are examples, to help programmers understand how to best use the format. And finally, sample source code will be provided to give programmers a jump-start in their coding efforts.

openrecipeformat's Issues

More information

Hi - is there anywhere we can get some more information? eg Software that supports the format? Sources of recipes in the format? Best ways to create/edit recipes?

Also - there is another format on schema.org for recipes (https://schema.org/Recipe) which seems to me to lack flexibility. For example, it has a 'recipeIngredient' element that is just text - 3/4 cup of sugar. Which would make converting between grams, ounces, cups, etc somewhat difficult.

Also it does not support different yields, as open recipe format does.

But is does support importing other schema - such as a format for 'creativeWork' and 'howTo'. For me, that seems a little excessive, but I can see it could be useful.

Anyway - this format would suit me - but the schema org format seems to be better supported. Jamie Oliver's site, for example, has the recipes in that format (it is in the source).

Jamie Oliver goes on about using sustainable sources and then wraps everything in cling film and other plastics. Sigh.

Support for images in open recipie format

Was wondering if there was interest in including images in the recipie format? A simple way to do this would be to base64 encode to images.

Open Recipe Format and hRecipe - State of art ?

Hi,

I’m trying to found the best common way to write and share opensource recipes.
I found ORF that sounds great but hRecipe (http://microformats.org/wiki/h-recipe) seems to be used by more people and microformat seems to help in that way.

What are the pros and cons from tech point of view but also (mainly) from cooking side ?
Did someone worked on this topic and could share some ressources ? What is the state of the art of open source formats for writing a recipe ?

Cheers,

Develop a JSON Schema

I think the most important thing Open Recipe Format could do to encourage adoption would be to have tooling to support its users.

This is somewhat covered by TODO.rst:

• Add a syntax checker
• Add a reference parser

I do not think a syntax checker and custom parser are quite the right approach. When I was considering using Open Recipe Format, I went looking at how best to validate a file as being compliant and did not find good options. Long story short, this lead to me building tooling that could be used for this purpose.

If someone wants to apply them to this problem (despite building the tooling as a result of this problem, I do not currently have a need for Open Recipe Format) they would need to write a JSON Schema for the schema of Open Recipe Format.

Then the following would be available:

• Users can use the YAML extension for Visual Studio Code to write their recipes while getting editor help (in the way of feedback if an entry is invalid, completion has not been implemented [but could]) because they specify the Open Recipe Format schema should be used.
  • The extension is Language Server-based so someone could port it to other editors if desired.
• Users can validate their recipes via command line using the Polyglottal JSON Schma Validator (pajv).
• Users looking for tools other than the two just mentioned can check Schema Validation for YAML at JSON Schema Everywhere to see if anything else has been implemented.
• Users wanting to programatically interact with their recipes using an API other than their YAML parser can look can generate an API from the JSON Schema (ex. Java, C#)

oven_* as top level information - and using oven more than once

Sometimes recipe requires that oven is used more than once - and attributes like duration and temperature may be different.

It is not purely theoretical - one of my recipes for apple pie requires that shortcrust pastry is baked, then baked pastry with apples and whipped egg white is baked again.

As I understand this format - it is currently impossible to express such recipe in it.

oven type would be nice

Hello

Thanks for the Open Recipe format, it looks pretty cool and I'll try to use it for my collection of waffle recipes soon.

I would have a small feature request. It would be very cool to specify the "oven type". I imagine here a string or possibly even an array of different options.

# Example Values
oven_type:
  - "any".
  - "conventional oven
  - "microwave"
  - "wood stove"
  - "waffle iron"
  - "stone oven"
  - "grill"
  - ...

currently in my draft, I solved this by setting 'X-oven_type: "waffle iron"', but of course I hope for a official solution. 😉

Divided Ingredients List

In the documentation, I don't see anything about segmenting ingredients lists, which many recipes have.

For example, if I were making a frosted cake, I might have:

CAKE:
1 box cake mix
1 egg

FROSTING:
1 can store-bought frosting

Could this be implemented?

Problems with navigation (reaching examples)

As I understand http://open-recipe-format.readthedocs.org/en/latest/index.html is intended starting point for exploring this format definition. But from this page it is impossible to reach examples ( https://github.com/techhat/openrecipeformat/tree/master/examples ).

Recipes in the examples folder fail to be parsed by pyYAML

Hi,

I just cloned your repository, and tried running the example files through pyYAML. Both of them could not be parsed until I made a simple correction of ensuring that all values of each field key are placed in the same line as the key itself. For example, in lines 90 to 91 of banana-bread.yaml, we have:

  - step:
    Preheat oven to 350F.

but this gives an error:

ScannerError: while scanning a simple key
  in "./banana-bread.yaml", line 91, column 5
could not find expected ':'
  in "./banana-bread.yaml", line 92, column 3

which goes away only after I convert the data to be:

  - step: Preheat oven to 350F.

I found a similar problem in other parts of the same file as well as in the orf-sample-1.yaml. Is this a bug in the example files that should be corrected? Or were the examples supposed to have worked? Why did pyYAML reject this representation?

Here I've attached the diffs between the original and corrected examples.

banana-bread.yaml
orf-sample-1.yaml

Thank you.

bake_time vs oven_time

The Banana Bread recipe has bake_time: 50 - 60 minutes however the format reference lists oven_time and not bake_time.

Example of recipe using duration

Looking at https://open-recipe-format.readthedocs.io/en/latest/topics/tutorials/using-alerts.html, I am confused on exactly where this duration field would be included on a step. Per the reference spec for the step dict, there is not duration field or anything else that might indicate duration, except perhaps embedding the duration in the step itself or in the notes field.

For a hypothetical duck procuttio recipe, a step may look like:

steps:
  - step: Hang for about 7 days in a cool (50 to 60 degrees is optimal), humid place, like a garage, a basement or in an unlit fireplace.

Now, is the intention that the 7 days in the step be replaced with 7D` (which I would argue against as potentially leading to parsing ambiguities for durations), or have something like:

steps:
  - step: Hang for about 7 days in a cool (50 to 60 degrees is optimal), humid place, like a garage, a basement or in an unlit fireplace.
    duration: 7D

Happy to add this @techhat to the reference and update the schema, just need a bit of intended direction on what this meant.

Setup ReadTheDocs automatic build integration

It would be beneficial to me (and probably others) if this repo was set-up to have automatic integration with ReadTheDocs such that pushes to master would then update https://open-recipe-format.readthedocs.io. As it stands for example, while #21 was merged, I am finding myself still relying on my fork at https://openrecipeformat.readthedocs.io to actually consult reference against which I would like to take down to have one definitive source.

Documentation on how to do this can be found at https://docs.readthedocs.io/en/stable/webhooks.html#github.

Validator software possible?

As this format becomes more popular, does it make sense to have some validation software to grade how much the recipe follows the specs?

Possibility to tag used ingredients in step

This would make it possible for parsers to automatically sort the ingredients list chronologically, or to export recipes with the ingredients listed at each step.

- step:
  Add the sugar and half of the flower to the bowl.
  ingredients:
  - sugar
  - flower:
    amounts: 
    - amount: 250
      unit: g

Add basic convertor of other formats to/from ORF

I am writing this issue out to gain feedback, but I plan to put the work in for putting this together. @techhat please let me know what your preferred languages for this would be. I am assuming python given your usage of rST, but perhaps you've moved onto a different language.

It would be useful in adopting ORF to allow it to both input well-known formats and to output to them as well. While I might wish all existing sites made use of it, that's not the case, and so having interoperability with their formats is somewhat necessary.

http://microformats.org/wiki/recipe-formats provides a list of many formats. Some of these formats are read and so may just need the Format -> ORF and not vice versa.

My current planed list is:

• MealMaster
• Recipe Markup Language
• MasterCook
• https://schema.org/Recipe
• JSON-LD (#16 (comment))
• h-recipe
• paprika file format.

@techhat, let me know if you've got any formats you would like to see supported.

How does this format relate with schema.org spec?

Please see:
Specs:
https://schema.org/Recipe
GitHub and issues:
https://github.com/schemaorg/schemaorg/issues?q=is%3Aissue+is%3Aopen+Recipe

As it seems, 76 of 79 recipe sites parsed by the recipe_scrapers project refer schema.org.

Suggestion for some improvements to the format with an example

Hi @techhat , following on our discussion in an earlier post #5 , I've given some more thought to the format and have experimented with different structures. I think I've arrived at one which might be worth considering. Here I thought I would just share some ideas using a concrete example of a recipe taken from this website.

An example YAML file that encodes this recipe, with some modifications from the original ORF:

# name of the dish
dish_name: MUSTARD GREEN PORK RICE

# Name of the dish's originator 
creator: Cynthia Lim

# How many persons this recipe can feed
serves:
  min: 6 
  max: 8 # If there is no range in the number of persons, just fill in the max field

# Information about the recipe, such as its uses, occasions where it is served, and any historical notes
info: 
  - It is my all-time favourite comfort food

# The most specific date the recipe was created, if known, else leave blank
creation_date:

# Category of the dish's cuisine, and associated cultural and geographical information
category:
  race: CHINESE
  ethnic_group: 
  geography: SINGAPORE

# Information source where this recipe was obtained from, be it a website or a cookbook
source_info: 
  type: website
  # Either website or book name is provided, one is filled, the other is left empty
  url: http://mysingaporefood.com/recipe/mustard-green-pork-rice/
  book_name:

# Ingredients used in the recipe
ingredients:
  
  RICE:     
    amount: 2
    units:  CUP
    notes: 
      - Uncooked raw rice

  MUSTARD GREENS:    
    amount: 2
    unit: BUNCH
    notes:
      - Washed and cut into bite-size

  GARLIC: 
    amount: 8
    unit: CLOVE
    notes:
      - Mince the garlic

  GINGER: 
    amount: 0.25
    unit: PIECE
    notes:
      - Sliced thinly
  
  DRIED SHRIMPS: 
    amount: 30
    unit: GRAM
    notes:
      - Soaked in hot water, then drained

  PORK BELLY: 
    amount: 1
    unit: SLAB
    notes:
      - Marinated with 2 tablespoon of soya sauce and 1 teaspoon sesame oil
      - Sliced into bite-size

  DRIED MUSHROOMS:
    amount: 30
    unit: GRAM
    notes:
      - Soaked in hot water to soften, then drained
  
  SOYA SAUCE LIGHT:
    amount: 3
    unit: TABLESPOON
    notes:
      - 2 tbsp used for seasoning pork belly, 1 tbsp used to drizzle on top of cooked rice
    
  SESAME OIL:
    amount: 2
    unit: TEASPOON
    notes: 
      - 1 tsp used for sauteing, 1 tsp used to drizzle on top of cooked rice

# Steps to cook the dish
steps:
  1: Wash the rice twice and drain well.
  2: Heat up wok. Add sesame oil.
  3: Saute ginger till fragrant.
  4: Add garlic and saute.  
  5: Add dried shrimps and saute.
  6: Add mushrooms and saute till fragrant.
  7: Add pork belly and stir-fry till pork belly is half cooked.
  8: Add in rice.
  9: Add in soya sauce and stir well.
  10: Add in mustard greens. Stir well.
  11: Scoop mixture into rice cooker and cover with sufficient water.
  12: Cook as per instructions on rice cooker.
  13: Ready and serve.

Modifications and their rationale:

• Make the ingredients in the recipe as accessible at the top level as possible. To this goal, I've stopped making the ingredient names be marked with a dash, and have instead just put down their names as nested under the ingredients key. The names themselves are going to contain information like amounts and notes; I've made sure to nest these under each respective ingredient name. In this way, I've made it possible to make a generator object of ingredient names, immediately after parsing the YAML file for the flavor formula, by just calling the keys() method on the ingredients dictionary that I index out of the main data structure. More concretely the code involved would simply be:

In [9]: with open("./mustard_green_pork_rice.yaml", "r") as f:
   ...:     fn = yaml.load(f)
   ...:     

In [10]: fn["ingredients"].keys()
Out[10]: dict_keys(['DRIED MUSHROOMS', 'DRIED SHRIMPS', 'MUSTARD GREENS', 'SOYA SAUCE LIGHT', 'PORK BELLY', 'RICE', 'SESAME OIL', 'GINGER', 'GARLIC'])

This greatly simplifies accessing the list of ingredients, an issue which I've raised in an earlier post numbered #5 .

• Eliminate unncessary sequence generation, focus on dictionaries dictionaries The structure of the original format always resulted in the parsed python object becoming a huge mangle of lists of dictionaries. This was due to the extensive use of dashes. Not a pretty and elegant representation. In making this modification, one guiding principle has been to prioritize dictionaries over lists, to represent as much as possible, the layers as dictionary-keys-dictionary-keys and to only have the list be represented at the end at the bottom-most level of a dictionary-key chain.

• Added new fields for recipe origin As some research projects might involve studying some categorical or cultural aspects of recipes, I thought that including these new fields related to such information would be useful from the perspective of provenance.

Looking forward to your thoughts on this. Thank you.