Recipe Book0.6.0

2.6Guides

Import recipes

Read the schema.org JSON-LD that recipe sites publish into a recipe, check what was left out, read regional decimals and units, store the result, and resolve its ingredient links.

§ 2.610 min readView as Markdown

Import a recipe from another site’s page, given its URL. Recipe sites publish their recipes as schema.org Recipe JSON-LD in a <script type="application/ld+json"> tag, for search engines’ recipe results. findRecipeJsonLd finds that JSON-LD in the page’s HTML, and fromJsonLd reads it into a Recipe, the model parseRecipe returns. Both come from @recipe-book/core/schema-org. In a React app, replace @recipe-book/core with @recipe-book/react/core in this page’s imports, so @recipe-book/core/schema-org becomes @recipe-book/react/core/schema-org. fromJsonLd doesn’t throw for bad data, though an error thrown by a getter or proxy in its input passes through, so branch on success:

TypeScript
import { findRecipeJsonLd, fromJsonLd } from '@recipe-book/core/schema-org'

export async function importRecipe(url: string) {
  const response = await fetch(url)

  if (!response.ok) {
    throw new Error(`Fetching ${url} failed with status ${response.status}.`)
  }

  const [node] = findRecipeJsonLd(await response.text())
  const result = fromJsonLd(node)

  if (!result.success) {
    throw result.error
  }

  return result.data
}

fromJsonLd keeps image URLs as the page wrote them, so a relative one, such as /img/pancakes.jpg, would point at your own site. In importRecipe, before it returns the recipe, resolve its image and each step’s image against the address the page loaded from, with new URL(image, response.url).href. Use response.url, not url: fetch follows redirects, such as from a short link or from http to https, and a relative URL belongs to the page it ends at.

Find the recipe in a page

findRecipeJsonLd returns the Recipe nodes it finds in the page, in document order except that a node’s @graph comes before its mainEntity, or [] when there are none. It finds a Recipe at the top level of the JSON-LD, in the arrays and @graphs that sites wrap recipes in, or as the mainEntity of a node there:

TypeScript
import { findRecipeJsonLd } from '@recipe-book/core/schema-org'

const html = `<!doctype html>
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@graph": [
      { "@type": "WebPage", "@id": "https://example.com/pancakes" },
      { "@type": "Recipe", "name": "Buttermilk pancakes" }
    ]
  }
</script>`

findRecipeJsonLd(html) // [{ '@type': 'Recipe', name: 'Buttermilk pancakes' }]
findRecipeJsonLd('<p>No recipe here.</p>') // []

When it finds several, pass each one to fromJsonLd. A roundup page that lists its recipes in an ItemList, and has no Recipe in the places above, gives the Recipes in the list. When the list’s items only link to the recipes’ own pages, fetch each page and find its recipe there.

findRecipeJsonLd reads only JSON-LD, and unlike a recipe scraper, Recipe Book doesn’t scrape a recipe from the rest of the page. A page whose recipe is only in microdata’s itemprop attributes, in RDFa, or in its text gives [].

Paste a page’s HTML source into the playground to see the recipes it gives and what fromJsonLd reads from each one.

Check what was left out

fromJsonLd is forgiving, because you can’t fix another site’s markup. It leaves out a value the recipe can’t hold and reports it as an issue with the severity warning, so the import still succeeds. The issue’s path points into the JSON-LD, such as ['recipeYield', 2], so you can find the value in the page:

TypeScript
import { fromJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Buttermilk pancakes',
  image: 'data:image/png;base64,iVBORw0KGgo=',
  prepTime: 10,
  recipeYield: ['4', '12 pancakes', '1 batch'],
  recipeIngredient: ['1 &frac12; cups (190 g) all-purpose flour', '2 eggs'],
  recipeInstructions: ['Whisk the flour and eggs.', 'Cook on a hot griddle.'],
})

if (!result.success) {
  throw result.error
}

result.warnings.map((issue) => issue.path) // [['image'], ['recipeYield', 2], ['prepTime']]
result.warnings.map((issue) => issue.message) // ['Expected an http or https URL, or a relative one, received "data:…". It is ignored.', 'Only one yield is read, "12 pancakes", so this one is ignored.', 'Expected an ISO 8601 duration such as "PT30M", received 10. It is ignored.']
result.data.servings // { amount: 4 }
result.data.yield // { amount: 12, unit: 'pancake', plural: 'pancakes' }
result.data.ingredients[0]?.items[0]?.quantity // { amount: 1.5, unit: 'cup' }

fromJsonLd lists which recipeYield text it reads as servings and which as the yield. A value the recipe can’t hold is left out with an issue whose message ends “It is ignored.”, such as invalid_url for the data: image or invalid_type for a HowToSupply in recipeIngredient whose name and text are blank. Another number of servings with a different amount, a second yield, or a second duration in a time’s list, such as the second yield here, is an ignored_value issue whose message names the value kept and ends “so this one is ignored.” A list of images keeps one URL, as image describes. A list in another field that holds one value, such as two descriptions, is a value the recipe can’t hold. Issue codes lists every code.

