JSON in 5 minutes

Almost every add-on file is written in JSON. It is a simple way to write data as text, and it has only a handful of rules. Learn them once and you can read any add-on file.

A first look

Here is a small JSON file that describes a pet:

{
  "name": "Biscuit",
  "age": 3,
  "is_friendly": true,
  "favorite_foods": ["bone", "cookie"],
  "owner": {
    "name": "Alex",
    "level": 12
  }
}

Read it out loud: "Biscuit is 3, is friendly, likes bones and cookies, and is owned by Alex who is level 12." That is all JSON is: names and values.

The building blocks

Objects

An object is wrapped in curly braces { }. It holds key and value pairs:

• The key is always text in double quotes, like "name".
• A colon : separates the key from its value.
• A comma , separates one pair from the next.

Every add-on file starts with an object, so the first character is always { and the last is always }.

Arrays

An array is a list wrapped in square brackets [ ]. Items are separated by commas. The order matters.

{
  "version": [1, 0, 0],
  "tags": ["sword", "weapon"],
  "rows": [
    { "item": "minecraft:stick" },
    { "item": "minecraft:diamond" }
  ]
}

An array can hold numbers, text, objects, or even other arrays.

Values

There are only a few kinds of values:

Watch the types. 64 and "64" look alike, but the first is a number and the second is text. If Minecraft expects a number and you give it text, the setting is ignored or the file fails to load.

Nesting: how add-on files are shaped

Objects can sit inside objects. Add-on files use this a lot to group things. Here is a real item file:

{
  "format_version": "1.26.30",
  "minecraft:item": {
    "description": {
      "identifier": "demo:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:max_stack_size": 16,
      "minecraft:icon": {
        "textures": {
          "default": "ruby"
        }
      }
    }
  }
}

Follow the path from the outside in: the file has a "minecraft:item" object, which has a "description" and "components". Inside components, "minecraft:max_stack_size" is set to the number 16. When this wiki says "set minecraft:max_stack_size in components", this is the spot it means.

Tip: indent each level by two spaces. The game does not need it, but it makes the shape easy to see.

Identifiers and namespaces

Everything you add needs an identifier: a unique name made of two parts separated by a colon.

demo:ruby

• The part before the colon is the namespace. It is like your signature.
• The part after it is the name of the thing.

Minecraft's own content uses the minecraft namespace, as in minecraft:diamond. Never use minecraft for your own content. Pick something short and unique, like your initials or project name: sam:ruby, dragons:fire_egg.

Rules that keep you safe:

1. Use only lowercase letters, numbers and underscores.
2. No spaces. Use ruby_sword, not ruby sword.
3. Use the same namespace in your whole add-on.
4. Once players have your item in their worlds, do not rename it, or those items will disappear.

Component names like minecraft:icon use the minecraft namespace too, because they are built into the game. You can look up every one in the item components reference.

format_version

Most files start with a "format_version". It tells Minecraft which version of the file layout you wrote, so the game knows how to read it. Note that it is text in quotes, like "1.26.30", in item, block and entity files, but a plain number 2 in manifest.json.

When in doubt, copy the format version from a working example on this wiki, and keep it the same across files of the same type.

Common mistakes

These five mistakes cause most broken packs.

1. Trailing commas

A comma after the last item is not allowed.

{
  "nutrition": 4,
  "saturation_modifier": 0.6,
}

Remove the comma after 0.6 and it works.

2. Missing commas

The opposite problem: forgetting a comma between two pairs.

{
  "nutrition": 4
  "saturation_modifier": 0.6
}

Add a comma after 4.

3. Missing or wrong quotes

Keys and text need double quotes, both at the start and the end.

{
  name: 'Ruby'
}

The fixed version is { "name": "Ruby" }.

4. Brackets that do not match

Every { needs a } and every [ needs a ], in the right order. VS Code highlights the matching bracket when you click next to one, which makes this easy to check.

5. Comments

Standard JSON has no comments. You may see // comment lines in some of Mojang's sample files, and the game does skip them in many places, but other tools and validators will reject them. The safest habit is to leave comments out of your JSON.

Other file types

Not everything is JSON. You will also meet:

• .lang files: plain key=value lines for names, like item.demo:ruby.name=Ruby.
• .mcfunction files: one command per line. See Functions.
• .js files: JavaScript for scripts.
• .png files: textures.

Skipping the JSON

If all these brackets feel like a lot, you are not alone. In GodCraft you never type JSON: you fill in forms with sliders, toggles and pickers, and the app writes valid files every time. It is a quick way to make something that works, and you can always come back here to learn what the app wrote for you.

Now that you can read JSON, try Your first custom item, or learn how to get your pack into the game in Export and play.