Block Format History and Schema Versions

Every custom block JSON file in a behavior pack begins with a `format_version` string. This string does not necessarily have to match the exact version of Minecraft you are running, nor does it need to match the `min_engine_version` in your pack's `manifest.json`. Instead, it acts as a contract with the game's JSON parser, dictating which components are valid, how their fields are structured, and whether experimental world toggles are required to load the block.

When Mojang updates a block component—such as renaming a field or changing a boolean into an object—they gate that change behind a newer `format_version`. This ensures backward compatibility so older add-ons continue to function when players update their game, unless the underlying experimental feature itself is completely removed from the engine.

Custom blocks gained most of their flexibility in the 1.16.100 update under the Holiday Creator Features experimental toggle. Prior to this, custom blocks were limited to simple unit cubes whose textures and render methods had to be registered inside the resource pack's root `blocks.json` file. Format version `1.16.100` moved visual definitions like `minecraft:geometry` and `minecraft:material_instances` directly into the behavior pack file.

This era also introduced block states, permutations, and an event system driven entirely by JSON (`minecraft:on_interact`, `minecraft:on_step_on`, and `minecraft:on_player_placing`). Many older code examples online still show this syntax. However, the JSON event architecture was never stabilized and has since been completely stripped from modern versions of Bedrock.

{
  "format_version": "1.16.100",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:legacy_crate"
    },
    "components": {
      "minecraft:destroy_time": 2.0,
      "minecraft:explosion_resistance": 5.0,
      "minecraft:unit_cube": {},
      "minecraft:material_instances": {
        "*": {
          "texture": "legacy_crate_tex",
          "render_method": "opaque"
        }
      }
    }
  }
}

During the 1.19 cycle, Mojang began moving block components out of experimental toggles and into the base game. Rather than keeping the 1.16.100 names as-is, many components were redesigned for clarity and consistency before being locked in as stable features. If you change a block's `format_version` from `1.16.100` to `1.19.40` or `1.19.50` without updating the component names, the block will fail to parse.

For example, `minecraft:destroy_time` became `minecraft:destructible_by_mining`, and `minecraft:explosion_resistance` became `minecraft:destructible_by_explosion`. The old `minecraft:unit_cube` component was retired in favor of using the standard block geometry identifier `minecraft:geometry.full_block` inside the `minecraft:geometry` component. Additionally, custom block properties inside the `description` block were standardized under the `states` key.

Across the 1.20 updates, the block format gained quality-of-life features that reduced repetitive boilerplate. In `1.20.20`, block traits were introduced under the `description` object. Traits like `minecraft:placement_direction` and `minecraft:placement_position` automatically inject standard cardinal, facing, or vertical-half states onto a block without requiring an external script or placement event to read the player's rotation.

The `minecraft:geometry` component also expanded during this period. Instead of creating multiple separate `.geo.json` files to toggle parts of a model on and off across permutations, creators can now define `bone_visibility` directly inside the `minecraft:geometry` component using booleans or Molang expressions, alongside the built-in `minecraft:geometry.full_block` identifier.

The largest breaking change in block format history occurred in 1.20.80 and 1.21.0. Mojang retired the Holiday Creator Features toggle and permanently removed JSON block events, event responses (`set_block_state`, `run_command`, `decrement_stack`), and all `minecraft:on_*` trigger components from the engine. Any pack relying on those components in newer versions will log content errors and ignore the triggers.

In their place, `1.21.0` introduced `minecraft:custom_components`. Instead of writing imperative logic inside JSON, you attach a named custom component to your block or permutation and register its behavior in JavaScript using the `@minecraft/server` API during world initialization.

{
  "format_version": "1.21.0",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:modern_crate",
      "menu_category": {
        "category": "construction"
      },
      "traits": {
        "minecraft:placement_direction": {
          "enabled_states": ["minecraft:cardinal_direction"]
        }
      }
    },
    "components": {
      "minecraft:geometry": "minecraft:geometry.full_block",
      "minecraft:material_instances": {
        "*": {
          "texture": "modern_crate_tex",
          "render_method": "opaque"
        }
      },
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.0
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 5.0
      },
      "minecraft:custom_components": [
        "wiki:crate_interaction"
      ]
    }
  }
}

Applies to all Bedrock versions from 1.16.0 through 1.21+. Modern blocks using format_version 1.21.0 and standard components require no experimental toggles.

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