Syntagés, home
For developers

The .folio format

A .folio file is a zip archive holding a whole cookbook or a few recipes. Syntagés uses it for backups and to move between iPhone and Android. Any tool can write one, for example to bring recipes over from another app or a spreadsheet: this page has everything a file needs.

  • Format version 1
  • JSON Schema 2020-12
  • Updated 
cookbook.folio: what a full .folio archive holds
  • manifest.jsonalways
  • recipes.jsonalways
  • settings.jsonfull export
  • groceries.jsonfull export
  • plans.jsonfull export
  • logs.jsonfull export
  • customFoods.jsonfull export
  • pantry.jsonfull export
  • corrections.jsonfull export
  • photos/own photos

The smallest file

A zip with two entries at its root. This one holds a single recipe.

manifest.json
{
  "format": "folio",
  "formatVersion": 1,
  "scope": "selection"
}
recipes.json
[
  {
    "id": "toast",
    "title": "Toast",
    "servings": 1,
    "createdAt": "2026-11-08T12:00:00Z",
    "updatedAt": "2026-11-08T12:00:00Z",
    "photo": { "kind": "none", "tabletop": "#E2DDD4",
               "plate": "#F3EEE4", "food": "#D9A35B",
               "accents": [] },
    "ingredients": [
      { "position": 1, "name": "bread",
        "quantityText": "2", "unit": "slice",
        "aisle": "Bakery", "confidence": "high",
        "nutrition": { "kcal": 160, "protein": 6,
                       "carbs": 30, "fat": 2 } }
    ],
    "steps": [ { "position": 1, "text": "Toast the bread.",
                 "ingredients": [1] } ]
  }
]
zip -X toast.folio manifest.json recipes.json

Use scope selection when the file holds only recipes. Opened with Merge, it adds recipes whose id is new and leaves everything else alone.

Conventions

JSON
UTF-8, one document per file.
Times
ISO 8601 in UTC with a Z, in whole seconds, optionally with up to 9 digits of a second: 2026-11-08T12:00:00Z or 2026-11-08T12:00:00.250Z.
Days
yyyy-MM-dd in the cook’s own time zone.
Numbers
Integers are written without a decimal point. A field marked integer rejects 1.5; a number takes either.
Weights and volumes
Grams and millilitres. Recipes show quantities as written, but every calculation uses grams.
Nutrition
kcal, plus protein, carbs and fat in grams.
Missing and null
An optional field may be left out or set to null; both mean the same. The schemas list which fields are required.
Unknown files and fields
Ignored on import, so a newer minor addition doesn’t break an older app. formatVersion changes only for something an older app can’t safely ignore.

What goes in the archive

Archive layout, version 1
EntryWhenSchema
manifest.jsonAlwaysmanifest.schema.json
recipes.jsonAlways (may be [])recipes.schema.json
settings.jsonFull exportssettings.schema.json
groceries.jsonFull exportsgroceries.schema.json
corrections.jsonFull exportscorrections.schema.json
plans.jsonFull exports; older files hold []plans.schema.json
logs.jsonFull exports; older files hold []logs.schema.json
customFoods.jsonFull exports: the cook’s own foodscustomFoods.schema.json
pantry.jsonFull exports; older files hold []pantry.schema.json
photos/<recipeId>.jpgA recipe’s own photo (jpg, png or heic)No schema
manifest.json
Always
manifest.schema.json
recipes.json
Always (may be [])
recipes.schema.json
settings.json
Full exports
settings.schema.json
groceries.json
Full exports
groceries.schema.json
corrections.json
Full exports
corrections.schema.json
plans.json
Full exports; older files hold []
plans.schema.json
logs.json
Full exports; older files hold []
logs.schema.json
customFoods.json
Full exports: the cook’s own foods
customFoods.schema.json
pantry.json
Full exports; older files hold []
pantry.schema.json
photos/<recipeId>.jpg
A recipe’s own photo (jpg, png or heic)
No schema

recipes.json

An array of recipes. Each id appears once; a second recipe with the same id is ignored. Totals and per-serving values are always computed from the ingredient lines, never stored.

Recipe

One object per recipe.

Recipe fields
FieldTypeRequiredNotes
idRequiredstringYesStable and unique, e.g. spaghetti-carbonara. Import merges by id.
titleRequiredstringYesNot empty.
descriptionstringOne or two sentences.
servingsRequiredinteger ≥ 1YesWhat the amounts are for.
totalMinutesinteger ≥ 0
difficultyEasy · Medium · HardMissing: Easy.
categoryBreakfast · Lunch · Dinner · Snacks · BakingMissing: Dinner.
tagsstring[]["Pasta", "Quick"]
slotsstring[]Meal slot ids the recipe suits: breakfast, lunch, preworkout, dinner, or the cook’s own.
sourceobjectkind (link, text, photo, manual; required in the object), name (site or book), url. Missing: manual.
notestringThe cook’s own note.
createdAt, updatedAtRequiredtimeYes
photoRequiredobjectYesThe palette that draws the plate, and where the image is. Field by field in recipes.schema.json.
ingredientsRequiredIngredient[]YesMay be empty.
stepsRequiredStep[]YesMay be empty.
idRequired
string
Stable and unique, e.g. spaghetti-carbonara. Import merges by id.
titleRequired
string
Not empty.
description
string
One or two sentences.
servingsRequired
integer ≥ 1
What the amounts are for.
totalMinutes
integer ≥ 0
difficulty
Easy · Medium · Hard
Missing: Easy.
category
Breakfast · Lunch · Dinner · Snacks · Baking
Missing: Dinner.
tags
string[]
["Pasta", "Quick"]
slots
string[]
Meal slot ids the recipe suits: breakfast, lunch, preworkout, dinner, or the cook’s own.
source
object
kind (link, text, photo, manual; required in the object), name (site or book), url. Missing: manual.
note
string
The cook’s own note.
createdAt, updatedAtRequired
time
photoRequired
object
The palette that draws the plate, and where the image is. Field by field in recipes.schema.json.
ingredientsRequired
Ingredient[]
May be empty.
stepsRequired
Step[]
May be empty.

