What's a .json? (A Beginners Guide to JSON)

As you create files for your data packs, you may begin to wonder what exactly a JSON file is, and what everything inside of it means.

Although you don't need to understand everything to use it well, it's still good to know what exactly you're doing.

There are many tutorials online, but I'll make this one super duper simple.

Oh, and before we get started: any code you see that's written "likeThis"? That's camelCase.

camelCase is a special way of writing that's often used in code.

Don't be confused, it should look like that: first word lowercase, second word Uppercase (not CAPS), and no spaces.

---

INDEX:

• String: A line of plain text. Always written in quotations.

• Number: A number, written as is. Sometimes can be a decimal.

• Object: Used to hold a multiple Key/Value pairs. Can also hold other Objects and Arrays.

• Array: Used to hold multiple Values, or Objects, separated by commas.

• Boolean: Used when data can only be one of 2 values.

• Null: A unique keyword used for keys that don't have values yet, but also aren't empty. Usually for the acknowledgement of the lack of a value. When referenced by a Boolean, it returns as "false". You won't see Null used in Minecraft JSON, but it's still good to know.

• Syntax: The way words or text have to be arranged for the language to work.

• Parsing: The program reading code and allowing it to work (barebones explanation). If code isn't parsed, it won't run.

---

Here are some syntax rules that must be followed when writing JSON:

• All data in JSON files must be in Key/Value pairs.

• All lines in the file must end with a comma if there is more data after it.

• When writing Strings in single quotations (' '), you must be consistent in writing all Strings in single quotes.

Allow me to explain each term. I'll try to be brief.

To help explain things, I'll be using the analogy of a fruit salad. It'll make sense as you read.

All JSON files must start with an Object, as everything is contained inside--it's the "bowl" in our fruit salad. After all, you can't just leave all the fruits on the table.

For the sake of not confusing anyone later, I will be referring to this specific object (the one that contains the entire file) as the Root Object.

This is an Object.

{}

It's written as 2 {curly brackets}, one to open and close it. Everything goes between them.

{
    "example": "text"
}

You don't have to put them on separate lines, but it makes it easier to read visually.

Doing it like this also works fine.

{"example":"text"}

That "example text" there is a Key/Value pair. The first part, "example", is the Key.

The Key can be something like "Name", "Money", "Age", things like that.

All Keys must be Strings, keep that in mind.

After writing the Key, you place a colon ( : ) AFTER inside the quotations.

So, this would work:

{
    "fifty": 50
}

But neither of these would.

{
    50: "fifty",
    "fifty:" 50
}

As long as the Key has quotations on it, it's a String.

The second part, "text", is the Value. Literally the Value of what the Key is.

The Value can change depending on what you want to track with the Key.

Let's say your Key is "Money". Your Value could be a Number, like 500, or it could be a String, like "Five Hundred".

Again, Strings are the only value type that uses quotations.

Adding quotations to something will turn it into a String!

Your Key/Value pairs are basically the "fruit" in your salad. The Values are your different kinds of fruit. Apples, bananas, kiwis, etc.

Here's an example below.

{
    "name": "John",
    "age": 50
}

"name" and "age" are the Keys. "John" and 50 are the Values.

In this case, we can see that "John" is 50 years old. If there were more Key/Values here, we could potentially learn more about John.

Oh, but look! There's a comma after "John" right?

Why's that?

It's because the program won't parse anything unless we tell it that there's more to parse, and we do that by adding commas to the end of our code lines.

Each comma tells it to read another line. No comma tells it to stop, so the last line doesn't have one because otherwise the program wouldn't stop.

Let's see an example of an Object by using Minecraft:

{
    "parent": "minecraft:item/generated",
    "textures": {
        "layer0": "item/apple",
        "layer1": "item/stick"
    }
}

In this file, we can see a few things.

Whatever this file is for, it's using "minecraft:item/generated" as its parent.

So, it's probably using the data from that as a base.

Next, it's using 2 textures: "item/apple" and "item/stick". Stick is layered above apple, so it would appear like this:

Seeing all of this, it's safe to assume that this is a JSON item model file.

It's a file that determines how a specific item renders in-game.

Even though it's only an example, this code would actually work in-game because JSON model files are surprisingly easy to set up if you want something barebones.

Before we move onto Arrays, take a look at the code example again.

{
    "parent": "minecraft:item/generated",
    "textures": {"layer0": "item/apple", "layer1": "item/stick"}
}

See that? I compressed it so you can see.

You can contain Objects inside of other Objects!

This is why I defined the first object that contains the whole file as the Root Object.

While the Root Object is the bowl, all other Objects are like those watermelons that you can hold other fruit in by carving them out.

Here's a bit of a complicated example to explain.

{
    "username": "Steve",
    "accAge": 300,
    "hasFriends": true,
    "numOfFriends": 1,
    "friends": {...}
}

Inside this example, we can see that it's tracking a player named Steve.

