.dish File Format Specification

1. File Container

A .dish file is a single JSON document encoded as UTF-8.

The importer auto-detects gzip via the two-byte magic number 0x1F 0x8B. If gzip-compressed data declares an ISIZE greater than 50 MB the file is rejected before decompression begins.

2. Top-Level Object: Recipe

The root JSON object represents a single recipe. All fields are optional unless marked required. Unknown keys are ignored. The importer is intentionally tolerant — invalid or out-of-range values are clamped or replaced with safe defaults rather than rejecting the file.

2.1 String fields

website URL sanitization

The importer normalizes website URLs aggressively:

1. Trims whitespace.
2. If the string contains no ://, prepends https://.
3. Forces scheme to https.
4. Strips query, user, and password components.
5. Rejects (sets to null) if the result has no host.

"website": "https://www.example.com/recipe"

2.2 Numeric fields

All out-of-range values are clamped to the allowed range.

2.3 Enum fields

origin (Int)

How the recipe was originally created. Invalid values are ignored.

Third-party producers should typically use 8 (Website). Users can search for recipes from a particular origin.

meal (Int)

The temporal meal/event the recipe is associated with. Users can filter for recipes from a particular meal. Invalid values are ignored.

cuisines (Array of String)

An array of cuisine identifiers associated with the recipe. Supports fusion recipes with multiple cuisines. An empty or missing array means no cuisine has been assigned.

Each entry is lowercased on import and then validated against the known cuisine values below. Strings that do not match a known value are silently dropped from the array. Duplicate entries are collapsed into a single entry so each cuisine appears at most once.

Valid values: american, argentinian, australian, brazilian, british, caribbean, chinese, colombian, creole, cuban, ethiopian, filipino, french, german, greek, indian, indonesian, italian, jamaican, japanese, korean, lebanese, mexican, moroccan, nigerian, pakistani, peruvian, polish, portuguese, russian, spanish, thai, turkish, vietnamese, other.

"cuisines": ["italian", "french"]

2.4 Identification

2.5 Nested object fields

2.6 Producer-only field

3. Ingredients

A recipe organizes ingredients into one or more named sections (e.g. “For the Crust”, “For the Filling”). The format supports two ways of providing ingredients:

1. Sectioned — set ingredientSections. This is what BrightDish itself exports.
2. Flat — set ingredients instead. The importer wraps the entire flat list in a single auto-created section titled "Other Ingredients".

If a recipe contains only one ingredientSection, BrightDish presents the ingredients as a flat list (it does not display any sectioning UI). Sections will appear only if more than one exists.

3.1 IngredientSection object

3.2 Ingredient object

3.3 Example

{
    "ingredientSections": [
        {
            "title": "For the Crust",
            "sortIndex": 0,
            "ingredients": [
                { "name": "All-purpose flour", "quantity": 2.0, "unit": "cups", "sortIndex": 0 },
                { "name": "Butter", "details": "cold, cubed", "quantity": 0.5, "unit": "cup", "sortIndex": 1 }
            ]
        },
        {
            "title": "For the Filling",
            "sortIndex": 1,
            "ingredients": [
                { "name": "Apples", "details": "peeled and sliced", "quantity": 6.0, "unit": "", "sortIndex": 0 }
            ]
        }
    ]
}

4. Utensils

4.1 Utensil object

Cap: 99 utensils per recipe.

4.2 Example

"utensils": [
    { "name": "9-inch pie pan", "sortIndex": 0 },
    { "name": "Rolling pin", "sortIndex": 1 }
]

5. Steps

A step is a single cooking instruction OR a section header that visually divides the directions list. A recipe may contain a maximum of 99 steps.

5.1 Step object

5.2 kind values

5.3 Example

"steps": [
    { "number": 1, "kind": "sectionHeader", "title": "Make the dough" },
    { "number": 2, "text": "In a large bowl, whisk together the flour and salt." },
    { "number": 3, "title": "Cut in the butter", "text": "Work the butter into the flour with your fingertips until it resembles coarse crumbs.", "imageUUID": "9F3D2B7A-8C42-4E11-A6B0-5D8EFC0A1234" }
]

6. NutritionInfo