fromJsonLd strips comments, tags, and the content of script and style elements as it reads, then decodes HTML entities, so the flour’s &frac12; is ½. To hold back an import with any issue, such as in a content pipeline, check result.warnings.length too.

Handle a failed import

The import fails only when there’s no Recipe node, or the recipe’s name is missing, isn’t text, or is only whitespace once its markup is removed and its entities decoded, such as '', '<p>&nbsp;</p>', or '<style>p {}</style>'. result.error is a RecipeValidationError, and its issues include the warnings, so you see everything wrong with the page at once:

TypeScript
import { fromJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  recipeIngredient: ['2 eggs'],
})

if (!result.success) {
  result.error.issues.map((issue) => issue.message) // ['Add a name for the recipe.', 'Recipe has no steps.']
}

const empty = fromJsonLd(undefined)

if (!empty.success) {
  empty.error.issues.map((issue) => issue.message) // ['Expected a schema.org Recipe, or an array, @graph, mainEntity, or ItemList that holds one, received undefined.']
}

The second import is what importRecipe gets for a page without a recipe. result.error.message lists the first 10 issues with their paths, one per line, so throwing the error gives a readable failure.

Read regional pages

For a page that writes decimals with a comma, such as '1,500 kg Mehl' on a German page, pass decimal: ',' to fromJsonLd, and for an Australian page’s 250 mL cups and 20 mL tablespoons, pass units:

TypeScript
import { fromJsonLd, toJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd(
  {
    '@context': 'https://schema.org',
    '@type': 'Recipe',
    name: 'Anzac biscuits',
    recipeIngredient: ['1 cup rolled oats', '2 tbsp golden syrup'],
    recipeInstructions: ['Mix, then bake.'],
  },
  { units: { cup: 'cup-metric', tbsp: 'tbsp-au' } },
)

if (!result.success) {
  throw result.error
}

result.data.ingredients[0]?.items.map((item) => item.quantity) // [{ amount: 1, unit: 'cup-metric' }, { amount: 2, unit: 'tbsp-au' }]
toJsonLd(result.data).data.recipeIngredient // ['1 cup rolled oats', '2 tbsp golden syrup']

decimal and units are the options Read regional recipes passes to parseRecipe. The page’s inLanguage and the site’s language don’t set either option, because few pages declare a language and a language doesn’t settle the decimal mark or the cup. Choose them for each site you import from. toJsonLd writes the recipe back as “1 cup rolled oats”, or as “1 cup (250 mL) rolled oats” with system: 'us', so a page you export reads back as metric cups only with the same units.

Store the recipe

result.data is a recipe like any other, so you can scale, convert, and render it. It’s plain JSON data, so you can store it in a database. When you load it back, validate it with parseRecipe, which accepts any recipe that parseRecipe or fromJsonLd returned and returns an equal recipe:

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

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Buttermilk pancakes',
  author: { '@type': 'Person', name: 'Ada' },
  recipeIngredient: ['1 ½ cups (190 g) all-purpose flour', '2 eggs'],
  recipeInstructions: ['Whisk the flour and eggs.', 'Cook on a hot griddle.'],
})

if (!result.success) {
  throw result.error
}

const saved = JSON.stringify(result.data)
const loaded = parseRecipe(JSON.parse(saved))

loaded.success && JSON.stringify(loaded.data) === saved // true
result.extra // { author: { '@type': 'Person', name: 'Ada' } }

result.extra holds the node’s fields that the recipe doesn’t model, such as author and keywords, as the page wrote them, but not its @context or @type. Store it alongside the recipe to credit the source. When the page gives author as an @id reference to a Person elsewhere in its JSON-LD, as Yoast and WP Recipe Maker pages do, findRecipeJsonLd puts that Person in its place, so extra.author holds the author’s name. fromJsonLd keeps the reference when you pass it the page’s parsed JSON instead.

Before you publish the recipe with your own JSON-LD, through toJsonLd or <Recipe.JsonLd>, take the source page’s fields out of extra: @id, url, mainEntityOfPage, and isPartOf identify the other site’s page, and aggregateRating and review are the ratings its readers gave. toJsonLd writes every field in extra that it doesn’t write from the recipe, so your page would claim them as its own.

Some sites link an ingredient line to a product page or another recipe. The first http, https, or relative link in a line becomes the ingredient’s url, and the line’s text reads as it would without it:

TypeScript
import { fromJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Sandwich bread',
  recipeIngredient: [
    '3 cups (360g) <a href="https://shop.example.com/flour">All-Purpose Flour</a>',
    '1 cup <a href="/recipes/sourdough-starter">sourdough starter</a>',
  ],
  recipeInstructions: ['Mix, knead, and bake.'],
})

result.success && result.data.ingredients[0]?.items[0] // { id: 'all-purpose-flour', name: 'All-Purpose Flour', quantity: { amount: 3, unit: 'cup' }, equivalents: [{ amount: 360, unit: 'g' }], url: 'https://shop.example.com/flour', optional: false }
result.success && result.data.ingredients[0]?.items[1]?.url // '/recipes/sourdough-starter'