Their account age is 300 (the unit of measurement isn't important), and we know they have at least 1 friend because "hasFriends" says so.

"numOfFriends" tells us that he has 1 specifically.

Now, you can see that "friends" has that Object inside.

I put those dots there to convey that we could potentially put another list like this one inside of it, like so:

{
    "username": "Steve",
    "accAge": 300,
    "hasFriends": true,
    "numOfFriends": 1,
    "friends": {
        "username": "Alex",
        "accAge": 100,
        "hasFriends": true,
        "numOfFriends": 1,
    }
}

See how we can start getting confused? We just put a watermelon bowl inside of our fruit salad, and that bowl can have its own fruit salads inside... if that makes sense.

Next up, let's talk about Arrays. Yeah, I know. All of that talk was just for Objects.

While Objects are like the watermelon bowls inside our original bowl, Arrays are like bowls made of cantaloupes.

Objects can hold a multitude of Key/Value pairs, but only 1 Value per pair.

Arrays, on their own, can hold a multitude of Values! When used as a Value itself, we can basically give a single Key multiple Values instead of just 1.

Of course, Objects can be placed inside of Arrays, and vice versa.

We create Arrays by using [square brackets]. I included a regular Key/Value too.

{
    "example": ["text1","text2","text3"],
    "example2": "text"
}

And here's an Array with an Object.

In this example, because the Object is inside the Array, the entire Object now counts as a single Value for the Key! This lets us add another Object!

{
    "types": [
        {
            "formal1": "hi",
            "formal2": "hello",
            "formal3": "howdy"
        },
        {
            "informal1": "yo",
            "informal2": "what's up",
            "informal3": "what's good"
        }
    ],
    "exampleNumber": 2 
}

Since there's a second Object, we add a comma after the first one to tell the program there's more data to read inside that Array.

I also added that "exampleNumber" so you can see how you can add regular Key/Values after an Array. Just remember the comma.

Here's the same thing simplified...

{"types": [{...},{...}], "exampleNumber": 2}

Ok, now let's get an example of this using Minecraft:

{
  "items": [
    {"items": ["minecraft:iron_boots"]}
  ]
}

Here, we can see that the "items" Key is using an Array as its Value. This Array is using an Object itself, and inside the Object is another "items" Key/Value.

If we zoom out another step, we can get some additional context.

{
  "parent": "minecraft:story/smelt_iron",
  "criteria": {
    "iron_boots": {
      "conditions": {
        "items": [
          {
            "items": [
              {"items": ["minecraft:iron_boots"]}
            ]
          }
        ]
      },
      "trigger": "minecraft:inventory_changed"
    }
  }
}

Now, we can see that this is supposed to be an Advancement file, which controls what achievements players can receive.

In this file, the "iron_boots" key (which has "conditions" and "items" as children) is actually nested under "criteria", which handles what is required to receive the achievement.

If I write it like this...

{
    "parent": "minecraft:story/smelt_iron",
    "criteria": {
        "iron_boots": {"conditions": {"items": [{...}]},...}
    }
}

...you can see how all of that fits.

I omitted the "trigger" part as it's too long, that's what the extra "..." at the end is.

In fact, let's add the other parts of the criteria.

{
    "parent": "minecraft:story/smelt_iron",
    "criteria": {
        "iron_boots": {"conditions": {"items": [{...}]},...},
        "iron_helmet": {"conditions": {"items": [{...}]},...},
        "iron_chestplate": {"conditions": {"items": [{...}]},...},
        "iron_leggings": {"conditions": {"items": [{...}]},...}
    }
}

The reason why "criteria" doesn't use an Array, while the "items" Key inside each of these do use Arrays, is because "criteria" doesn't need to.

An Array is only for having multiple Values under one Key, while an Object can have multiple Key/Values.

Yes, you could have an Array with multiple Objects inside that each have a Key/Value, but why would you create more work for yourself like that?

(Here's an example of how messy this is)

{
	"parent": "minecraft:story/smelt_iron",
	"criteria": [
	{
		"iron_boots": {...}
		},
	{
		"iron_helmet": {...}
		},
	{
		"iron_chestplate": {...}
		},
	{
		"iron_leggings": {...}
		},
	]
}

(Shortened version, ewww)

{
	"parent": "minecraft:story/smelt_iron",
	"criteria": [{"iron_boots": {...}},{"iron_helmet": {...}},{"iron_chestplate": {...}},{"iron_leggings": {...}},]
}

Ok ok ok, now we can move on. I said I'd keep this brief, sorry!

A Value has to be a valid JSON data type.

The valid types (or fruits, if we're still using our fruit analogy) are:

1. Strings

2. Numbers

3. Objects

4. Arrays

5. Booleans

6. Null

The explanation for each of them is listed in the Index up top.

I already explained Objects and Arrays, so let's flash through the last few.

Strings are very simple. Write anything inside of quotations, and it's a String.

You could even write a Number with quotations and use that as a Key, because it's no longer a Number.

But always remember that Keys must be Strings!

Numbers are really simple. Just write the Number as is, no quotations.

Periods ( . ) are allowed if the Number is a decimal.

Lastly, Booleans will be familiar to you if you use literally any other kind of code.

They allow you to specify a Yes or No outcome.

They don't have to specifically be "yes" or "no", either. As long as the code (the JavaScript)

has specified what means yes and no, you can use any of those options.

A safe bet for Minecraft code is to write "true", "false", "yes", "no", "1" or "0".

I won't go over Null because you won't be using it with Minecraft JSON. But, if you were curious, you could use it to give a Value a placeholder.

What I mean by this is, if you wanted to state that a player doesn't have any friends on their account without leaving the Object for it empty, you could replace the Object with:

{
    "username": "Steve",
    "accAge": 300,
    "hasFriends": false,
    "numOfFriends": 0,
    "friends": null
}

And that's the jist of it! JSON is a very easy code language to understand, since it meshes directly with JavaScript.

JavaScript, on the other hand, is a bit harder to get, but if you're just doing vanilla Minecraft file stuff, JSON is all you'll need.

Feel free to read some of my other tutorials, and leave a comment if this helped you!

Have a great day.