Ingredient

Each line keeps what was written and what it was matched to, so a recipe stays the same when the food database changes.

Ingredient fields
FieldTypeRequiredNotes
positionRequiredinteger ≥ 1YesOrder in the list.
quantitynumberThe written amount as a number: ½ is 0.5. Null for “to taste”.
quantityTextRequiredstringYesAs written: "½", "1–2", "400"; "" when there is none.
unitRequiredstringYesAs written: g, ml, cup, tbsp, tsp, clove…; "" for counts.
nameRequiredstringYesAs written: "spaghetti".
notestring"finely chopped"
foodIdstringThe matched food, or custom-… for the cook’s own. Lines with the same foodId merge on the grocery list.
foodNamestring"Pasta, dry"
statestringdry, raw, cooked, drained…: how the food’s numbers are counted.
grams, mlnumberThe line’s weight; ml set for liquids.
densityGPerMlnumber > 0Set where a volume conversion makes sense: rice, flour, sugar, oil, milk, stock.
aisleRequiredstringYesProduce, Bakery, Meat & fish, Dairy & eggs, Grains & pasta, Tins & jars, Baking, Spices & oils, Frozen, Drinks or Other. Any other name is kept and sorted after Drinks.
confidenceRequiredhigh · medium · lowYeslow marks the line “to check”.
nutritionRequiredobjectYeskcal, protein, carbs, fat for the line’s whole amount, not per 100 g. All four required; zeros when unknown.
how, assumptionstringHow the weight was worked out and what was assumed, shown on review.
userCorrectedbooleanThe cook changed the match by hand. Missing means false.
positionRequired
integer ≥ 1
Order in the list.
quantity
number
The written amount as a number: ½ is 0.5. Null for “to taste”.
quantityTextRequired
string
As written: "½", "1–2", "400"; "" when there is none.
unitRequired
string
As written: g, ml, cup, tbsp, tsp, clove…; "" for counts.
nameRequired
string
As written: "spaghetti".
note
string
"finely chopped"
foodId
string
The matched food, or custom-… for the cook’s own. Lines with the same foodId merge on the grocery list.
foodName
string
"Pasta, dry"
state
string
dry, raw, cooked, drained…: how the food’s numbers are counted.
grams, ml
number
The line’s weight; ml set for liquids.
densityGPerMl
number > 0
Set where a volume conversion makes sense: rice, flour, sugar, oil, milk, stock.
aisleRequired
string
Produce, Bakery, Meat & fish, Dairy & eggs, Grains & pasta, Tins & jars, Baking, Spices & oils, Frozen, Drinks or Other. Any other name is kept and sorted after Drinks.
confidenceRequired
high · medium · low
low marks the line “to check”.
nutritionRequired
object
kcal, protein, carbs, fat for the line’s whole amount, not per 100 g. All four required; zeros when unknown.
how, assumption
string
How the weight was worked out and what was assumed, shown on review.
userCorrected
boolean
The cook changed the match by hand. Missing means false.

Step

Method steps, in order.

Step fields
FieldTypeRequiredNotes
positionRequiredinteger ≥ 1Yes
titlestring“Boil the pasta”
textRequiredstringYes
timerSecondsinteger ≥ 1Offers a timer on the step.
ingredientsinteger[] or nullThe ingredient lines the step uses, by their position, listed in cooking mode under “For this step”. [] uses none; absent or null means not known yet, and the app fills it in with an AI key. Positions that match no line are ignored.
positionRequired
integer ≥ 1
title
string
“Boil the pasta”
textRequired
string
timerSeconds
integer ≥ 1
Offers a timer on the step.
ingredients
integer[] or null
The ingredient lines the step uses, by their position, listed in cooking mode under “For this step”. [] uses none; absent or null means not known yet, and the app fills it in with an AI key. Positions that match no line are ignored.

Photos, settings, plans, logs, groceries, pantry and corrections are described field by field in their schemas below.

How Syntagés opens a file

Readers are more forgiving than the schemas: they fill in defaults and skip lines they can’t read. A writer shouldn’t rely on that. A file that passes the schemas imports in full on both platforms.

  1. Check before touching anything
    Not a zip, no manifest, a wrong format or an unreadable recipes.json: “This file isn’t a Syntagés backup”. A newer formatVersion: “This backup was made by a newer version of the app — update to open it”.
  2. Stay safe
    Entries with an absolute path or .. are rejected. Archives over 200 MB uncompressed, or any entry over 20 MB, stop with “This backup is too large to open”. Only photos/ entries with an allowed extension are written.
  3. Show a preview
    The recipes in the file, how many are new and how many are already here by id, the new titles and the photo count.
  4. Merge
    Adds recipes and custom foods whose id is new, staples whose foodId is new, and missing corrections. Settings, groceries, plans and logs are left alone.
  5. Replace
    Asks first, then replaces recipes, groceries, corrections and settings in one step, and plans, logs, custom foods and the pantry only when the file holds them. If anything fails, the existing data stays as it was.
  6. Keys are never read
    Any key-like field in the file is ignored and never stored. Keys in the Keychain or Keystore are never touched.

Schemas

One JSON Schema per file, draft 2020-12. Both apps validate their own exports against them in their tests, so the schemas can’t drift from what the apps really read and write.

All schemas (.zip)

Never write an API key, under any field name. Readers drop apiKey, api_key, accessKey, key and the like, and the settings schema rejects them.