Using JSON Schemas for Add-on Validation

Minecraft Bedrock add-ons are driven almost entirely by JSON files. Because JSON is a generic data format, a standard text editor only cares about basic syntax rules: matching curly braces, quoting keys, and separating items with commas. A plain editor has no idea that a Bedrock block file needs a format_version key, or that typing minecraft:destructable_by_mining with an 'a' instead of an 'i' will cause the game to silently ignore your block's mining speed.

A JSON schema bridges this gap. It is a blueprint written in the JSON Schema standard (typically Draft-07) that defines the exact structure, data types, and allowed values for a specific kind of Bedrock file. When your code editor links a schema to the file you are editing, it reads that blueprint in the background and checks your work in real time.

This validation happens entirely inside your editor—most commonly Visual Studio Code (VS Code). Minecraft itself does not read your schema files or your editor settings. If you use the $schema property inside a behaviour pack file, the game's JSON parser simply ignores that property during pack loading, treating it like a harmless comment.

For most creators, the fastest way to get working schemas is to install the Blockception Minecraft Bedrock Development extension in VS Code. Instead of requiring you to download and maintain hundreds of schema files manually, the extension bundles up-to-date community schemas for entities, blocks, items, loot tables, spawn rules, and resource pack files.

For the extension to automatically match the right schema to your file, your project must follow standard Bedrock folder conventions. The extension looks at the path of the file you have open. If a file sits inside a folder named blocks inside a behaviour pack, it applies the block schema. If it sits inside entities, it applies the entity schema. A messy project structure where files are stored in arbitrary folders will prevent automatic matching from working.

If you prefer not to use an extension, or if you have a custom workspace layout, you can map schemas manually using VS Code's workspace settings. By creating a .vscode/settings.json file at the root of your project, you can use the json.schemas array to associate specific file glob patterns with local or remote schema definitions.

{
  "json.schemas": [
    {
      "fileMatch": [
        "BP/blocks/**/*.json",
        "*behavior_pack*/blocks/**/*.json"
      ],
      "url": "./schemas/behavior/blocks/blocks.json"
    },
    {
      "fileMatch": [
        "BP/items/**/*.json",
        "*behavior_pack*/items/**/*.json"
      ],
      "url": "./schemas/behavior/items/items.json"
    },
    {
      "fileMatch": [
        "RP/entity/**/*.json",
        "*resource_pack*/entity/**/*.json"
      ],
      "url": "./schemas/resource/entity/entity.json"
    }
  ]
}

Sometimes you need to validate a single JSON file without setting up workspace folders, or you want to enforce a custom schema on a specific file. You can do this by adding the $schema key at the very top of your JSON object, right above format_version.

The value of $schema is a path (either a relative file path on your computer or a web address) pointing to the schema definition file. As soon as you save or reload the file, VS Code reads the target schema and applies its rules to the rest of the document.

When you package your add-on into a .mcpack or .mcaddon file for distribution, you do not need to strip out the $schema lines. Minecraft's internal parser only looks for format_version and the primary root object (such as minecraft:block or minecraft:entity). Unknown top-level keys like $schema are safely skipped without generating content log errors.

{
  "$schema": "../../schemas/behavior/blocks/blocks.json",
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "custom:slate_tile"
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 1.5
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6.0
      },
      "minecraft:geometry": "minecraft:geometry.full_block"
    }
  }
}

Once a schema is active, you can stop memorizing exact component syntax and let the editor guide you. Pressing Ctrl + Space inside a JSON object triggers IntelliSense. If your cursor is inside the components object of a block file, the editor will pop up a searchable list of every valid block component. Selecting one from the list automatically inserts the key and, depending on the component, scaffolds the required brackets or default values.

Hovering your mouse over any existing key brings up a tooltip explaining what that property does, what default value Minecraft assumes if you leave it out, and what data type it expects. When you make a mistake, the editor underlines the problem in yellow or red. Opening the Problems panel in VS Code gives you a plain-English breakdown of why your file is invalid.

Bedrock schemas rely heavily on the format_version field at the top of your file to know which rules to apply. Over the years, components have changed from simple booleans to complex objects, and others have been replaced entirely. A well-written schema uses conditional logic to switch its validation rules based on the version string you provide.

For example, in older block format versions, geometry and mining properties used different component names than they do in 1.20.80. If you copy a modern component like minecraft:destructible_by_mining into an older file with format_version set to 1.16.0, a version-aware schema will flag it as an invalid property.

Conversely, if you update your format_version to the latest release, the schema will immediately highlight legacy components that have been deprecated or removed in that version. Always set your format_version before you begin writing components so the schema gives you accurate advice for the target version of the game.

If you work on a large add-on with a team, you might want to enforce stricter rules than vanilla Minecraft requires. For instance, you might want to ensure every custom item uses your team's specific namespace, or restrict which components junior designers are allowed to use. Because JSON Schema is an open standard, you can write your own lightweight validation files.

The example below is a valid Draft-07 JSON Schema that validates a basic custom item file. It requires format_version and minecraft:item to be present, forces the item identifier to start with the namespace studio:, and restricts the components list to a small, curated set of properties: minecraft:max_stack_size, minecraft:hand_equipped, and minecraft:glint.

By setting additionalProperties to false inside the components definition, any component not explicitly listed in this schema will trigger a warning in the editor. You can save this file in your project folder and link it via .vscode/settings.json to enforce project-wide coding standards.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Studio Custom Item Schema",
  "type": "object",
  "required": [
    "format_version",
    "minecraft:item"
  ],
  "properties": {
    "$schema": {
      "type": "string"
    },
    "format_version": {
      "type": "string",
      "enum": [
        "1.20.50",
        "1.20.80"
      ]
    },
    "minecraft:item": {
      "type": "object",
      "required": [
        "description",
        "components"
      ],
      "properties": {
        "description": {
          "type": "object",
          "required": [
            "identifier"
          ],
          "properties": {
            "identifier": {
              "type": "string",
              "pattern": "^studio:[a-z0-9_]+$",
              "description": "Must use the 'studio:' namespace and lowercase letters."
            },
            "menu_category": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string",
                  "enum": [
                    "construction",
                    "nature",
                    "equipment",
                    "items",
                    "none"
                  ]
                }
              }
            }
          },
          "additionalProperties": false
        },
        "components": {
          "type": "object",
          "properties": {
            "minecraft:max_stack_size": {
              "type": [
                "integer",
                "object"
              ]
            },
            "minecraft:hand_equipped": {
              "type": [
                "boolean",
                "object"
              ]
            },
            "minecraft:glint": {
              "type": [
                "boolean",
                "object"
              ]
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  }
}

Applies to all Minecraft Bedrock versions. Schema validation is an external editor feature and requires no in-game experimental toggles. However, community schemas typically track the latest stable Bedrock release (such as 1.20.80 or 1.21.x), so files using very old format versions or brand-new preview features may occasionally show false warnings in your editor.

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