Improved schema.org JSON structure for grouping instructions, ingredients, tools

[seyfeb]

I was doing some thinking on how the schema.org standard's structure could be used to allow users to give the recipes more structure. Related issues are

• Add images to recipe steps #47
• Support for ingredient grouping #311
• Meta: Future file structure #340
• Enable to get the possibility to save more than one picture #443
• Timer per step #706
• Separate scrollbar for ingredients list and cooking steps #1240
• "Cooking mode" - specific display of recipe #1847
• Problem importing recipe instructions with HowToSections #428
• Recipe instructions in object-form should be importable #382

Instructions

For the instructions we could use HowToSection elements to allow structuring the recipe into multiple parts and HowToDirection elements for the single steps.

The sections can have their own title, description, photos and videos attached that are a general representation of the section and a list of instructions.

The instructions can come with their own photos and videos, illustrating the individual step, a list of ingredients and tools required for the step, the time required for this step which can be shown as a timer (e.g. "Cook for 20min.").

UI

This would allow for different UI ideas to be implemented:

• Each step could be shown with ingredients, tools, images, ... used in this step
• For each group the required ingredients, etc. could be displayed
• At the top one could additionally display a list of all ingredients (e.g., for shopping lists or getting a quick overview)
• Multiple timers could be available (I'd suggest max. 1 per step)

schema.org properties

The schema.org properties I have in mind are listed below

HowToSection

• name or headlines: The title of the section. I'd prefer name
• abstract, text, or description: For summarizing the content or some introductory words to the section. description should be the most fitting
• associatedMedia (MediaObject): Could be used for images, videos, recipe ingredients, ...
• position: Indicates the position in the list of sections and instructions
• `itemListElement: The list of instructions
• image: If one wants to show one or multiple general images for the section
• thumbnail/thumbnailUrl: Thumnails of the images

HowToDirection

• position: Indicates the position in the list of sections and instructions
• name or headline: Actually, I don't think this is necessarily required. One could use Markdown in the text, but I expect that most of the time you wouldn't add another title to a single instruction
• supply: Ingredients for the instruction. However, I'm not sure how things like baking sheets, etc. would be handled. There is also the material property, which can be of type Product.
• tool: Tools required in this step
• image: Image(s) of the step
• thumbnail/thumbnailUrl: Thumnails of the images
• timeRequired or totalTime: Timer for a step. (There is also prepTime and performTime, but I think one timer should be enough for a single step. tbd. I'd vote for totalTime.)
• text: The instructions, Markdown supported

The advantage of using HowToDirection over using HowToStep is, that the former has supply and tool properties which can be used for defining required ingredients and, well, tools.

Example JSON

In the example below I show a non-complete (in the sense that you should not try to cook it) recipe for a lasagna as an example for the ideas above. I left out the dates, nutrition, etc. which are not important for the ideas here, but should obviously still be supported. Regarding the timers: If those where moved to the actual step where time is consumed, the main cookTime property could be the sum of all cook times for information purpose only and would not need to have countdown timer functionality anymore.

I used the supply property for listing ingredients, as proposed here schemaorg/schemaorg#882.

Short version of JSON

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Recipe",
  "name": "Delicious Lasagna",
  "totalTime": "PT1H30M",
  "cookTime": "PT40min",
  "recipeIngredient": [
            //...
  ],
  "supply": [
            //...
  ],
  "recipeInstructions": [
    {
      "@type": "HowToSection",
      "position": 1,
      "name": "Prepare the Meat Sauce",
      "description": "First the meat sauce needs to be prepared. Be aware that this will take a lot of time to get the best result.",
      "image": [
        "meat_sauce_1.jpg",
        "meat_sauce_2.jpg"
      ],
      "thumbnailUrl": [
        "meat_sauce_1_thumb.jpg",
        "meat_sauce_2_thumb.jpg"
      ],
      "itemListElement": [
        {
          "@type": "HowToDirection",
          "position": 1,
          "image": ["ground_beef_in_pan.jpg"],
          "thumbnailUrl": ["ground_beef_in_pan_thumb.jpg"],
          "timeRequired": ["PT6M"],
          "text": "In a large skillet, brown the ground beef and the onions.",
          "supply": [
            //...
          ],
          "tool": [
            //...
          ]
        },
        {
          "@type": "HowToDirection",
          "position": 2,
          "image": [],
          "thumbnailUrl": [],
          "timeRequired": ["PT4M"],
          "text": "Add minced garlic and sauté for a few minutes.",
          "supply": [
            //...
          ],
          "tool": []
        }
      ]
    },
    {
      "@type": "HowToSection",
      "position": 2,
      "name": "Prepare the Cheese Filling",
      "description": "Get ready for the cheesy part...",
      "image": [],
      "thumbnailUrl": [],
      "itemListElement": [
        {
          "@type": "HowToDirection",
          "position": 1,
          "image": ["cheese_in_a_bowl.jpg"],
          "thumbnailUrl": ["cheese_in_a_bowl_thumb.jpg"],
          "timeRequired": ["PT2M"],
          "text": "In a bowl, combine ricotta cheese, mozzarella cheese, salt, and pepper.",
          "supply": [
            //...
          ],
          "tool": [
            //...
          ]
        }
      ]
    },
    {
      "@type": "HowToDirection",
      "position": 3,
      "image": ["lasagna_layer.jpg"],
      "thumbnailUrl": ["lasagna_layer_thumb.jpg"],
      "timeRequired": ["PT10M"],
      "text": "In a baking dish, layer lasagna noodles, meat sauce, and cheese filling.",
      "supply": [
        //...
      ],
      "tool": [
        //...
      ]
    }
  ]
}
</script>

Full JSON

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Recipe",
  "name": "Delicious Lasagna",
  "totalTime": "PT1H30M",
  "cookTime": "PT40min",
  "recipeIngredient": [
    "0.5 kilogram of ground beef",
    "1/2 cup of diced onions",
    "2 cups of ricotta cheese",
    "2 cups of shredded mozzarella cheese",
    "2 cloves of garlic, minced",
    "salt to taste",
    "pepper to taste",
    "12 pieces of lasagna noodles"
  ],
  "supply": [
    {
      "@type": "HowToSupply",
      "identifier": "37d8e801-13fe-4ce9-ba93-6b8a35e6646f",
      "name": "ground beef",
      "description": "",
      "requiredQuantity": {
        "@type": "QuantitativeValue",
        "value": 0.5,
        "unitText": "kilogram",
        "unitCode": "KGM"
      }
    },
    {
      "@type": "HowToSupply",
      "identifier": "887ab19e-97be-43b1-bf20-b423b38eda5a",
      "name": "onion",
      "description": "diced",
      "requiredQuantity": {
        "@type": "QuantitativeValue",
        "value": 0.5,
        "unitText": "cup",
        "unitCode": "CU"
      }
    },
    {
      "@type": "HowToSupply",
      "identifier": "5bea667a-344a-44e9-a842-b6187e95b702",
      "description": "minced",
      "name": "garlic",
      "requiredQuantity": {
        "@type": "QuantitativeValue",
        "value": 2,
        "unitText": "clove"
      }
    },
    {
      "@type": "HowToSupply",
      "identifier": "f0a77778-5292-4bf4-8be2-4541a1cbd6ee",
      "name": "ricotta cheese",
      "description": "",
      "requiredQuantity": {
        "@type": "QuantitativeValue",
        "value": 2,
        "unitText": "cups",
        "unitCode": "CU"
      }
    },
    {
      "@type": "HowToSupply",
      "identifier": "ce0388ac-617f-4a15-9273-9ba805bf7523",
      "name": "shredded mozzarella cheese",
      "description": "",
      "requiredQuantity": {
        "@type": "QuantitativeValue",
        "value": 0.5,
        "unitText": "cup",
        "unitCode": "CU"
      }
    },
    {
      "@type": "HowToSupply",
      "identifier": "4563b9e4-460b-4325-96f2-9fc5ef349e81",
      "name": "salt",
      "description": "to taste"
    },
    {
      "@type": "HowToSupply",
      "identifier": "6811be83-8282-4851-bb88-749b3be727af",
      "name": "pepper",
      "description": "to taste"
    },
    {
      "@type": "HowToSupply",
      "identifier": "f16704c8-9b3f-4009-b6d1-1ec843e416f3",
      "name": "lasagne noodles",
      "description": "",
      "requiredQuantity": {
        "@type": "QuantitativeValue",
        "value": 12,
        "unitText": "piece",
        "unitCode": "C62"
      }
    }
  ],
  "recipeInstructions": [
    {
      "@type": "HowToSection",
      "position": 1,
      "name": "Prepare the Meat Sauce",
      "description": "First the meat sauce needs to be prepared. Be aware that this will take a lot of time to get the best result.",
      "image": [
        "meat_sauce_1.jpg",
        "meat_sauce_2.jpg"
      ],
      "thumbnailUrl": [
        "meat_sauce_1_thumb.jpg",
        "meat_sauce_2_thumb.jpg"
      ],
      "itemListElement": [
        {
          "@type": "HowToDirection",
          "position": 1,
          "image": ["ground_beef_in_pan.jpg"],
          "thumbnailUrl": ["ground_beef_in_pan_thumb.jpg"],
          "timeRequired": ["PT6M"],
          "text": "In a large skillet, brown the ground beef and the onions.",
          "supply": [
            {
              "@type": "HowToSupply",
              "identifier": "37d8e801-13fe-4ce9-ba93-6b8a35e6646f",
              "name": "ground beef",
              "description": "",
              "requiredQuantity": {
                "@type": "QuantitativeValue",
                "value": 0.5,
                "unitText": "kilogram",
                "unitCode": "KGM"
              }
            },
            {
              "@type": "HowToSupply",
              "identifier": "887ab19e-97be-43b1-bf20-b423b38eda5a",
              "name": "onion",
              "description": "diced",
              "requiredQuantity": {
                "@type": "QuantitativeValue",
                "value": 0.5,
                "unitText": "cup",
                "unitCode": "CU"
              }
            }
          ],
          "tool": [
            {
              "@type": "HowToTool",
              "identifier": "b3c0d2ff-009c-423e-89e8-e0245d027006",
              "name": "large skillet",
              "description": "",
              "requiredQuantity": {
                "@type": "QuantitativeValue",
                "value": 1,
                "unitText": "unit",
                "unitCode": "C62"
              }
            }
          ]
        },
        {
          "@type": "HowToDirection",
          "position": 2,
          "image": [],
          "thumbnailUrl": [],
          "timeRequired": ["PT4M"],
          "text": "Add minced garlic and sauté for a few minutes.",
          "supply": [
            {
              "@type": "HowToSupply",
              "identifier": "5bea667a-344a-44e9-a842-b6187e95b702",
              "description": "minced",
              "name": "garlic",
              "requiredQuantity": {
                "@type": "QuantitativeValue",
                "value": 2,
                "unitText": "clove"
              }
            }
          ],
          "tool": []
        }
      ]
    },
    {
      "@type": "HowToSection",
      "position": 2,
      "name": "Prepare the Cheese Filling",
      "description": "Get ready for the cheesy part...",
      "image": [],
      "thumbnailUrl": [],
      "itemListElement": [
        {
          "@type": "HowToDirection",
          "position": 1,
          "image": ["cheese_in_a_bowl.jpg"],
          "thumbnailUrl": ["cheese_in_a_bowl_thumb.jpg"],
          "timeRequired": ["PT2M"],
          "text": "In a bowl, combine ricotta cheese, mozzarella cheese, salt, and pepper.",
          "supply": [
            {
              "@type": "HowToSupply",
              "identifier": "f0a77778-5292-4bf4-8be2-4541a1cbd6ee",
              "name": "ricotta cheese",
              "description": "",
              "requiredQuantity": {
                "@type": "QuantitativeValue",
                "value": 2,
                "unitText": "cups",
                "unitCode": "CU"
              }
            },
            {
              "@type": "HowToSupply",
              "identifier": "ce0388ac-617f-4a15-9273-9ba805bf7523",
              "name": "shredded mozzarella cheese",
              "description": "",
              "requiredQuantity": {
                "@type": "QuantitativeValue",
                "value": 0.5,
                "unitText": "cup",
                "unitCode": "CU"
              }
            },
            {
              "@type": "HowToSupply",
              "identifier": "4563b9e4-460b-4325-96f2-9fc5ef349e81",
              "name": "salt",
              "description": "to taste"
            },
            {
              "@type": "HowToSupply",
              "identifier": "6811be83-8282-4851-bb88-749b3be727af",
              "name": "pepper",
              "description": "to taste"
            }
          ],
          "tool": [
            {
              "@type": "HowToTool",
              "identifier": "b3c0d2ff-009c-423e-89e8-e0245d027006",
              "name": "bowl",
              "description": "ca. 500 ml",
              "requiredQuantity": {
                "@type": "QuantitativeValue",
                "value": 1,
                "unitText": "unit",
                "unitCode": "C62"
              }
            }
          ]
        }
      ]
    },
    {
      "@type": "HowToDirection",
      "position": 3,
      "image": ["lasagna_layer.jpg"],
      "thumbnailUrl": ["lasagna_layer_thumb.jpg"],
      "timeRequired": ["PT10M"],
      "text": "In a baking dish, layer lasagna noodles, meat sauce, and cheese filling.",
      "supply": [
        {
          "@type": "HowToSupply",
          "identifier": "f16704c8-9b3f-4009-b6d1-1ec843e416f3",
          "name": "lasagne noodles",
          "description": "",
          "requiredQuantity": {
            "@type": "QuantitativeValue",
            "value": 12,
            "unitText": "piece",
            "unitCode": "C62"
          }
        },
        {
          "@type": "HowToSupply",
          "name": "meat sauce",
        },
        {
          "@type": "HowToSupply",
          "name": "cheese filling",
        }
      ],
      "tool": [
        {
          "@type": "HowToTool",
          "identifier": "e015a3fb-ca67-4890-9ec7-05359828fa0c",
          "name": "baking dish",
          "requiredQuantity": {
            "@type": "QuantitativeValue",
            "value": 1,
            "unitText": "unit",
            "unitCode": "C62"
          }
        }
      ]
    }
  ]
}
</script>

tl;dr;

• Introducing HowToSections in our JSON would allow ingredient grouping
• Using HowToDirection for instruction steps would allow individually defining tools, ingredients, images, and timers with the instruction text
• This allows multiple different ways to display recipes from showing ingredients/tools per step, per section, total per recipe and hence offering quite some flexibility
• This should be compatible with the schema.org standard
• An example is shown above

Do you spot any issues or have an opinion on this? :)