YumML - Un Altre Format de Metadades de Receptes

Fa anys, parlant amb un amic, ens vam adonar que no existeix cap format estàndard per desar receptes de cuina. En aquell moment estava aprenent React, i un dels meus primers projectes va ser una app de gestió de receptes. No vaig tenir èxit (com tants projectes que vaig començar i mai vaig acabar), però pel camí vaig trobar un esborrany d'especificació per a un format de receptes: YumML.

Sí, sóc plenament conscient de la ironia. xkcd.com/927

Paul Jenkins va publicar aquest format a vikingco.de, però el lloc ja no està disponible. Les úniques referències que queden són de l' Internet Archive i del repositori de la pàgina, que encara segueix accessible.

Les paraules clau "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" i "OPTIONAL" en aquest document s'han d'interpretar com es descriu a RFC 2119.

Història

El primer esborrany del format YumML és del 21 de setembre de 2011, creat per Paul Jenkins. Pots revisar l'especificació original aquí, que vaig rescatar dels vells arxius que vaig trobar.

Aquest esborrany és prometedor com a format per a receptes de cuina, així que vull recuperar-lo de l'oblit i reviure'l, afegint funcionalitats i especificacions addicionals.

Motivació

Com va mencionar l'autor original de YumML al seu blog, he investigat formats de receptes de cuina i, sent sincer, la majoria són força dolents. El panorama de formats d'intercanvi de receptes està fragmentat, però gairebé tots comparteixen un problema comú: la manca de llegibilitat humana.

La majoria del programari de cuina fa servir formats propietaris que només aquest programari pot llegir. Alguns es poden importar a altres programes. Meal-Master és un d'aquests formats àmpliament suportats i gràcies a això existeix una enorme col·lecció de receptes disponible en línia.

Però si mirem un exemple, el format sembla estar mal especificat:

