5.6Errors
invalid_
parseRecipe or fromJsonLd found errors in a recipe, and the error's issues say where each one is and how to fix it.
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.
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:
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/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:
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.'],
})[
{
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:
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 // trueName, 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.
Links and images
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.