A single optional object containing per-serving nutritional values. Every field is an optional Double. A null or missing value means “unknown” and is shown dimmed in the UI; an explicit 0 is treated as a real value (zero of that nutrient).

All values are clamped to 0.0 … 9999.0. Units are fixed by field semantics; the value itself carries no unit.

6.1 Field reference

6.2 Example

"nutritionInfo": {
    "fat": 12.5,
    "saturatedFat": 4.2,
    "carbohydrates": 38,
    "fiber": 3,
    "sugar": 18,
    "protein": 4,
    "sodium": 220,
    "calcium": 40
}

7. Images

7.1 RecipeImage object

7.2 origin values

An integer that describes where an image originated. Invalid values become 0.

Third-party producers should use 0 or 3.

7.3 Embedded image bytes (imageData)

imageData is a base64-encoded image payload. JPEG is the canonical and recommended format. PNG and other formats supported by Apple’s ImageIO are also accepted on import.

Per-image limits enforced on import:

Images exceeding the pixel-count cap are rejected. Images larger than 3,072 px on the longest side are downsampled at decode time.

7.4 Image-Step linking

A Step may attach an image by setting imageUUID to the UUID of a RecipeImage listed in images. The reference must resolve to a uuid that survives the per-recipe cap; otherwise the importer clears it.

7.5 Example

"images": [
    {
        "uuid": "9F3D2B7A-8C42-4E11-A6B0-5D8EFC0A1234",
        "sortIndex": 0,
        "caption": "Finished pie, fresh out of the oven",
        "origin": 2,
        "imageData": "/9j/4AAQSkZJRgABAQEASABIAAD/...<truncated base64>..."
    }
]

8. Tags

User-defined freeform labels (e.g. "weeknight", "gluten-free"). A recipe may contain up to 50 tags.

8.1 Tag object

8.2 Tag deduplication on import

BrightDish performs fuzzy matching when importing tags:

• Names are normalized by replacing dashes with spaces and lowercasing.
• An incoming "gluten-free" matches an existing "Gluten Free" and the recipe attaches to the existing tag rather than creating a duplicate.
• Likewise, an incoming "Gluten Free" matches an existing "gluten-free" and the recipe attaches to the existing tag rather than creating a duplicate.
• If no match exists, the tag is created fresh.

8.3 Example

"tags": [
    { "name": "weeknight" },
    { "name": "gluten-free", "colorHex": "5A9463FF" }
]

9. Sanitization Summary

Every string field is sanitized by the importer, which:

1. Discards leading/trailing whitespace and newlines.
2. Truncates to the field’s maximum length (UTF-8 character count).
3. Substitutes a default if the result is empty (where a default is documented).

Numeric fields outside their allowed range are clamped to the nearest valid value, never rejected.

Array fields exceeding their cap have the excess dropped (the first N items are kept, sorted by sortIndex/number first where applicable).

The importer is intentionally lenient — almost any malformed-but-decodable input produces a valid (if defaulted) recipe rather than a hard rejection. The exceptions:

• Non-JSON / unparseable file bytes
• Gzip stream declaring more than 50 MB uncompressed
• Decompressed bytes exceeding 50 MB
• Any Step missing the required number field

These produce a user-facing import-failure error.

10. Duplicate handling

If the importer finds an existing recipe in the user’s library with a matching uuid, it prompts the user to choose:

• Replace existing — the existing recipe (and all its images) is deleted; the imported recipe takes its place.
• Keep both — the imported recipe is assigned a fresh UUID and added alongside the existing one.
• Cancel — the import aborts.

If you want your .dish files to always import as fresh recipes, generate a fresh UUID for uuid each time you produce the file.

11. Minimal Example

The smallest viable .dish file. Everything except steps[].number may be omitted.

{
    "title": "Toast",
    "summary": "Bread, made warm.",
    "ingredients": [
        { "name": "Bread", "quantity": 1, "unit": "slice" }
    ],
    "steps": [
        { "number": 1, "text": "Toast the bread in a toaster until golden brown." }
    ]
}

12. Full Example