MMMMM----- Now You're Cooking! v5.65 [Meal-Master Export Format]

      Title: Agua De Valencia
 Categories: beverages, spanish
      Yield: 4 servings

      1    bottle of spanish cava
           -(sparkling wine or; champag
           plenty fresh orange juice
           cointreau
           ice cubes

Put some ice cubes into a large jug and pour over lots of orange juice. Now
add the bottle of cava. Once the fizz subsides, stir in a good dash of the
cointreau and it's ready to serve.

  Contributor:  Esther Pérez Solsona

  NYC Nutrilink: N0^00000,N0^00000,N0^00000,N0^00000

Hi ha alguns altres formats "famosos" com:

• RecipeML
• Recipe Exchange Markup Language
• CookML

Però estan basats principalment en XML, i cap humà pot llegir una recepta escrita en ells. Si t'interessa trobar altres formats de receptes, existeix una llista de formats de cuina relacionats amb programari.

Val la pena esmentar alguns formats que van sorgir amb l'era d'Internet. Les microdades HTML com Google rich snippets i les microdades de schema.org són àmpliament usades per llocs comercials de receptes. Tot i que l'objectiu principal de les microdades és la llegibilitat per màquines (especialment per a SEO), la gent segueix llegint i seguint les receptes.

Finalment, vaig trobar pesto, que busca ser un format més simple i llegible per humans, però personalment el trobo difícil d'entendre per a algú que no està familiaritzat amb la seva sintaxi.

Consideracions de disseny originals

L'autor original de YumML tenia en ment algunes consideracions durant el disseny del format:

• No necessita una guia de referència extensa.
• Pot ser llegit fàcilment per persones no tècniques en el seu format "cru".
• Permet conversió entre sistema imperial i mètric.
• Busca ser quelcom semblant al markdown de les receptes (però que segueixi sent fàcil de processar per programari).

YumML està basat en YAML per crear un format llegible tant per humans com per sistemes.

De yaml.org

Què és: YAML és un estàndard de serialització de dades amigable per a humans, compatible amb tots els llenguatges de programació.

Per què YAML a l'era de la IA

Quan es va redactar l'especificació original de YumML el 2011, la consideració era purament sobre llegibilitat humana i per màquines. Avui dia hi ha un tercer lector a tenir en compte: els Models de Llenguatge de Gran Escala (LLMs).

A mesura que els assistents d'IA es tornen comuns a les cuines (pensa en assistents de veu llegint receptes en veu alta, o chatbots ajudant-te a adaptar receptes), el format que triïs per a dades estructurades importa més que mai. Investigacions recents mostren que el format de dades impacta significativament tant l'eficiència de tokens (cost) com la precisió del model quan els LLMs processen informació estructurada.

Comparatives entre diferents models mostren que YAML fa servir entre un 27-40% menys tokens que JSON i un 38-40% menys que XML per a les mateixes dades. Més enllà de l'estalvi de costos, el format també afecta la comprensió: YAML va assolir una precisió entre 12-18 punts percentuals major que JSON quan els models extreien informació de dades imbricades. La sintaxi més neta amb menys soroll de puntuació ajuda els models a processar el contingut semàntic de forma més fiable. Tot i que JSON minificat pot ser més eficient, sacrifica completament la llegibilitat humana, cosa que va en contra dels objectius fonamentals de YumML.

El millor de tots dos mons

El disseny de YAML aconsegueix un equilibri que funciona bé per a aquest requisit de llegibilitat triple:

• Humans poden llegir-lo sense entrenament (sense claudàtors angulars ni claus)
• Màquines poden processar-lo amb biblioteques estàndard en qualsevol llenguatge
• Models d'IA el processen de forma més eficient i precisa que les alternatives

Això fa que YumML sigui particularment adequat per a aplicacions modernes de receptes on una IA podria ajudar-te a escalar una recepta, suggerir substitucions, o convertir entre sistema mètric i imperial—tot mantenint el format font llegible en un editor de text.

Objectius

Vull definir objectius més formals per a l'especificació.

El format YumML:

• HA DE ser llegible per humans i per sistemes.
• HA DE ser autocontingut, per tant NO HA DE requerir recursos addicionals per ser interpretat.
• HA DE tenir suport per a diferents sistemes de mesures (mètric, imperial).
• HAURIA DE ser fàcil de traduir a diferents idiomes (les receptes tenen una forta influència cultural i l'idioma no hauria de ser una barrera per a qui vulgui entendre-les).
• HAURIA DE ser fàcil de processar usant eines ja existents.
• HAURIA DE ser fàcil d'estendre en el futur.

Detalls Tècnics

• Extensió de fitxer: .yumml (els fitxers HAN DE ser YAML vàlid)
• Tipus MIME: application/x-yumml+yaml
• Codificació: UTF-8

Exemple Bàsic

name: Mrs Fields Choc-Chip Cookies
date: 2011-09-21
prepTime: 15 minutes
cookTime: 10 minutes
ingredients:
  - quantity: 2.5
    unit: cups
    item: plain flour

  - quantity: 0.5
    unit: tsp
    item: bicarbonate of soda

instructions:
  - step: Mix flour, bicarbonate of soda, and salt in a large bowl
  - step: Blend sugars with electric mixer, add margarine to form a grainy paste

Especificació

Hi ha tres seccions principals que tota recepta HA D' incloure: la capçalera, la llista d'ingredients i les instruccions.

Capçalera

La capçalera és una secció implícita on tots els atributs es col·loquen al nivell arrel del fitxer. Tots els atributs HAURIEN D' ubicar-se a la part superior del fitxer, abans d'ingredients i instructions.

Format de durada: Cadenes llegibles per humans. Per a màxima compatibilitat, fes servir nombres enters seguits de minutes, hours o seconds (ex., 15 minutes, 1 hour 30 minutes). Els processadors HAURIEN D' acceptar també abreviacions comunes (15 min, 1 hr) i variacions naturals (1.5 hours).

Exemple

name: Mrs Fields Choc-Chip Cookies
date: 2011-09-21
author: Paul Jenkins
description: Classic chocolate chip cookies, crispy outside and chewy inside.
prepTime: 15 minutes
cookTime: 10 minutes
servings: 4
yield: 24 cookies
tags:
  - cookies
  - chocolate
ingredients:
  - quantity: 2.5
    unit: cups
    item: plain flour

  - quantity: 0.5
    unit: tsp
    item: bicarbonate of soda

instructions:
  - step: Mix flour, bicarbonate of soda, and salt in a large bowl
  - step: Blend sugars with electric mixer, add margarine to form a grainy paste

Ingredients

La secció ingredients és una llista REQUERIDA de tots els ingredients necessaris per a la recepta.

Unitats Canòniques

Per suportar la conversió entre sistemes mètric i imperial, les implementacions HAURIEN DE reconèixer aquestes abreviacions d'unitats canòniques:

Exemple

ingredients:
  # Quantitats numèriques
  - quantity: 2.5
    unit: cups
    item: plain flour

  - quantity: 200
    unit: g
    item: chocolate chips
    notes: semi-sweet

  # Fracció en string (més llegible que 0.5)
  - quantity: "1/2"
    unit: cup
    item: walnuts
    notes: chopped
    optional: true

  # Elements comptables (no necessiten unitat)
  - quantity: 2
    item: eggs
    notes: room temperature

  # Descriptor string per a quantitats imprecises
  - quantity: "to taste"
    item: salt

  # Sense quantitat (implica "una mica de")
  - item: cooking spray
    notes: for greasing

Instruccions

La secció instructions és una llista REQUERIDA de passos per preparar la recepta. Les instruccions suporten dos formats: una llista simple plana o seccions agrupades per a receptes complexes.

Format Simple

instructions:
  - step: Preheat oven
    temperature: 180C
  - step: Mix dry ingredients in a large bowl
  - step: Bake until golden brown
    duration: 10 minutes

Format Agrupat

Per a receptes complexes amb múltiples etapes, les instruccions PODEN organitzar-se en seccions:

Nota d'implementació: Els processadors HAN DE gestionar ambdós formats. Verificar la presència de section per determinar el format: si algun element té un camp section, tractar com a agrupat; en cas contrari, tractar com a simple.

instructions:
  - section: For the dough
    steps:
      - step: Mix flour and salt
      - step: Add water gradually

  - section: For the filling
    steps:
      - step: Sauté onions until translucent
        duration: 5 minutes
      - step: Add remaining filling ingredients

Notes de Disseny

Algunes decisions mereixen explicació.

Per què quantity és opcional i accepta strings

Cuinar és imprecís. Les receptes reals inclouen instruccions com "sal al gust", "un pessic de nou moscada" o "mantega per engreixar". Forçar una quantitat numèrica exclouria aquests casos o portaria els autors a solucions forçades com quantity: 0.

Permetre strings també habilita fraccions com "1/2", que són més llegibles en el context d'una recepta que 0.5. La contrapartida és que els processadors han de gestionar múltiples tipus, però això reflecteix l'ambigüitat inherent de la cuina en lloc de lluitar-hi.

Per què durades llegibles en lloc d'ISO 8601

Les durades ISO 8601 (PT25M) són inequívoques i amigables per a les màquines, però fallen en l'objectiu de "llegible per una persona no tècnica". Un cuiner casolà que fa un cop d'ull a un fitxer .yumml hauria d'entendre immediatament 25 minutes sense necessitat de consultar cap referència.

L'especificació recomana un subconjunt estructurat (enter + unitat) per a eines que necessiten un processament fiable, però manté la flexibilitat suficient per acceptar variacions naturals.

Per què les instruccions suporten dos formats

Les receptes simples no necessiten seccions. Obligar els autors a escriure section: main per a una recepta bàsica de galetes afegeix fricció innecessària. Però les receptes complexes (com un pastís de diversos components) realment es beneficien d'agrupar els passos per etapes.

El disseny polimòrfic prioritza la comoditat de l'autor sobre la simplicitat del processador. La nota d'implementació fa explícita la lògica de processament: verificar section per determinar el format.

Exemple Complet

Aquí teniu un exemple exhaustiu que demostra totes les característiques de YumML:

name: Classic Apple Pie
date: 2024-03-15
author: Jane Baker
description: A traditional apple pie with a flaky butter crust and cinnamon-spiced filling.
prepTime: 45 minutes
cookTime: 55 minutes
totalTime: 1 hour 40 minutes
servings: 8
yield: 1 pie (9-inch)
rating: 5
tags:
  - dessert
  - pie
  - baking

ingredients:
  - quantity: 2.5
    unit: cups
    item: all-purpose flour

  - quantity: 1
    unit: tsp
    item: salt

  - quantity: 1
    unit: cup
    item: unsalted butter
    notes: cold, cubed

  - quantity: 6
    unit: tbsp
    item: ice water

  - quantity: 6
    item: apples
    notes: peeled and sliced (Granny Smith recommended)

  - quantity: 0.75
    unit: cup
    item: sugar

  - quantity: 2
    unit: tsp
    item: cinnamon

  - quantity: 0.25
    unit: cup
    item: caramel sauce
    optional: true

instructions:
  - section: For the crust
    steps:
      - step: Combine flour and salt in a large bowl
      - step: Cut in cold butter until mixture resembles coarse crumbs
      - step: Add ice water gradually, mixing until dough forms
      - step: Divide dough in half, wrap in plastic, and refrigerate
        duration: 30 minutes

  - section: For the filling
    steps:
      - step: Preheat oven
        temperature: 375F
      - step: Toss sliced apples with sugar and cinnamon
      - step: Roll out bottom crust and place in pie dish

  - section: Assembly
    steps:
      - step: Add apple filling to crust
      - step: Roll out top crust and place over filling
      - step: Crimp edges and cut vents in top
      - step: Bake until golden brown and bubbling
        duration: 55 minutes
        temperature: 375F
      - step: Cool before serving
        duration: 30 minutes

Propers Passos

Aquesta especificació és un punt de partida—per ser útil, YumML necessita implementacions. Si t'interessa contribuir:

• Escriu un parser en el teu llenguatge favorit (TypeScript, Python, Go, Rust...)
• Crea un convertidor de schema.org/Recipe a YumML
• Desenvolupa una extensió per a VS Code amb ressaltat de sintaxi i validació
• Experimenta amb LLMs per veure com de bé poden generar i processar YumML

Si construeixes alguna cosa, m'encantaria saber-ho.