Homebrew: JSON Overview

From 5etools Community Wiki
Revision as of 13:41, 3 October 2020 by Modnar (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

(from Tutorial Point)

What is JSON?

JSON stands for JavaScript Object Notation

JSON is a is a lightweight text-based open standard designed for human-readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. Conventions used by JSON are known to programmers, which include C, C++, Java, Python, Perl, etc.

So, in way, learning JSON can help you understand some of the more common ways to store your data.

Keys and Values

Enclosing everything in braces: { ... }, which is describing an object in the JSON data format The two primary parts that make up JSON formated elements are keys and values. Together they make a key/value pair.

Key: A key is always a string enclosed in quotation marks.
Value: A value can be a string, number, boolean expression, array, or object.
Key/Value Pair: A key value pair follows a specific syntax, are separated by a colon (:) followed by the value. Key/value pairs are comma separated.

Let's take one line from a JSON sample and identify each part of the code.

"key": [ "value" ],

This example is a key/value pair. The key is "key" and the value is "value".

All text values are enclosed in double quotes ("), this is critical (and means using quotes (") inside text values requires some special handling (talked about later)

JSON in general is:

Types of Values

  • Array: An associative array of values.
*Boolean: True or false.
*Number: An integer.
*Object: An associative array of key/value pairs.
*String: Several plain text characters which usually form a word.
Numbers, booleans and strings are self-evident, so we'll skip over those sections. Arrays and Objects are explained in more depth below.


Almost every type has categories and tags. In this example the value might look unfamiliar, but the reasoning we will tease out. Since each type will have a few specialied fields, an array of multiple strings can be used if the filters need to return fuzzy concepts.
"alignment": [
In the above segment, the code denotes that the alignment of the entry is "C" and "E" which, in this case, means Chaotic Evil. There are several elements of the schema that do require some degree of familiarity not just with JSON but the specifics on what the data types will mean. Those specifics are covered in the review of the various homebrew data types' schemas.


An object is indicated by curly brackets. Everything inside of the curly brackets is part of the object. We already learned a value can be an object. So that means "foo" and the corresponding object is a key/value pair.
"foo" : {
 "bar" : "Hello"
The key/value pair "bar" : "Hello" is nested inside the key/value pair "foo" : { ... }. That's an example of a hierarchy in JSON data.


We said at the beginning of this tutorial that JSON is a minimal data format. Just by learning a few key principles you can decode an entire site's worth of JSON. And now you can apply that knowledge to converting Homebrew content into 5eTools with JSON.

General rules for JSON Lint compatibility in formatting

*Indent after opening a punction section, reduce indention by one tab when ending a section
*Brackets or Square Brackets [ ] or Braces or Curly Brackets { }, must open and close the various sections.
*Quotation marks "" denote a string (alphanumeric content follows)
*An orphaned set of punctuation will cause the JSON validation to fail.
*The order punctation is opened and closed must be preserved  { [ "  will fail if not matched in the reverse order " ] } 
** { [ " " ] } - Will Work
** { [ " } ]  - Will Fail (not closing one ("") of them)
** { [ " } ]" - Will Fail (Closing them out of order)
** { [ " { ]] " - Will Fail (Double Opening or double closing)

Quotation marks inside a set of quotation marks will END that string and that will often mean the remain string's text will fail validation.
"Ragnar yelled "HELP!!" at top of his lungs."  
will be viewed as Strings "Ragnar yelled " and " at top of his lungs." respectively, and between them HELP!! will be an unidentified tag/command - and so the validation will fail. instead, try:
  • (BEST) "Ragnar yelled \"HELP!!\" at top of his lungs." using two \" tells the parser to just produce the " to the screen, as its not structural to the code.
  • (SLOPPY) "Ragnar yelled ' 'HELP!!' ' at top of his lungs." using two '' apostrophes, or
  • (Meh) "Ragnar yelled “HELP!!” at top of his lungs." using open and close quotes ( “ ” ) (&ldquo and &rdquo in HTML also known as Ascii codes 0147 and 0148.
The comma (outside of quotation marks "" ) signifies the end of a line and that another element in that section or a new subsection will follow. The lack of a comma signifies the END of a section or subsection.
  • When another of the same element type (see Formatting) follows another line, that line must end with a comma (,)
  • When no other line of the same element or a new sub-element follows. That line must NOT end with a comma (,)

Some specifics for 5eTools formatting.

  • Try to use tabs instead of spaces in the file for legibility/line indents, most editors do this automatically, but mixing them will cause problems down the line. Be consistent
  • Try to tag elements (@disease, @spell, @creature, @item, @background, @race, @optfeature, @class, @condition, @disease, @reward, @feat, @psionic, @boon, @trap, @hazzard, @deity, @variantrule, @cult or even @table so that the document is dynamic and mouse over tips can bring up the content easily.
  • Do not reuse meta names in new documents. Duplication doesn't exist, the cite will ignore one of the duplicates, and you don't get any say on which one remains when there is a conflict around such.


      "source": "5eHP",
      "page": 0,
      "name": "Cthurkey",
      "size": "S",
      "type": "aberration",
      "alignment": [

Open braces: { will open the segment,

next line indents one step - a tag (sources) is defined in a string (we know this because of the quotation marks "5eHP").
As the next line is part of that same section and more data follows this line, a comma ends the line.
page is defined as a numeric value (no quotes), as 0 (again as the next line is part of that same section and more data follows this line, a comma ends the line.)
name is defined (string - in quotes) (again as the next line is part of that same section and more data follows this line, a comma ends the line.)
and so one all the way to "alignment": at which a new subsection is starte ( [ denotes the opening of such) - it indents another step, and since "E" follows "C" - line "C" ends in a comma. But "E" has nothing following it in that section so no comma is put at the end of the line and the next line will close that subsection with a closing bracket (]) and the indentation on the next line will reduce by one step. That closure is also the last element with that segment the open brace { defined so it also will have no comma and the program now knows that the next line will be un-indented with an expected closing brace }

For a more detailed explanation, Go here