JSON is a common format for data exchange and configuration. The name stands for "JavaScript Object Notation", because it was extracted from the JavaScript specification, but you don't need to know JavaScript to use and read it.

JSON is used by many programs and has no relation to the DDDG project. We just use it. We can't make any changes to the format itself and are bound by it's limitations. In this text, whenever the word "character" is used, it refers to a text character, a symbol/letter/number, not a DDDG character.

They are written as plain text files and can be edited with any simple text editor, like Notepad. However, I suggest using a programming editor like VS Code. This will highlight the text in different colors to help readability, show you red underlines when you have errors in your file, and, if configured correctly, can even autocomplete what you are trying to type.

Note for people with no programming experience: Aside from whitespace (Any character that is not visible, like space and line-breaks), which you can basically use wherever and however you like, data formats like JSON are very strict. They will not try to interpret what you have written, they will not guess on your behalf, it will not ignore sections it cannot read. Your text either follows the exact rules and works, or it's broken and will not work at all. A single stray comma can make a file unusable to DDDG. That is why I suggest a programming editor like the above to show you when and where you have errors.

JSON files can contain 4 kinds of values:

• Objects
• Arrays
• Numbers
• Strings
• Booleans
• Null

Numbers

Numbers are fairly self-explanatory. You know what numbers are. They are used for things like the sizes or positions of something. They are written as plain digits:

1
20
301234

Numbers can have decimal parts after a . (dot) symbol. (Other decimal separators, such as the , (comma) used in some countries are NOT supported)

1.03
20.99
301234.1005069

Numbers can be preceded by a - (minus) symbol to make a negative number.

-42

For either very large or very small numbers, you can use the Scientific E notation. Any of the previous numbers can be followed by E (or e) and another (whole, non-decimal) number. The comma in that number is than shifted by the amount after the E. You probably won't encounter any of that in a DDDG file, it's just here for completeness.

-42E10 (equivalent to -420000000000)
42E-10 (0.0000000042)

There is no such thing as thousands separators in JSON.

Strings

A "string" in computer science describes a sequence of characters. (A "string" of characters) They are used to store text as is and signify that the text is not meant to be read as JSON code.

Strings start and end with " (double quotes) and can have (almost) any characters in between.

"This is a text"
"45"
"The previous one is not a number. It's still text, as long as it's in double quotes"

Sometimes, you might need to use the symbol " (double quotes) in your text. For that, you can precede it by a \ (backslash) to indicate that the quote does not end the string.

"\"This is a text with quotes\", he said"

The backslash is what is known as an "escape character". It changes how the letter after it is interpreted. The backslash and the character after it together are called an "escape sequence".

If you actually want to use a symbol \ as part of your text, you need to write \\, two backslashes.

"Like this: \\"

A string may also not contain line breaks. Those are instead written as \n.

"Line 1\nLine2"

There are also other escape sequences \b, \f, \r and \u followed by four numbers, but those are not often used and are not relevant for this document.

NOTE: Many beginners try to write bare text without quotes into the file and expect JSON to just know that it is text. That is not how JSON works. It only sees a bunch of unexpected characters and throws an error. As stated before, JSON will not guess what you wanted to do. Strings have to be in quotes.

Booleans

A boolean is like a switch. It can either be true or false. They are like on or off, yes or no. There is no in-between.

true
false

Null

null marks an explicitly non-existing value.

Array

An array is a list of values. They start with [ (opening bracket), end with ] (closing bracket) and the values are separated using , (comma). They can contain any type of other values, even other arrays or objects.

[1, 2, 3]
["Array", "of", "strings"]
[  "Whitespace doesn't matter"     ]
[
  "Arrays",
  "can span",
  "multiple",
  "lines" 
]
["Mixed types are allowed", 43, null, true]

What kind of values are expected in a given array will be written in the specification. It will say something like "Array of strings".

NOTE: A common mistake is to end an array with a , (comma). This is not allowed. The , (comma) may only be in between the values. (Something that is widely considered to be a misstep of the JSON format, but isn't fixable at this point)

Objects

Objects are the most complex data type in JSON, and the one the format is named after. It is made up of pairs of keys, which are always strings, and values, which can be of any type, even arrays or other objects. They have an : (colon) in between and multiple pairs are separated by , (comma)

{
  "key": "value",
  "height": 521,
  "alias": ["KV", "Dictionary"],
  "coordinates": {
    "x": 60,
    "y": 20
  },
  "isGood?": true
}

This allows you to bundle multiple values and give each of them a name (the key), so you can see what the values represent.

Every key is only allowed once per object.

The specification will tell you what keys an object is supposed to have, and what type the value should have. Keys that are not in the specification are not seen as errors, but will be ignored by the program.

NOTE: A common mistake is to end an object with a ,. (comma) This is not allowed. The , (comma) may only be in between the key-value-pairs. (Something that is widely considered to be a misstep of the JSON format, but isn't fixable at this point)

A json file

The file starts immediately with one single value. This value is called the root. Theoretically it can be of any type, but it is most often an object, sometimes an array, depending on the specification.

A note on formatting

You might have noticed the indentation with spaces that is done in the examples for arrays and objects. This is entirely optional. Spaces and newlines outside of values mean nothing to JSON and are only used to make the file more readable.

When you have a long array or an object with multiple key-value-pairs, it is generally encouraged to write every value or pair on a separate line, and indent them with spaces. Commonly 2 or 4 spaces are used, sometimes the tab-character (The one you get when you press the "⭾" key on your keyboard). Whichever you pick is not important, but you should pick one and stick with it.

Having your values correctly indented makes it easier to see where a multi-line object/array starts and where it ends.

{
  "level": 1,
  "child": {
    "level": 2,
    "child": {
      "level": 3
    }
  }
}

Note that VSCode will help you with indentation automatically. But should it get messed up, you can right click on your text and select "Format document".