A link to a place on the same page (#…), or an empty one, is skipped without a warning, so a later link in the line can give the url.

Some relative links, such as //host/path, point to another site. fromJsonLd also keeps a HowToTool’s url as written, in equipment[].url. When you import, before you store the recipe, resolve each ingredient’s url and each equipment[].url, as you resolve the image and each step’s image in importRecipe:

TypeScript
import type { Recipe } from '@recipe-book/core'
import { fromJsonLd } from '@recipe-book/core/schema-org'

function resolveUrl(url: string, page: string): string | undefined {
  return URL.canParse(url, page) ? new URL(url, page).href : undefined
}

function resolveLinks(recipe: Recipe, page: string): Recipe {
  return {
    ...recipe,
    ingredients: recipe.ingredients.map((section) => ({
      ...section,
      items: section.items.map((ingredient) =>
        ingredient.url === undefined
          ? ingredient
          : { ...ingredient, url: resolveUrl(ingredient.url, page) },
      ),
    })),
    equipment: recipe.equipment.map((item) =>
      item.url === undefined
        ? item
        : { ...item, url: resolveUrl(item.url, page) },
    ),
  }
}

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Sandwich bread',
  recipeIngredient: [
    '1 cup <a href="/recipes/sourdough-starter">sourdough starter</a>',
    '3 cups <a href="//shop.example.com/flour">flour</a>',
  ],
  recipeInstructions: ['Mix, knead, and bake.'],
  tool: [{ '@type': 'HowToTool', name: 'loaf pan', url: '/shop/loaf-pan' }],
})

if (!result.success) {
  throw result.error
}

const recipe = resolveLinks(result.data, 'https://example.com/bread')
recipe.ingredients[0]?.items.map((ingredient) => ingredient.url) // ['https://example.com/recipes/sourdough-starter', 'https://shop.example.com/flour']
recipe.equipment.map((item) => item.url) // ['https://example.com/shop/loaf-pan']

To show no links instead, remove them with items: section.items.map(({ url, ...ingredient }) => ingredient).

fromJsonLd lists the links it leaves out and the issues they give. The link’s text isn’t kept apart from the line, and the link belongs to the whole ingredient, so the words of a “learn more” link can end up in the ingredient’s name or note. To render the link, make the ingredient’s name a link with asChild.

Read a pasted recipe

Recipe Book has no reader for a whole recipe written as text, such as one pasted from a recipe card. parseRecipe reads ingredient lines only when you pass it parseIngredientLine, and then keeps each line and step as written, so a line such as 'For the glaze:' would be an ingredient, and '1. Heat the oven.' would keep its number in a list that numbers its steps. fromJsonLd reads a recipe’s lines by the rules recipe sites need, so split the text into its name, its ingredient lines, and its method, and pass them to fromJsonLd as a schema.org Recipe:

TypeScript
import { fromJsonLd } from '@recipe-book/core/schema-org'

function readPastedRecipe(text: string) {
  const [name = '', ...lines] = text
    .split('\n')
    .map((line) => line.trim())
    .filter((line) => line !== '')
  const method = lines.findIndex((line) => /^method$/i.test(line))

  if (method === -1) {
    throw new Error('Write the steps after a line that says "Method".')
  }

  return fromJsonLd({
    '@type': 'Recipe',
    name,
    recipeIngredient: lines
      .slice(0, method)
      .filter((line) => !/^ingredients$/i.test(line)),
    recipeInstructions: lines.slice(method + 1).join('\n'),
  })
}

const result = readPastedRecipe(`Lemon drizzle cake

Ingredients
1 cup (200 g) sugar
1 ½ cups (190 g) self-rising flour
2 eggs
For the glaze:
1 cup (120 g) powdered sugar
2 tbsp lemon juice

Method
1. Heat the oven to 350°F.
2. Beat the sugar, flour, and eggs, then bake for 45 minutes.
Step 3
Whisk the glaze and pour it over the warm cake.`)

if (!result.success) {
  throw result.error
}

result.data.ingredients.map((section) => section.title) // [undefined, 'For the glaze']
result.data.ingredients[1]?.items.map((ingredient) => ingredient.name) // ['powdered sugar', 'lemon juice']
result.data.steps[0]?.items.map((step) => step.text) // ['Heat the oven to 350°F.', 'Beat the sugar, flour, and eggs, then bake for 45 minutes.', 'Whisk the glaze and pour it over the warm cake.']
result.warnings // []

'For the glaze:' titles a section of the lines after it, because it reads as a heading: it has a letter but no number, and it ends in a colon. A step’s number of one or two digits followed by a period and a space, such as '1. ', is left out, but one written as '1) ' stays in the step’s text, and a line that’s only a step’s label, such as 'Step 3', isn’t a step. fromJsonLd lists every rule in its recipeIngredient and recipeInstructions rows and in the paragraphs on sections and on recipeInstructions text after its table.

readPastedRecipe removes the lines that say only “Ingredients” and “Method” before it calls fromJsonLd. With no colon, a bare “Ingredients” isn’t a heading by those rules, so it would be an ingredient named “Ingredients”, and “Method” would be a step, with no warning for either. Recipe cards differ in how they set out a name, servings, and the method, so adjust the split to the text your readers paste.

Next steps

Contents