Item Format History and Schema Versions

Every item file in your Behavior Pack (and formerly in your Resource Pack) begins with a `format_version` string. This string does not have to match the current release of the game; instead, it tells the Bedrock engine which set of JSON rules and component schemas to use when reading that specific file. If you declare `1.10.0`, the parser expects the legacy schema where visuals and behaviors were split across two packs. If you declare `1.20.50`, the parser expects all visual and mechanical components to live together inside the Behavior Pack.

Because tutorials and sample packs from the past five years use wildly different schemas, mixing components from one era into a file declared with another era's `format_version` is the single most common cause of silent item failures. Below is a summary of the major milestones in item schema evolution.

When custom items first became usable around version 1.10.0, defining a single item required two separate JSON files: one in `BP/items/` to control stack size and basic mechanics, and a matching file in `RP/items/` to assign the texture icon and creative category. The component names in this era directly mirrored old internal C++ names, such as `minecraft:max_damage` for durability and `minecraft:hand_equipped` to make an item render like a tool in third-person.

Remarkably, the `1.10.0` schema remains backward-compatible in current Bedrock releases without any experimental toggles. However, it is strictly limited in what it can do. You cannot attach custom 3D geometry, define custom digger speeds, or hook into modern `minecraft:custom_components` from a `1.10.0` file. You will still see this format in older resource packs or simple food and currency add-ons.

{
  "format_version": "1.10.0",
  "minecraft:item": {
    "description": {
      "identifier": "wiki:legacy_coin"
    },
    "components": {
      "minecraft:max_stack_size": 64,
      "minecraft:hand_equipped": false,
      "minecraft:foil": true
    }
  }
}

Version 1.16.100 overhauled custom items completely, moving them behind the "Holiday Creator Features" experimental toggle. The biggest structural change was the elimination of the `RP/items/` JSON file. Instead, visual components like `minecraft:icon` (which links to `RP/textures/item_texture.json`) and `minecraft:render_offsets` were placed directly inside the Behavior Pack item file. Creative menu placement also moved into the `description` block via the `category` property.

This era also introduced data-driven item `events` alongside trigger components like `minecraft:on_use` and `minecraft:on_use_on`. Creators could run slash commands, damage items, or apply status effects purely through JSON event responses. While `1.16.100` was the standard for years, Mojang officially deprecated JSON item events and removed the Holiday Creator Features toggle in the 1.20.x cycle. Any item still using `format_version` `1.16.100` will fail to parse or lose its functionality in modern Bedrock.

Starting around 1.20.50 and solidified through 1.20.80 and 1.21.0, the modern item schema reached full stability without requiring experimental toggles for core features. The creative menu assignment was restructured into a dedicated `menu_category` object inside `description`, allowing creators to specify the creative tab (`category`), expandable item group (`group`), and command visibility (`is_hidden_in_commands`).

Many components were renamed and given stricter object structures for consistency. For example, `minecraft:max_stack_size` can now be written as a simple value or an object, `minecraft:display_name` takes a `value` string, and `minecraft:icon` was simplified in 1.20.60+ so its `textures` object (or direct string shorthand) points cleanly to the `item_texture.json` shortname. Most importantly, JSON `events` are completely gone; interactive behavior declared in 1.21.0+ uses `minecraft:custom_components` paired with the `@minecraft/server` Script API.

{
  "format_version": "1.21.0",
  "minecraft:item": {
    "description": {
      "identifier": "wiki:modern_blade",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.sword"
      }
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:hand_equipped": true,
      "minecraft:durability": {
        "max_durability": 500
      },
      "minecraft:damage": {
        "value": 7
      },
      "minecraft:icon": "wiki_modern_blade",
      "minecraft:display_name": {
        "value": "item.wiki:modern_blade.name"
      }
    }
  }
}

When upgrading an add-on from `1.10.0` or `1.16.100` to `1.20.80` or `1.21.0`, you cannot simply bump the `format_version` number at the top of the file. You must also replace retired component keys and restructure their values to match the modern parser expectations.

Use the table below to translate legacy keys into their modern equivalents. For any item that previously relied on `events` and `minecraft:on_use`, you will need to remove the `events` block entirely, register a custom component in a behavior pack script file, and attach its identifier inside the `minecraft:custom_components` array.

Covers schema evolution from Bedrock 1.10.0 through 1.21.0+. Modern items using format_version 1.20.50 or 1.21.0 are fully stable and do not require any experimental toggles.

Read out of the game itself, so the ids match the version you are building for.