Recipes
Every data-driven recipe type a Java Edition data pack can define — crafting, cooking, stonecutting and smithing — with full schemas, the ingredient and result formats, and copy-pasteable examples. Primary syntax targets 1.21+ (singular recipe/ folder).
Recipe file basics
Each recipe is one JSON file at data/<namespace>/recipe/<path>.json. The file path is the recipe ID: the crafting book and the /recipe command reference it as namespace:path. The type field selects the recipe kind. All recipes share the optional fields below; individual types add their own.
| Field | Type | Applies to | Meaning |
|---|---|---|---|
type | string (required) | all | The recipe serializer, e.g. minecraft:crafting_shaped. |
group | string | most | Recipes sharing a group stack into one recipe-book slot. |
category | string | crafting / cooking | Recipe-book tab. Crafting: building, redstone, equipment, misc. Cooking: food, blocks, misc. |
show_notification | boolean | crafting | Whether unlocking pops a toast. Default true. |
- Since 1.21 (pack_format 48): the folder is singular —
data/<ns>/recipe/. Before 1.21: it was pluralrecipes/. - Since 1.20.5 (pack_format 41): results and item NBT use the data-component system (see The result object). Before 1.20.5: results used
{item, count, nbt}with an SNBT string. - Since 1.21.2 (24w33a): the ingredient format was simplified — the wrapper objects
{"item": …}/{"tag": …}were removed (see Ingredient format).
The result object
The result is the item a recipe produces. Its shape is the single most important version split in this topic.
| Era | result shape |
|---|---|
| pre-1.20.5 (≤ pack_format 26, 1.20.4) | {"item": "minecraft:x", "count": 4, "nbt": "{...}"} — nbt is an SNBT string. |
| 1.20.5+ (pack_format 41, snapshot 24w10a on) 1.20.5+ | {"id": "minecraft:x", "count": 4, "components": { … }} — note item → id and nbt → components. |
count is optional (default 1). components is optional and uses the data-component map format (e.g. minecraft:custom_name, minecraft:lore, minecraft:enchantments). See Data components for the component catalogue.
- Since 1.20.5: result key is
id; custom data lives undercomponents. - Before 1.20.5: result key is
item; custom data is an SNBTnbtstring.
Ingredient format
An ingredient is one of three forms. Ingredients match item type only — they never inspect components, so you cannot require "a sword named X" as a crafting input.
| Form | Example | Matches |
|---|---|---|
| Item ID string | "minecraft:stick" | Exactly that item. |
Tag reference (leading #) | "#minecraft:planks" | Any item in the tag. |
| List of item IDs (OR-match) | ["minecraft:oak_log", "minecraft:spruce_log"] | Any listed item. |
- Since 1.21.2 (24w33a): an ingredient is just an item ID, a
#tag, or an array of IDs. The wrapper-object forms were removed. - Before 1.21.2: ingredients could also be written as
{"item": "minecraft:x"}or{"tag": "minecraft:x"}.
Crafting recipes
crafting_shaped
Shaped crafting matches items in a specific grid layout.
| Field | Type | Meaning |
|---|---|---|
type | string | minecraft:crafting_shaped |
pattern | array of strings | 1–3 rows, each 1–3 chars. A space is an empty slot. Patterns are shift-agnostic (auto-trimmed) but relative positions are preserved. |
key | object | Map of a single pattern character → an ingredient (item, #tag, or list). |
result | result object | Item produced (see result). |
category, group, show_notification | — | Optional shared fields. |
data/<namespace>/recipe/cauldron.json
{
"type": "minecraft:crafting_shaped",
"category": "misc",
"group": "optional_string",
"show_notification": true,
"pattern": ["XXX", "X X", "XXX"],
"key": { "X": "minecraft:iron_ingot" },
"result": { "id": "minecraft:cauldron", "count": 1 }
}
crafting_shapeless
Shapeless crafting matches a set of items in any arrangement.
| Field | Type | Meaning |
|---|---|---|
type | string | minecraft:crafting_shapeless |
ingredients | array | 1–9 ingredients (order irrelevant). |
result | result object | Item produced. |
category, group | — | Optional shared fields. |
data/<namespace>/recipe/map_copy.json
{
"type": "minecraft:crafting_shapeless",
"category": "misc",
"group": "optional_string",
"ingredients": ["minecraft:paper", "minecraft:paper", "minecraft:paper"],
"result": { "id": "minecraft:map", "count": 1 }
}
crafting_transmute 1.21.2+
Changes an item's type while preserving the input stack's components — e.g. re-colouring a shulker box while keeping its contents, or dyeing armour while keeping its trim. Added in 1.21.2 (24w38a); it replaced the hard-coded crafting_special_shulkerboxcoloring.
| Field | Type | Meaning |
|---|---|---|
type | string | minecraft:crafting_transmute |
input | ingredient | The item whose components are carried over. |
material | ingredient | The item consumed to drive the transmute. |
result | item ID / result object | The output item type (see version note below). |
category, group | — | Optional shared fields. |
data/<namespace>/recipe/dye_shulker_blue.json
{
"type": "minecraft:crafting_transmute",
"category": "misc",
"group": "shulker_box_dye",
"input": "minecraft:shulker_box",
"material": "#minecraft:dyes",
"result": "minecraft:blue_shulker_box"
}
- 1.21.2–1.21.4:
resultis a bare item-ID string. - Since 1.21.5 (25w02a):
resultalso acceptscountandcomponents, like other recipes.
crafting_transmute's exact snapshot pinning is well-established, but treat any result component behaviour before 1.21.5 as version-sensitive — verify against a recipe generator if you target older 1.21.x releases.
crafting_special_*
Special recipes are hard-coded logic that is not data-driven beyond the type. A file is just the type — the recipe is enabled by its presence and cannot be meaningfully customised.
data/<namespace>/recipe/firework_rocket.json
{ "type": "minecraft:crafting_special_firework_rocket" }
Known crafting_special_* ID | Handles |
|---|---|
crafting_special_armordye | Dyeing leather armour. |
crafting_special_bannerduplicate | Copying a banner pattern. |
crafting_special_bookcloning | Cloning a written book. |
crafting_special_firework_rocket | Firework rockets. |
crafting_special_firework_star | Firework stars. |
crafting_special_firework_star_fade | Adding a fade to a firework star. |
crafting_special_mapcloning | Cloning a filled map. |
crafting_special_mapextending | Extending a map's zoom. |
crafting_special_repairitem | Combining two damaged items. |
crafting_special_shielddecoration | Applying a banner to a shield. |
crafting_special_shulkerboxcoloring | Colouring shulker boxes. Removed 1.21.2, replaced by crafting_transmute. |
crafting_special_suspiciousstew | Suspicious stew from a flower. |
crafting_special_tippedarrow | Tipping arrows with a lingering potion. |
crafting_special_bundle | Bundle crafting (bundles era). |
Cooking recipes
Four furnace-family types share an identical schema: minecraft:smelting (furnace), minecraft:blasting (blast furnace), minecraft:smoking (smoker), and minecraft:campfire_cooking (campfire).
| Field | Type | Meaning |
|---|---|---|
type | string | One of the four cooking types above. |
ingredient | ingredient | Single ingredient (item, #tag, or list). |
result | result object | Item produced. |
experience | double | XP awarded. Optional, default 0. |
cookingtime | int (ticks) | Optional. Vanilla defaults: smelting 200, blasting 100, smoking 100, campfire_cooking 100. |
category, group | — | Optional. Cooking category: food, blocks, misc. |
data/<namespace>/recipe/kelp_smelt.json
{
"type": "minecraft:smelting",
"category": "food",
"group": "optional_string",
"ingredient": "minecraft:kelp",
"result": { "id": "minecraft:dried_kelp", "count": 1 },
"experience": 0.1,
"cookingtime": 200
}
Stonecutting
Stonecutter recipes convert one input into one output. No group/category semantics apply.
| Field | Type | Meaning |
|---|---|---|
type | string | minecraft:stonecutting |
ingredient | ingredient | Single input. |
result | result object | Output; count defaults to 1. |
data/<namespace>/recipe/stone_to_bricks.json
{
"type": "minecraft:stonecutting",
"ingredient": "minecraft:stone",
"result": { "id": "minecraft:stone_bricks", "count": 4 }
}
Smithing recipes
smithing_transform
Transforms a base item into a new item (e.g. netherite upgrades). The base item's components are preserved in the result.
| Field | Type | Meaning |
|---|---|---|
type | string | minecraft:smithing_transform |
template | ingredient | Smithing template slot. Optional. |
base | ingredient (required) | The item being upgraded; its components carry over. |
addition | ingredient | Material slot. Optional. |
result | result object | Output; count defaults to 1. |
data/<namespace>/recipe/netherite_chestplate.json
{
"type": "minecraft:smithing_transform",
"template": "minecraft:netherite_upgrade_smithing_template",
"base": "minecraft:diamond_chestplate",
"addition": "minecraft:netherite_ingot",
"result": { "id": "minecraft:netherite_chestplate" }
}
smithing_trim
Applies an armour trim component to the base item. There is no result — the base item is modified in place.
| Field | Type | Meaning |
|---|---|---|
type | string | minecraft:smithing_trim |
template | ingredient | Trim template slot. |
base | ingredient | The trimmable armour item. |
addition | ingredient | Trim material. |
pattern | string | Trim pattern ID (see version note). |
data/<namespace>/recipe/coast_trim.json
{
"type": "minecraft:smithing_trim",
"template": "minecraft:coast_armor_trim_smithing_template",
"base": "#minecraft:trimmable_armor",
"addition": "#minecraft:trim_materials",
"pattern": "minecraft:coast"
}
The wiki reports the pattern string became required in 25w04a (1.21.5 development); before that the trim pattern was derived from the template ingredient. Treat the exact snapshot as version-sensitive — for stable 1.21–1.21.4 use the template-only form (omit pattern). Verify against a recipe generator before shipping.
Version-flagged types
The wiki's auto-generated Recipe page attributes two further data-driven crafting types to snapshots on the 26.x line (pack_format 88+, after 1.21.8) — not to 1.21.5 as some summaries claim.
| Type | Intended purpose |
|---|---|
crafting_dye | Data-driven dyeing (target ingredient + dye ingredient → result), intended to supersede hard-coded crafting_special_armordye. |
brewing | Data-driven brewing recipe (input / reagent / output with potion_contents), moving brewing-stand recipes into data packs. |
crafting_dye and brewing do not exist as standard recipe types in 1.21–1.21.8. Their exact version pinning is unverified (sourced from an auto-generated page that mislabeled 26.x snapshots). Do not target them for a 1.21 baseline pack; confirm against a recipe generator or the wiki's data-version history before relying on them.
Tricks & best practices
Disable a vanilla recipe by placing a same-named file in the minecraft namespace of your pack (data/minecraft/recipe/<name>.json) to override it, or remove it at runtime with /recipe take @a minecraft:<name> from a load function.
Craft "custom items" without mods: put unique components (custom custom_data, custom_model_data, attributes) on a recipe result, then pair with a resource-pack model keyed on custom_model_data. See the example below.
data/<namespace>/recipe/custom_named_sword.json (1.20.5+ components in result)
{
"type": "minecraft:crafting_shapeless",
"category": "equipment",
"ingredients": ["minecraft:netherite_sword", "minecraft:nether_star"],
"result": {
"id": "minecraft:netherite_sword",
"count": 1,
"components": {
"minecraft:custom_name": "{\"text\":\"Starblade\",\"color\":\"gold\"}",
"minecraft:enchantments": { "levels": { "minecraft:sharpness": 5 } },
"minecraft:rarity": "epic"
}
}
}
- Tag-driven ingredients (
#tag) make one recipe accept many inputs (e.g. any log). groupcollapses many variants into one recipe-book slot to reduce clutter.
Ingredients ignore components — you cannot require "a sword named X" as a crafting ingredient in vanilla. Use a crafting_transmute or crafting_special pattern, or detect the item with predicates plus /clear and /give in a function instead.