The Cookbase Data Model

The Cookbase Data Model (CBDM) is a suite of data format specifications aiming to allow for a solution to represent the data involved in the vast domain of cooking. In order to face such a challenge, CBDM provides a set of data object definitions (ingredients, appliances, preparations, cooking processes…) and a model of the interactions among these elements.

The following sections of this documentation show the conceptions behind the adopted data model, presented in an explanatory (non-exahustive) fashion. For a full description of the data model and types, please visit our repository hosting the complete CBSchema definitions.

The CBDM is organized into five main submodels:

Cookbase Recipe

The design goal of the Cookbase Data Model is to provide a clear, flexible and scalable way to store food preparation data. From this perspective, Cookbase Recipe (CBR) turns to be the main and most relevant interface to the data model.

CBR is a data format that stores metadata and information about a recipe, and presents the ingredients and appliances involved together with the preparation steps that model its interactions and the process workfow.

CBR is conceived to be ‘as-complete-as-possible’ and ‘as-exact-as-possible’, potentially automatable, though allowing enough flexibility to be useful to any user level and application.

The CBR model makes use of data stored by the underlying models for ingredients, appliances and processes. The figure below outlines the CBR Schema format, extracted from its formal CBSchema definition.

The Cookbase Recipe format diagram.

Cookbase Recipe format. [View full-sized image]

Basically, a CBR document consists of five sections: two of them are focused on the metadata and generic information about the recipe, info, yield; and the three core parts of the document, describing the preparation flow and the elements involved in, ingredients, appliances and preparation.

info

Metadata and basic information about the recipe –such as course types or cooking times– are contained into the info object of the CBR document (see CBSchema).

Example: A typical info object.
{
   "name": "Pizza mozzarella",
   "authorship": {
      "fullName": "Hernán Blanco",
      "version": "0.1"
   },
   "releaseDate": "2019-09-01",
   "cuisine": [
      "Argentine"
   ],
   "courseType": [
      "main dish"
   ],
   "preparationTime": {
      "value": 105,
      "measure": "min"
   },
   "cookingTime": {
      "value": 17,
      "measure": "min"
   },
   "servingTime": {
      "value": 1,
      "measure": "min"
   }
}

yield

The yield section (see CBSchema) contains information regarding the form of the recipe output and the way it is to be served.

Example: A typical yield object.
{
   "servings": 8,
   "servingSize": {
      "descriptive": "medium",
      "weight": {
         "value": 160,
         "measure": "g"
      },
      "volume": {
         "value": 400,
         "measure": "ml"
      }
   },
   "servingFormat": "dinner plate"
}

ingredients

A collection of CBR Ingredient objects (see CBSchema) is included in the CBR document, each of them holding an identifier to a Cookbase Ingredient object and the specific information on the ingredient utilized for the recipe. Every ingredient is characterized by the following properties:

  • name: The name given to an ingredient of the recipe
  • cbiId: The identifier to the base CBI document
  • subdivision (optional): A name specifying a subsection of the recipe, into which a number of ingredients can be grouped
  • amount (optional): Description on the ingredient’s quantity applied to the recipe
  • optional (optional): A boolean flag indicating whether the ingredient is optional
  • notes (optional): Any comment on the ingredient that the author considered relevant to remark
Example: A non-optional ingredient ‘tomato purée’, associated to a determined Cookbase Ingredient, and making part of the ‘sauce’ recipe subdivision.
{
   "subdivision": "sauce",
   "name": {
      "text": "tomato purée",
      "language": "en"
   },
   "cbiId": 1978180615,
   "amount": {
      "value": 230,
      "measure": "g"
   }
}

appliances

The list of CBR Appliance objects (see CBSchema) in the CBR document describes all the kitchenware involved in the preparation of the given recipe.

A CBR Appliance can be defined in two different ways:

  1. In association to a determined definition of a Cookbase Appliance
    • name: The name given to an appliance used during the recipe preparation
    • cbaId: The identifier to the base CBA document
  2. Specifying the functions that the appliance is to be able to perform
    • functions: An array containing the different functionalities required to the appliance

On top of the items involved on these two possible instantiation models, the following also apply to any specified appliance:

  • properties (optional): One or more specifications regarding physical properties that the appliance should fulfill, such as size, capacity…
  • optional (optional): A boolean flag indicating whether the ingredient is optional
  • notes (optional): Any comment on the appliance that the author considered relevant to remark
Example: A ‘pizza tray’ appliance indicating its associated Cookbase Appliance, and conditions on its diameter and material.
  {
     "name": {
        "text": "pizza tray",
        "language": "en"
     },
     "cbaId": 1962226524,
     "properties": {
        "diameter": {
           "value": 32,
           "measure": "cm"
        },
        "preferredMaterial": "metal"
     }
  }

preparation

The preparation section represents the sequence of steps that are required to prepare the recipe expressed by the CBR document. It is constructed as a collection of CBR Process objects (see CBSchema) that define the interactions produced during the ellaboration of a recipe with the given ingredients and appliances. The data contained in the preparation object (together with the ingredients and appliances objects) is conceived to allow for the representation of a Cookbase Recipe Graph. This imposes a number of assumptions and conditions that any CBR document must follow to be considered a valid CBR.

A CBR Process is a CBSchema representation of a Cookbase Process, where the following properties are general present:

  • name: The name given to a process of the recipe

  • cbpId: The identifier to the base CBP document

  • parameters (optional): One or more specifications on process end conditions or other process-related attributes that should be taken into account: time, temperature, weight, position in the oven…

  • foodstuff (“abstract”): One or more properties that provide references either to ingredients or to the product of a previously performed (and finished) process. Such references must be strings that match within the same CBR document to the key of either a CBR Ingredient or a CBR Process.

    Different names can be given to a foodstuff property, in order to provide a better insight of its role within the context of a concrete process. This specification is provided in the CBP document.

  • appliances: A list of the appliances involved in the process, referred by strings that match within the same CBR document to a definition of a CBR Appliance. Each appliance is also kept with information on whether it remains used after the finalization of the process or, on the contrary, it is released for other potential uses.

  • residuals (optional): A boolean flag indicating whether the process generates any kind of residual product

  • return (optional): A boolean flag indicating whether the process provides any sort of informative feedback (e.g. a weight measurement)

  • notes (optional): Any comment on the process that the author considered relevant to remark

Example: An ‘adding’ process which is an instance of a given Cookbase Process. In this case, foodstuffsList provides a reference list with the ingredients to be added, and the appliance that is used during the process (remaining used after the process is finished).
{
   "name": {
      "text": "adding",
      "language": "en"
   },
   "cbpId": 3308424952,
   "foodstuffsList": [
      "ing1",
      "ing2",
      "ing3"
   ],
   "appliances": [
      {
         "appliance": "pot1",
         "usedAfter": true
      }
   ]
}

Cookbase Ingredient

The Cookbase Ingredient format diagram.

Cookbase Ingredient format. [View full-sized image]

Cookbase Appliance

The Cookbase Appliance format diagram.

Cookbase Appliance format. [View full-sized image]

Cookbase Process

represents the minimal functional unit of a recipe preparation. It descr

The Cookbase Process format diagram.

Cookbase Process format. [View full-sized image]

Cookbase Appliance Function

The Cookbase Appliance Function format diagram.

Cookbase Appliance Function format. [View full-sized image]