Understanding JSON in Minecraft Bedrock Add-ons

Every JSON file in a Bedrock add-on is built from two basic structures: objects and arrays. An object is enclosed in curly braces `{}` and holds unordered key-value pairs. Every key must be a string wrapped in double quotes, followed by a colon, and then its value. An array is enclosed in square brackets `[]` and holds an ordered list of values. Every item in an object or an array must be separated from the next by a comma, except for the very last item in that block.

Indentation and line breaks are ignored by the game engine, which only cares about the structural characters. However, proper indentation (usually two or four spaces per nesting level) is vital for humans so you can visually match every opening brace `{` or bracket `[` with its closing partner. A single mismatched bracket or a missing comma will cause the entire file to fail parsing, meaning your custom block, item, or entity simply will not show up in the game.

Every pack starts with a `manifest.json` file at its root. This file is a clean example of how objects, arrays, strings, and numbers fit together to tell Minecraft what your pack is and which version of the engine it requires.

{
  "format_version": 2,
  "header": {
    "name": "My First Behavior Pack",
    "description": "Demonstrates basic JSON syntax structures.",
    "uuid": "f4c785c2-119b-4821-b4f2-8c636b015b8c",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "a3d901e4-552a-4c88-9a11-3b772e904d12",
      "version": [1, 0, 0]
    }
  ]
}

Values inside a JSON key-value pair or array must belong to one of six strict data types. Minecraft's internal parser expects specific types for specific components. For example, passing the string `"true"` in quotes where the game expects a raw boolean `true` will either throw a content log error or silently fall back to default behavior.

Strings are always wrapped in double quotes; single quotes are never valid in JSON. Numbers can be integers or decimals (floating-point) and are written without quotes. Booleans are the literal words `true` or `false` in lowercase without quotes. Objects and arrays can be nested inside each other to create complex hierarchies, which is how Bedrock groups components inside a file.

While `manifest.json` has its own unique layout, almost all gameplay files in Behavior Packs and Resource Packs follow a standard three-part pattern. At the very top of the root object is `format_version`, a string that tells Minecraft which schema rules to use when reading the file. Different subsystems evolve at different paces, so a block file might use `1.20.80` while an entity file or render controller in the same pack uses an older version string like `1.10.0`.

Immediately inside the root object, alongside `format_version`, sits a domain wrapper key such as `minecraft:block`, `minecraft:item`, or `minecraft:entity`. This wrapper always contains two primary sub-objects: `description` and `components`. The `description` block assigns the custom identifier (formatted as `namespace:name`) and handles registration settings like creative menu categories. Notice that you should never use `minecraft` as your own namespace; always pick a unique prefix for your project.

The `components` object is where you define how the asset actually behaves or looks. Each key inside `components` is a built-in Bedrock component identifier, and its value is usually an object containing the parameters for that mechanic.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "custom:slate_tile"
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.5
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6.0
      },
      "minecraft:friction": 0.4,
      "minecraft:map_color": "#4a4e54"
    }
  }
}

The official JSON specification does not allow comments of any kind. However, Minecraft Bedrock's internal parser supports a relaxed variant often called JSONC (JSON with Comments) for most add-on files. This means you can use double slashes `//` for single-line comments or `/* */` for multi-line comment blocks to leave notes for yourself or temporarily disable components while testing.

Despite the engine allowing comments in most behavior and resource files, relying on them comes with caveats. Some external tools, web-based validators, and strict script parsers will reject a file the moment they encounter a `//` comment. Furthermore, keeping your files as strict, comment-free JSON guarantees they will pass every linter and automated build tool without issue.

If you use a code editor like Visual Studio Code, it may highlight comments in `.json` files as syntax errors by default unless the file association is set to `JSON with Comments`. If you want to store metadata inside strict JSON without breaking validators, it is best to keep your files completely free of `//` lines in production.

Not every string in a Bedrock JSON file is plain text. Frequently, a string value is actually code or a reference to another file. Resource identifiers, such as `"custom:slate_tile"` or `"minecraft:geometry.full_block"`, act as pointers that link behavior definitions, geometries, textures, and translations together across your packs. These strings are case-sensitive and must match their target definitions character for character.

Another common pattern is embedding Molang expressions inside JSON strings. Molang is Bedrock's lightweight math and query language. When a field supports Molang, you write the expression inside double quotes just like a normal string, and the game evaluates it dynamically at runtime. If you need to use quotes inside a string—or escape special characters—you must prefix them with a backslash `\`, though in Molang you generally use single quotes for internal string arguments to avoid escaping.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "custom:healing_stone"
    },
    "components": {
      "minecraft:max_stack_size": 16,
      "minecraft:icon": "healing_stone_texture",
      "minecraft:glint": true,
      "minecraft:display_name": {
        "value": "item.custom:healing_stone.name"
      }
    }
  }
}

Never write JSON in a plain text editor like Notepad. Because a single missing quote or trailing comma breaks the entire file, you need a code editor with live syntax checking, such as Visual Studio Code. A proper editor immediately underlines syntax errors in red and draws indent guides so you can trace which object a closing brace belongs to.

Inside Minecraft, your most important tool is the Content Log. Enable both "Enable Content Log File" and "Enable Content Log GUI" inside Settings under the Creator section. Whenever you load a world with your add-on active, Minecraft parses every JSON file and prints purple or red error messages to the screen if a file cannot be read or if a component value does not match the expected schema.

Applies to all versions of Minecraft Bedrock Edition. No experimental toggles are required to use JSON files, though specific components or format versions inside those files may require current engine versions (such as 1.20.80+).

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