What is this? Since most of this game's modding is done via editing JSON configuration files, I think it is important that modders take time to learn about the format itself and the common "gotcha's" for those that unfamiliar with the format. What is JSON? JSON stands for JavaScript Object Notation. It is currently the most widely accepted and preferred data transportation format due to the rise in popularity of REST and other web application design patterns. Many document-based NoSQL implementations also use JSON as their storage format. JSON basically replaced XMLs, which were insanely cumbersome, verbose and resource taxing for programs to parse. Though I personally believe that Starbound devs could have went one step further and implemented YAML, which is much easier to read and write for modders (who are usually not developers.) More about JSON: http://en.wikipedia.org/wiki/JSON More about YAML: http://en.wikipedia.org/wiki/YAML Basics There are two types of "containers" in JSON, an Object and an Array Code: { "key": "value" } , [ "value1", "value2" ] Curly brackets define an object, leaving it empty defines an empty object Code: { "key": "value } , {} Square brackets defined an array, leaving it empty defines an empty array Code: [ "value1", "value2" ] , [] You can have as many tiers of nested items as you like, it can be any combination of object within object, array within array, object within array, or array within object. Code: { "object1": { "array1": [ { "name":"array item 1" }, [ "array item 2" ], { "values":[ "1","2","3" ] } ] } } You may have noticed that most JSON files open with a { and closes with a }. This is required because whatever is parsing the JSON will return an object once its done, and these brackets define this return object. Optionally you can actually just open a JSON file with [ and close it with a ]. This way the return value from the parser will be an array, not an object. Keep in mind that if you were to do it this way, all the immediate children must not be key'd since it is now an array. Code: [ { "name": "Bob" }, { "name": "Sally" } ] Data Types JSON has the same data types as Javascript itself, minus a few like "function." Inherently JSON is "weak-typed." See the wikipedia entry for all of the data types in depth: http://en.wikipedia.org/wiki/JSON#Data_types.2C_syntax_and_example Number ( numbers must not have quotations around them ) Code: { "value1": 25, "value2": 0.1 } String ( strings must have double quotes around them ) Code: { "value": "abc" } Boolean ( bools must not have quotations around them ) Code: { "key1": true, "key2": false } Array ( arrays must not be associated arrays and cannot have keys ) Arrays are ordered by their sequence that you defined them Code: { "key": [ 1, 2, 3, 4 ] } Object ( objects must be key-value pairs ) Objects are unordered and will not follow the sequence that you defined them Code: { "key": { "value": 1 } } Null ( null values must not have quotes around them ) Null is basically an empty value that is defined. In Javascript, if you do "typeof" on a null value, it will return the type of "object." So basically, null is a special type of object. Code: { "key": null } Common "Gotcha's" The last item in an object or array must not have a trailing comma. This probably accounts for 99% of the invalid hand-typed JSON problems out there. Note the last comma in the invalid example Valid: Code: { "key1", "value1", "key2", "value2" } Invalid: Code: { "key1", "value1", "key2", "value2", } You cannot have comments in JSON. JSON is a data format, not a scripting or programming language, thus it does not support comments. Invalid: Code: { //"key1", "value1", "key2", "value2" } Invalid: Code: { #"key1", "value1", "key2", "value2" } Invalid: Code: { /*"key1", "value1",*/ "key2", "value2" } Objects must be key-value pairs Valid: Code: { "key": "value" } Invalid: Code: { "value" } Arrays cannot be associated arrays and thus cannot have keys If you want to have associated arrays, use objects Valid: Code: [ "value1", "value2" ] Invalid: Code: [ "key": "value" ] All keys must be between double quotes, or else its invalid. You may see some Javascript developer using the keys without the quotes, this is not valid JSON and is bad practice. The reason it works is because without the quotes, it is valid Javascript and the JS parser will let it through. But this is not valid JSON, and if you tried to send it to a non-Javascript environment, it will throw a parse error exception. Valid: Code: { "key": "value" } Invalid: Code: { key: "value" } Strings are always in quotes, numbers are always not in quotes Code: "15" is not 15, these are not the same things, the first is a string, the second is a number. Complete Example Below is the JSON example from wikipedia, note the placement of the commas, quotes, lack of quotes, etc: Code: { "firstName": "John", "lastName": "Smith", "age": 25, "address": { "streetAddress": "21 2nd Street", "city": "New York", "state": "NY", "postalCode": 10021 }, "phoneNumbers": [ { "type": "home", "number": "212 555-1234" }, { "type": "fax", "number": "646 555-4567" } ] } Useful Tools The best way to make sure your JSON is valid is to simply test it, using a parser: http://json.parser.online.fr/ If its invalid, you'll get a highlight of the error. Hope this thread was useful to you.
Does starbound allow for comments in JSON? You say comments aren't valid in JSON. However official starbound assets seem to have comment lines. So does starbounds implementation of JSON allow for commenting?
Starbound's JSON files are weird... They do allow for comments with //. However, it's not exactly standard JSON. Someone actually made a thread about it: http://community.playstarbound.com/...s-assets-as-standard-json.52518/#post-1521920 ... And I'd agree. I think that: Code: "comment" : "foo bar" is better than: Code: // foo bar Anyway, nice tutorial. There's also some nice flow charts at: http://json.org/
Its possible their parser simply allows it, just like how you can comment on JSONs that are embedded in Javascript. JSON by default does not allow comment though, if you were to send a JSON with a comment to a REST api for example, it will simply error out.
