Namespaces and Custom Identifiers

In Bedrock Edition, an identifier is a string split into two parts by a colon: the namespace on the left, and the asset name on the right (for example, `my_pack:copper_coin`). Both parts must be written in strictly lowercase letters. You can use numbers and underscores, and in some contexts hyphens or periods are tolerated, but sticking to `a-z`, `0-9`, and `_` is the safest practice across all engine systems.

The namespace acts as an ownership tag. When the game loads multiple behavior and resource packs into a single world, it merges their contents into one registry. If two different packs define an item simply called `ruby`, the pack higher in the load order will overwrite the lower one, causing bugs in the overridden pack. If one pack uses `magic_mod:ruby` and the other uses `gemcraft:ruby`, both items exist in the game simultaneously without conflict.

Before writing your first JSON file, decide on a namespace strategy. There are two common patterns among add-on developers: choosing a studio prefix (derived from your creator name or team) or choosing a project prefix (derived from the specific add-on's name). For most standalone packs, combining both or using a distinct project abbreviation works best.

Keep your namespace between three and twelve characters. Avoid generic words like `custom`, `addon`, `mod`, `test`, or `new`. If you use `custom:sword` in a published pack, the odds of another creator choosing that exact same identifier are extremely high. Instead, pick something distinct to your project, such as `arcania:silver_sword` or `joes_tinkering:silver_sword`.

The `minecraft` and `minecon` namespaces are strictly reserved for vanilla game content. In older versions of Bedrock, the engine allowed creators to register totally new items and blocks under the `minecraft:` prefix, which caused widespread breaks whenever official game updates introduced features with overlapping names.

In modern format versions (specifically `1.16.100` and later for items and blocks), the Content Log will throw a hard parsing error if you try to define a brand-new asset using `minecraft:`. The only time you should ever put `minecraft:` in the description identifier of a behavior pack file is when you are intentionally overriding and modifying an existing vanilla entity, item, or recipe—such as changing the behavior of `minecraft:creeper` or altering the output of a vanilla crafting recipe.

Note that while your custom asset's identifier must use your own namespace, the components inside that file will still use the `minecraft:` namespace, because those components are built-in engine features.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "underworld:basalt_pillar",
      "states": {
        "underworld:is_cracked": [
          false,
          true
        ]
      }
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.0
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6.0
      }
    }
  }
}

Namespaces are not just for top-level block, item, and entity identifiers. As the Bedrock add-on format has matured, the engine has enforced namespace prefixes on smaller sub-features to prevent collisions inside shared registries.

Custom block states, custom entity properties, block and item tags, recipe identifiers, loot table conditions, particle effects, and custom geometries all use namespaces. Even within the Scripting API, custom component names registered in JavaScript must be prefixed with your namespace.

Your namespace is the bridge that links an object's server-side logic in the Behavior Pack (BP) to its client-side visuals in the Resource Pack (RP). The file names and folder paths do not link these files together; only the string inside `identifier` does.

When you create an entity in your Behavior Pack with the identifier `underworld:imp`, the Resource Pack looks for a client entity definition with that exact same `underworld:imp` identifier to know which model, texture, animation, and render controller to display. If there is even a single character mismatch in the namespace between the two packs, the entity will function in the world (taking damage, moving, making sounds if defined in BP) but will be completely invisible to the player.

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "underworld:imp",
      "materials": {
        "default": "entity_alphatest"
      },
      "textures": {
        "default": "textures/entity/imp"
      },
      "geometry": {
        "default": "geometry.underworld.imp"
      },
      "render_controllers": [
        "controller.render.default"
      ]
    }
  }
}

Applies to all modern Bedrock versions. Strict enforcement rejecting the 'minecraft' namespace on custom items, blocks, and block states applies to format_version 1.16.100 and higher. No experimental toggles are required.

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