Recipe Book0.6.0

5.6Errors

invalid_recipe

parseRecipe or fromJsonLd found errors in a recipe, and the error's issues say where each one is and how to fix it.

§ 5.610 min readView as Markdown

parseRecipe found at least one error in recipe input, such as a misspelled unit or an amount of 0, or fromJsonLd found one in a schema.org Recipe, such as a missing name. Each returns a RecipeValidationError with the code invalid_recipe in result.error, and the error’s issues list every problem it found.

Text
RecipeValidationError: "Buttermilk pancakes" has 3 problems:
  ✖ ingredients[0].quantity  Unknown unit "cupz". Did you mean "cups"?
  ✖ ingredients[1].quantity  Expected a positive number, received 0.
  ⚠ serving                  Unknown field. Did you mean "servings"?
See https://recipe-book.siraj.page/errors/invalid_recipe/

To fail loudly instead, such as for a recipe in your own code, throw result.error.

When fromJsonLd gets input with no Recipe node, such as a WebPage node without one in its mainEntity, the only issue is an invalid_type error at (root): Expected a schema.org Recipe, or an array, @graph, mainEntity, or ItemList that holds one, received an object.

Input with no name, or that isn’t an object, has no name to quote, so the error’s first line names it Recipe:

Text
RecipeValidationError: Recipe has 1 problem:
  ✖ (root)  Expected a recipe object such as { name, ingredients, steps }, received 42.
See https://recipe-book.siraj.page/errors/invalid_recipe/
Text
RecipeValidationError: Recipe has 3 problems:
  ✖ name         Add a name for the recipe.
  ⚠ ingredients  Recipe has no ingredients.
  ⚠ steps        Recipe has no steps.
See https://recipe-book.siraj.page/errors/invalid_recipe/

Read the issues

Each issue in result.error.issues is a RecipeIssue:

TypeScript
import { parseRecipe } from '@recipe-book/core'

const result = parseRecipe({
  name: 'Buttermilk pancakes',
  serving: 4,
  ingredients: [
    { name: 'all-purpose flour', quantity: '1 ½ cupz' },
    { name: 'egg', plural: 'eggs', quantity: 0 },
  ],
  steps: ['Whisk everything together.'],
})
result.error.issues
[
  {
    code: 'unknown_unit',
    severity: 'error',
    path: ['ingredients', 0, 'quantity'],
    message: 'Unknown unit "cupz". Did you mean "cups"?',
    suggestion: 'cups',
  },
  {
    code: 'invalid_amount',
    severity: 'error',
    path: ['ingredients', 1, 'quantity'],
    message: 'Expected a positive number, received 0.',
  },
  {
    code: 'unknown_field',
    severity: 'warning',
    path: ['serving'],
    message: 'Unknown field. Did you mean "servings"?',
    suggestion: 'servings',
  },
]

Only issues with the severity 'error' fail the parse. The error’s message writes each path in a form such as ingredients[0].quantity, or (root) for the input itself. Issue codes lists every code. After 10 issues, the message ends with a line such as …and 2 more. error.issues lists them all.

Fix the recipe input

Fix each issue as its message says:

TypeScript
import { parseRecipe } from '@recipe-book/core'

const result = parseRecipe({
  name: 'Buttermilk pancakes',
  servings: 4,
  ingredients: [
    { name: 'all-purpose flour', quantity: '1 ½ cups' },
    { name: 'egg', plural: 'eggs', quantity: 2 },
  ],
  steps: ['Whisk everything together.'],
})

result.success // true

Name, system, and lists

parseRecipe takes a recipe as an object. A recipe needs a name, and system is 'metric' or 'us'. ingredients and steps are lists, and each can group its items in sections such as { title: 'Batter', items: [...] }, which can’t hold other sections. parseRecipe gives these issues for them:

