Difference between revisions of "Homebrew: JSON Overview"

From 5etools Community Wiki
Jump to: navigation, search
m
m (Some specifics for 5eTools formatting.)
 
Line 89: Line 89:
 
*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.
 
*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.
  
EXAMPLE:
+
'''EXAMPLE:'''
 
  {
 
  {
 
       "source": "5eHP",
 
       "source": "5eHP",
Line 103: Line 103:
  
 
Open braces: '''{''' will open the segment,  
 
Open braces: '''{''' will open the segment,  
next line indents one step a tag (sources) is defined by a string -- we know this because of the quotation marks -- (5eHP). As the next line is part of that same section of the braces a comma ends the lines all the way to "alignment": [ subsection - which indents another step, and since "E" follows "C" - line "C" ends in a comma. "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 which will reduce the indentation 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 unindented with a closing brace '''}'''
+
: 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 unindented with an expected closing brace '''}'''

Latest revision as of 18:37, 12 October 2019

(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

The two primary parts that make up JSON 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, with the key followed 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.

88888 need a simple json to quote here 88888 

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

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.

Arrays

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": [
   "C",
   "E"
]

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.

Objects

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.


Recap

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 subelement 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.

EXAMPLE:

{
      "source": "5eHP",
      "page": 0,
      "name": "Cthurkey",
      "size": "S",
      "type": "aberration",
      "alignment": [
          "C",
          "E"
      ]
}

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 unindented with an expected closing brace }