The smallest file
A zip with two entries at its root. This one holds a single recipe.
{
"format": "folio",
"formatVersion": 1,
"scope": "selection"
}[
{
"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.jsonUse 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:00Zor2026-11-08T12:00:00.250Z. - Days
yyyy-MM-ddin 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.
formatVersionchanges only for something an older app can’t safely ignore.
What goes in the archive
| Entry | When | 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 |
- 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.
| Field | Type | Required | Notes |
|---|---|---|---|
| idRequired | string | Yes | Stable and unique, e.g. spaghetti-carbonara. Import merges by id. |
| titleRequired | string | Yes | Not empty. |
| description | string | One or two sentences. | |
| servingsRequired | integer ≥ 1 | Yes | 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 | Yes | |
| photoRequired | object | Yes | The palette that draws the plate, and where the image is. Field by field in recipes.schema.json. |
| ingredientsRequired | Ingredient[] | Yes | May be empty. |
| stepsRequired | Step[] | Yes | May 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.
| Field | Type | Required | Notes |
|---|---|---|---|
| positionRequired | integer ≥ 1 | Yes | Order in the list. |
| quantity | number | The written amount as a number: ½ is 0.5. Null for “to taste”. | |
| quantityTextRequired | string | Yes | As written: "½", "1–2", "400"; "" when there is none. |
| unitRequired | string | Yes | As written: g, ml, cup, tbsp, tsp, clove…; "" for counts. |
| nameRequired | string | Yes | 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 | Yes | 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 | Yes | low marks the line “to check”. |
| nutritionRequired | object | Yes | 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. |
- 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 samefoodIdmerge 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;
mlset 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
lowmarks the line “to check”.- nutritionRequired
- object
kcal,protein,carbs,fatfor 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.
| Field | Type | Required | Notes |
|---|---|---|---|
| positionRequired | integer ≥ 1 | Yes | |
| title | string | “Boil the pasta” | |
| textRequired | string | Yes | |
| 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. |
- 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 ornullmeans 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.
- Check before touching anythingNot a zip, no manifest, a wrong
formator an unreadablerecipes.json: “This file isn’t a Syntagés backup”. A newerformatVersion: “This backup was made by a newer version of the app — update to open it”. - Stay safeEntries 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”. Onlyphotos/entries with an allowed extension are written. - Show a previewThe recipes in the file, how many are new and how many are already here by
id, the new titles and the photo count. - MergeAdds recipes and custom foods whose
idis new, staples whosefoodIdis new, and missing corrections. Settings, groceries, plans and logs are left alone. - ReplaceAsks 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.
- Keys are never readAny 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.
- manifest
.schema.json - recipes
.schema.json - settings
.schema.json - groceries
.schema.json - plans
.schema.json - logs
.schema.json - customFoods
.schema.json - pantry
.schema.json - corrections
.schema.json
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.