Received Issue code Message
null instead of a recipe invalid_type Expected a recipe object such as { name, ingredients, steps }, received null.
name: '', or no name missing_field Add a name for the recipe.
equipment: [{ name: '' }] missing_field Add a name, e.g. name: "whisk".
system: 'Metric' invalid_type Expected "metric" or "us", received "Metric".
equipment: [42] invalid_type Expected a string or { name }, received 42.
notes: 'Chill the dough.' invalid_type Expected a list of notes, received "Chill the dough.".
ingredients: [42] invalid_type Expected an ingredient such as { name: "flour", quantity: "2 cups" }, received 42.
ingredients: ['2 cups flour'] invalid_type Expected an ingredient such as { name: "flour", quantity: "2 cups" }, received "2 cups flour". To read ingredient lines, pass parseIngredientLine: parseRecipe(input, { parseIngredientLine }).
ingredients: [] empty_list Recipe has no ingredients.
steps: [] empty_list Recipe has no steps.
ingredients: [{ items: [] }] empty_list Section has no ingredients.
ingredients: [{ items: [{ items: [] }] }] invalid_type Sections can't be nested. Make this a top-level section in ingredients.

empty_list is a warning, so on its own it doesn’t fail the parse: result.success is true, and the issue is in result.warnings. For a section in steps, the messages say steps instead.

Other input that isn’t an object gets the same message as null, with its own ending, such as received undefined., received an array., or received 42. JSON text is a string, so its message ends with the text in quotes, cut short with … when it’s long. Pass it through JSON.parse first, and pass the object it gives to parseRecipe.

ingredients, steps, or equipment that isn’t a list gets the same message as notes, with its own name. With parseIngredientLine passed in, ingredients: [42] gets Expected an ingredient such as "2 cups flour" or { name: "flour", quantity: "2 cups" }, received 42.

In createRecipeSchema, ingredients: ['2 cups flour'] gets a message that ends To read ingredient lines, use createRecipeSchema({ parseIngredientLine }). instead.

fromJsonLd leaves out a number or a boolean in recipeIngredient or recipeInstructions, and an object in recipeIngredient that makes no line, such as {}, with an invalid_type warning. recipeIngredient: [42] gives Expected an ingredient line such as "2 cups flour", received 42. It is ignored. at recipeIngredient[0], and Recipe has no ingredients. at recipeIngredient. For recipeIngredient: [{}], the first message ends received an object. It is ignored. instead.

Quantity and optional

parseRecipe gives these issues for an ingredient’s quantities and optional, at a field such as ingredients[0].quantity:

Received Issue code Message
ingredients: [{ name: 'flour', equivalents: ['120 g'] }] missing_field Add a quantity. Equivalents are alternatives to it, so they need one.
ingredients: [{ name: 'flour', equivalents: '120 g' }] invalid_type Expected a list of quantities, e.g. ["190 g"], received "120 g".
ingredients: [{ name: 'flour', optional: 'yes' }] invalid_type Expected true or false, received "yes".

For a tool, equipment: [{ name: 'Ramekin', quantity: 1.5 }] gives Expected a whole number greater than 0, received 1.5., an invalid_amount error at equipment[0].quantity.

Steps and notes

A step or note is a string, or an object with its text. parseRecipe gives these issues for them, at a step such as steps[0] or steps[0].text, or at a note such as notes[0] or notes[0].text:

Received Issue code Message
steps: [42] invalid_type Expected a string or { text }, received 42.
steps: [{ text: 42 }] invalid_type Expected text, received 42.
steps: [{ text: '' }] missing_field Add the step text.
notes: [{ title: 'Storage' }] missing_field Add the note text.

A note gets the same invalid_type messages as a step. Any other field that takes text, such as name, description, or a note’s title, gets the same Expected text message when it isn’t a string.

Servings and yield

servings is a number or range of servings, and yield is what a batch makes, with a unit. parseRecipe gives these issues for them, at servings or yield, or at servings.amount, servings.max, yield.amount, yield.max, or yield.unit:

