JSON Format

All MealieSync JSON files use a wrapper format with metadata for validation. Legacy raw arrays (without the wrapper) are rejected; use Tools/Convert-MealieSyncJson.ps1 to migrate old files.

Wrapper Structure

Every file has the same outer structure:

{
  "$schema": "mealie-sync",
  "$type": "Foods",
  "$version": "1.0",
  "items": [
    ...
  ]
}

Field	Description
$schema	Always "mealie-sync"
$type	Must match the data type: Foods, Units, Labels, Categories, Tags, or Tools
$version	Format version, currently "1.0"
items	Array of items

Food

{
  "id": "b9dc4c47-c569-4630-846f-1f4b4fbda3c1",
  "name": "sour cream",
  "pluralName": "sour cream",
  "description": "Cultured cream; topping for tacos or soups.",
  "aliases": [
    { "name": "schmand" }
  ],
  "label": "Dairy",
  "householdsWithIngredientFood": ["main-household"]
}

Field	Required	Description
id		Stable UUID, shared across language files. Auto-generated by Mealie if missing.
name	yes	Primary name (singular)
pluralName		Plural form
description		Short description
aliases		Array of { "name": "..." } objects
label		Category label name
householdsWithIngredientFood		Array of household names that have this ingredient

Unit

{
  "id": "a1b2c3d4-...",
  "name": "tablespoon",
  "pluralName": "tablespoons",
  "description": "15 ml",
  "abbreviation": "tbsp",
  "pluralAbbreviation": "tbsp",
  "useAbbreviation": true,
  "fraction": true,
  "aliases": [{ "name": "Tbsp" }]
}

Field	Required	Description
id		UUID (auto-generated if missing)
name	yes	Primary name (singular)
pluralName		Plural form
description		Description (e.g., "15 ml")
abbreviation		Short form (e.g., "tbsp")
pluralAbbreviation		Plural short form
useAbbreviation		Show abbreviation in recipes
fraction		Allow fractional values
aliases		Alternative names

Label

{
  "id": "a1b2c3d4-...",
  "name": "Vegetables",
  "color": "#4CAF50"
}

Field	Required	Description
id		UUID (auto-generated if missing)
name	yes	Label name
color		Hex color code (e.g., "#4CAF50")

Category

{
  "id": "a1b2c3d4-...",
  "name": "Main Course"
}

Field	Required	Description
id		UUID (auto-generated if missing)
name	yes	Category name

Tag

{
  "id": "a1b2c3d4-...",
  "name": "asian",
  "mergeTags": ["oriental", "indian", "indonesian", "thai"]
}

Field	Required	Description
id		UUID (auto-generated if missing)
name	yes	Tag name
mergeTags		Array of tag names to merge into this tag. See Tag Merging.

Tool

{
  "id": "a1b2c3d4-...",
  "name": "Oven",
  "householdsWithTool": ["household-name"]
}

Field	Required	Description
id		UUID (auto-generated if missing)
name	yes	Tool name
householdsWithTool		Array of household names that have this tool