Good day, friend!

If you want to learn about making Minecraft datapacks, then you'll eventually come across this neat thing called JSON. Put simply, JSON is a way to store data in a way which makes sense. In datapacks, loot tables, advancements, recipes, worldgen files, item modifiers, and even pack.mcmeta is stored as JSON. Most json files end with .json. However some formats such as pack.mcmeta use json syntax without being JSON.

What actually is JSON?

JSON stands for JavaScript Object Notation. It was created as a way of writing objects in Javascript. These days, JSON is used in almost every programming environment, datapacks included.

JSON is a way of storing information so that both a computer and a human can understand it. It usually stores data as key-value pairs - this means that arbitrary keys (such as "name") can store any type of value (such as "Aron Aronson"). We can easily change the name from Aron Aronson to anything else, and the computer can read it.

A JSON file contains a data value. Usually, the entire file is a JSON Object (aka dictionary). A JSON object is the name of the data type for storing key/value pairs. In a way, it is what it says it is - a dictionary. Multiple KV pairs are separated by commas in a object. Key-value pairs are only found within dictionaries/objects. However, the JSON file doesn't have to just be a object - it can also be an array/list, or anything else really.

Example JSON:

{
  "name":"Aron Aronson",
  "age":83,
  "alive":true,
  "family_members":[
    "James Aronson",
    "Catherine Aronson"
  ],
  "login_details":{
    "email":"aron.aronson@gmail.com",
    "password":"MyNameIsAron12345"
  }
}
Let's go through this file one step at a time:

• It starts and ends with a curly bracket, therefore the file is a JSON Object
• The first key/value (kv) pair is "name", and it has a value of "Aron Aronson". This is a string (piece of text) which has the name of the person.
• The next KV pair is "age", which has an integer (whole number) value of 83.
• The third KV pair is "alive". This is a boolean - it can only be "true" or "false".
• The fourth KV pair is "family_members". This is an array (list) containing many strings (pieces of text).
• The last KV pair is "login_details". This is a object, which contains two more KV pairs: "email" and "password".

Data Types

We've seen most of the data types before in the guide. JSON has these data types. It might not look like much, but using these you can theoretically store any other type of information (for example: date/time can be a number)

Name	Example	Description
String (text)	"Hi! I'm some text."or'Hi I\'m some text!'	A string is a fancy programming word for plain text. You can store any plain text as a string. Strings start and end with either " or ', but if you want to use one of those in the actual text, you need to put a backslash ( \ ) before it
Integer (whole number)*	75	An integer (often called just int) is a whole number without decimals.
Float (decimal number)*	4.92	A float (or floating point number) is a number which is a decimal.
Boolean	trueorfalse	A boolean can only have two values - "true" or "false". Minecraft often treats them the same as 1 and 0
Array	[123,"hello","hi",339]	An array is a fancy name for a list. They start and end with a square bracket. They can store any number of any data type, including other lists. The position an item is in the array is the index - the first item is index 0. For example, "hi" in the array would be position 2.
Object (or Dictionary)	{   "name":"John",   "surname":"Cena",   "age":88 }	An object aka a dictionary is a list of keys and values. They start and end with a curly bracket. Most JSON files are dictionaries. For example, a key here is name, and the value of that key would be "John". The key is always a string, and there can only be one key/value with that name (keys must be unique)
Null	null	Null means "nothing". This data type literally has no value.

Limitations of JSON

Before you start working with JSON, you need to understand these key points and limits to how you can use it.

• A JSON file must itself be a dictionary or an array. A JSON file could not just contain a key-value pair without it being inside a dictionary.
• A key in a object must be a string. For example: these are incorrect syntax:
  123:"Hello",
false:"Hi"
• Technically, JSON treats an integer and decimal number as the same thing. Well in reality, JSON doesn't have opinions. The JSON parser will convert it to the correct data type regardless, as long as the number isn't too big.
• Index [​0] in an array is the first thing in it, [​1] is the second, etc.

Test your knowledge!

Here's an example JSON file. See if you can answer these questions on it.
{
  "earthquake_name":"Tohoku Earthquake",
  "date":{
    "day":11,
    "month":3,
    "year":2011
  },
  "magnitude":9.1,
  "total_damage_cost_usd":360000000000,
  "affected_regions":[
    "Iwate",
    "Sendai",
    "Miyagi",
    "Fukushima"
  ],
  "tsunami":{
    "height_metres":40.5,
    "speed_mph":500
  }
}
1. What data type is "magnitude"?
2. At what index is "Sendai" in the affected_regions array?
3. What data type is "tsunami"?
4. How fast did the tsunami travel?
5. What data type is the year in the date object?

Thanks for reading!

You made it to the end! Hopefully you now know how JSON works. If you want more help, or if you want to improve your skills more, please join our super friendly Discord community: https://discord.datapackhub.net/. We've got teams of people waiting to help you with any questions or projects you may have!

© 2024 Silabear (Datapack Hub). Licensed under CC BY-SA 4.0