Received Issue code Message
servings: '4 servings' invalid_quantity Expected a number of servings, e.g. 4 or "4–6", received "4 servings".
servings: true invalid_type Expected a number of servings, e.g. 4 or "4–6", received true.
servings: { max: 6 } missing_field Add an amount, e.g. { amount: 4, max: 6 }.
servings: { amount: { min: 4, max: 6 } } invalid_type Expected a positive number, received an object. Write a range as { amount: 4, max: 6 }.
servings: { amount: 6, max: 4 } invalid_range Expected a maximum no less than the amount (6), received 4.
yield: '24' missing_field Add what the recipe makes, e.g. "24 cookies". For a number of servings, use servings: 24.
yield: 24 invalid_type Expected a batch such as "24 cookies" or { amount, unit }, received 24. For a number of servings, use servings: 24.
yield: '3 or 4 loaves' invalid_quantity Expected a batch such as "24 cookies" or "3–4 loaves", received "3 or 4 loaves".
yield: '2 and 1/2 dozen' invalid_quantity Expected a batch such as "24 cookies" or "3–4 loaves", received "2 and 1/2 dozen". Did you mean "2 1/2 dozen"?
yield: '1/2 + 1/4 cup' invalid_quantity Expected a batch such as "24 cookies" or "3–4 loaves", received "1/2 + 1/4 cup".
yield: { unit: 'cookie' } missing_field Add an amount, e.g. { amount: 24, unit: "cookie" }.
yield: { amount: 24 } missing_field Add a unit, e.g. { amount: 24, unit: "cookie" }. For a number of servings, use servings: 24.

Other values get the same invalid_type messages with their own ending, such as received null. or received an array.

Times

times holds prep, cook, total, and a list of custom times, each in minutes or as an ISO 8601 duration. parseRecipe gives these issues for them, at times or a time such as times.prep, or at a custom time such as times.custom[0], its label, or its minutes:

Received Issue code Message
times: 30 invalid_type Expected { prep, cook, total, custom }, received 30.
times: { prep: '30 min' } invalid_duration Expected minutes or an ISO 8601 duration like "PT30M", received "30 min".
times: { custom: { label: 'Chill', minutes: 60 } } invalid_type Expected a list of custom times, received an object.
times: { custom: ['Chill 1 hour'] } invalid_type Expected { label, minutes }, e.g. { label: "Chill", minutes: 60 }, received "Chill 1 hour".
times: { custom: [{ minutes: 60 }] } missing_field Add a label, e.g. label: "Chill".
times: { custom: [{ label: 'Chill' }] } missing_field Add the time, e.g. minutes: 60 or minutes: "PT1H".

Nutrition

nutrition is for one serving: calories in kilocalories, sodium and cholesterol in milligrams, and the other nutrients in grams. Each is a number in that unit, or a string with a unit such as '12 g', and servingSize is a string. parseRecipe gives these issues for them, at nutrition or a field such as nutrition.fat:

Received Issue code Message
nutrition: 250 invalid_type Expected nutrition for one serving, e.g. { calories: 250, fat: "12 g" }, received 250.
nutrition: { calories: 'about 250' } invalid_quantity Expected kcal, e.g. 250, "250 kcal", or "1046 kJ", received "about 250".
nutrition: { calories: '1,200 kcal' } invalid_quantity Couldn't read "1,200 kcal". "1,200" could be "1200" or "1.2": write one of those, or pass { decimal: "," } to read commas as decimals.
nutrition: { fat: '12 kcal' } invalid_quantity Expected grams, e.g. 12 or "12 g", received "12 kcal".
nutrition: { fat: -1 } invalid_amount Expected grams, e.g. 12 or "12 g", received -1.
nutrition: { sodium: 'trace' } invalid_quantity Expected milligrams, e.g. 300, "300 mg", or "0.3 g", received "trace".

A nutrient that’s neither a number nor a string, such as true, gets its unit’s message as an invalid_type issue.

A recipe’s image, a step’s image, and the url of an ingredient or tool are each an http or https URL or a relative one. parseRecipe gives this issue for a URL with any other scheme, or one the URL parser rejects, at its field, such as image or steps[0].image:

Received Issue code Message
image: 'javascript:alert(1)' invalid_url Expected an http or https URL, or a relative one, received "javascript:…".
image: 'ftp://[bad' invalid_url Expected an http or https URL, or a relative one, received "ftp://[bad".

Other schemes get the same message with their own ending, such as received "data:…". or received "ftp:…"., when the URL parser reads the URL. A URL it rejects ends with the URL itself, whatever its scheme, quoted like a JSON string and cut with “…” when longer than 60 UTF-16 code units.

Unknown fields

A field parseRecipe doesn’t read gets an unknown_field warning. A close match gets a suggestion, as serving gets servings, and a schema.org @type at the top level gets Unknown field. For schema.org JSON-LD, use fromJsonLd.

Contents