{
    "uuid": "8B1C44A2-3F22-49DF-9E3D-1EBD5C7AAB10",
    "origin": 6,
    "title": "Apple Crumble",
    "summary": "A warm autumn dessert with cinnamon-spiced apples under a buttery oat topping.",
    "meal": 4,
    "cusines": ["american"],
    "rating": 4.5,
    "difficulty": 3,
    "prepMinutes": 20,
    "cookMinutes": 40,
    "additionalMinutes": 0,
    "servingsCount": 6,
    "yield": "1 9-inch crumble",
    "servingSize": "1 cup",
    "calorieCount": 380,
    "notes": "Best served warm with vanilla ice cream.",
    "author": "John Smith",
    "source": "Family Recipe",
    "website": "https://example.com/apple-crumble",

    "ingredientSections": [
        {
            "title": "For the Filling",
            "sortIndex": 0,
            "ingredients": [
                { "name": "Apples", "details": "peeled, cored, sliced", "quantity": 6, "unit": "", "sortIndex": 0 },
                { "name": "Brown sugar", "quantity": 0.5, "unit": "cup", "sortIndex": 1 },
                { "name": "Cinnamon", "quantity": 1, "unit": "tsp", "sortIndex": 2 },
                { "name": "Lemon juice", "quantity": 1, "unit": "tbsp", "sortIndex": 3 }
            ]
        },
        {
            "title": "For the Topping",
            "sortIndex": 1,
            "ingredients": [
                { "name": "Rolled oats", "quantity": 1, "unit": "cup", "sortIndex": 0 },
                { "name": "All-purpose flour", "quantity": 0.5, "unit": "cup", "sortIndex": 1 },
                { "name": "Brown sugar", "quantity": 0.5, "unit": "cup", "sortIndex": 2 },
                { "name": "Butter", "details": "cold, cubed", "quantity": 0.5, "unit": "cup", "sortIndex": 3 }
            ]
        }
    ],

    "utensils": [
        { "name": "9-inch baking dish", "sortIndex": 0 },
        { "name": "Mixing bowl", "sortIndex": 1 }
    ],

    "steps": [
        { "number": 1, "text": "Preheat the oven to 350°F (175°C)." },
        { "number": 2, "kind": "sectionHeader", "title": "Make the filling" },
        { "number": 3, "text": "Toss the sliced apples with brown sugar, cinnamon, and lemon juice in a large bowl." },
        { "number": 4, "text": "Transfer the apple mixture to the baking dish." },
        { "number": 5, "kind": "sectionHeader", "title": "Make the topping" },
        { "number": 6, "text": "Combine the oats, flour, and brown sugar. Cut in the cold butter until the mixture resembles coarse crumbs." },
        { "number": 7, "text": "Sprinkle the topping evenly over the apples." },
        { "number": 8, "text": "Bake for 40 minutes, until the topping is golden and the filling is bubbling." }
    ],

    "nutritionInfo": {
        "fat": 14,
        "saturatedFat": 8,
        "carbohydrates": 62,
        "fiber": 5,
        "sugar": 38,
        "protein": 3,
        "sodium": 95
    },

    "images": [
        {
            "uuid": "9F3D2B7A-8C42-4E11-A6B0-5D8EFC0A1234",
            "sortIndex": 0,
            "caption": "Fresh out of the oven",
            "origin": 2,
            "imageData": "/9j/4AAQSkZJRgABAQEASABIAAD/...<truncated>..."
        }
    ],

    "tags": [
        { "name": "dessert" },
        { "name": "weeknight", "colorHex": "5A9463FF" }
    ]
}

13. Producer Checklist

Before publishing .dish files for distribution:

• Use UTF-8 encoding throughout.
• Either gzip-compress the JSON (recommended for files with embedded images) or leave it uncompressed.
• Stay under 50 MB after decompression.
• Provide a fresh uuid per published file unless you intend duplicate detection to fire.
• Provide every Step.number (the only truly required field).
• Encode embedded imageData as base64-encoded JPEG; keep each image under 100 megapixels.
• Cap your images array at 20 — anything beyond is silently dropped.
• Stay within array caps: 10 ingredient sections, 100 ingredients per section, 99 utensils, 99 steps, 50 tags.
• Set Step.imageUUID to the uuid of an entry in images, never to an arbitrary UUID.