# Syntax introduction
The syntax that Jsonic uses is configurable. There is a standard version that you will learn about first in this guide.
Jsonic syntax is a super set of traditional JSON. Every valid JSON document is also a valid Jsonic document.
# Developer experience
The developer experience when using JSON is OK but not great. When JSON is used for editable documents, say for configuration, things get tricky. The lack of comments make life more difficult than it needs to be. The ceremony of quoting all strings is tedious. And dealing with multi-line strings is really nasty.
There are many extensions to JSON that solve these problems (and others) in various ways. All the alternatives that I know about are listed on the alternatives page.
I have taken as many of the good ideas as possible, and combined them into a configurable JSON parser. The basic guiding is: if it isn't ambiguous, it's cool.
Jsonic is also something else&emdash;an extensible parser. If you want to add your own little Domain Specific Languages (DSL) into your JSON documents, Jsonic is built exactly for that purpose! See the custom parsers section for a guide to writing your own JSON-based DSLs with Jsonic
# Walkthrough
Let's first informally describe the syntax extensions that Jsonic provides. For a slightly more formal description, See the railroad diagrams section.
Jsonic is an extension of JSON (opens new window), so all the usual rules of JSON syntax still work.
# Comments
Single line comments can be introduced by #
or //
and run to the
end of the current line:
{
"a": 1, # a comment
"b": 2, // also a comment
}
You also get multi-line comments with:
{
"a": 1,
/*
* A Multiline comment
*/
"b": 2,
"foo": foo,
}
Sometimes you need to comment out a section that already has a
multi-line comment within it. This can be annoying with traditional
multi-line syntax, as the multi-line comment ends with the first end
marker (*/
) seen. Jsonic allows multi-line comments to nest
so you don't have to worry about this anymore:
{
"a": 1,
/*
* /* a multi-line comment
* * inside a multi-line comment.
* */
*/
"b": 2,
}
(Even the syntax highlighter struggles with this one!)
# Keys
You don't have to quote keys. This deals with the most tedious part of
editing pure JSON by hand. We go a little easier than pure
JavaScript
too—you only have to quote keys if they contain
spaces or punctuation.
// jsonic // JSON
{ {
a: 1, "a": 1,
1: 2, "1": 2,
1a: 3, "1a": 3,
"1 a": 4, "1 a": 4,
"{}": 5, "{}": 5,
true: 6 "true": 6
} }
# Commas
This is another essential convenience. You can having trailing commas, which makes cut-and-paste editing much easier.
// jsonic // JSON
{ {
a: 1, "a": 1,
1: 2, "1": 2
} }
Actually, you don't need commas at all. Spaces, tabs, new lines and nothing also separate elements for you:
// jsonic // JSON
{ {
a: 1 "a": 1,
1: 2 "1": 2,
b: [3 4] "b": [3, 4]
c: [[5][6]] "c": [[5], [6]]
} }
Repeated commas do have a special meaning. Any comma without a
preceding value generates a null
value (JSON only has null
, not
undefined
):
// jsonic // JSON
[a,] ["a"]
[,a] [null, "a"]
[,a,] [null, "a"]
[,a,,] [null, "a", null]
[,,,] [null, null, null]
[,,] [null, null]
[,] [null]
You also get null
when a property value is missing:
// jsonic // JSON
{a:,b:} {"a":null, "b":null}
# Strings
Single and double quoted strings work the same way as in JavaScript:
// jsonic // JSON
"a" "a"
'b' "b"
"c'c" "c'c"
'd"d' "d\"d"
'e\te' "e\te"
You also get backticks, which are multi-line:
// jsonic // JSON
`a "a\nb"
b`
And a convenience syntax for indented blocks of text:
// jsonic // JSON
''' "red\ngreen\nblue"
red
green
blue
'''
# Numbers
You get all the JavaScript number formats:
// jsonic // JSON
20 20
20.0 20
2e1 20
0x14 20
0o24 20
0b10100 20
And underscore as way to make large numbers easier to read:
// jsonic // JSON
2_000_000 2000000
The special JavaScript number value literals (such as Infinity
) are
not supported, but you can have them (and other things, like
undefined
) if you use the native plugin.
# Merges
Duplicate keys merge their values when they are objects or arrays, otherwise the last value wins.
// jsonic // JSON
{a:1, a:2} {"a":2}
{a:{b:1}, a:{c:2}} {"a":{"b":1, "c":2}}
{a:[1,2], a:[3]} {"a":[3, 2]}
# Shortcuts
At the top level, you can skip braces and square brackets:
// jsonic // JSON
a:1,b:2 {"a":1, "b":2}
1,2 [1, 2]
You can use repeated key-colon pairs to set a single deep property:
// jsonic // JSON
a:b:1 {"a": {"b":1}}
a:b:[2] {"a": {"b": [2]}}
a:b:2, a:c:3 {"a": {"b": 2, "c":3}}
Open objects and arrays close themselves:
// jsonic // JSON
{a:{b:{c:[1 {"a":{"b":{"c":[1]}}}
# Things that still aren't allowed
You still need to be able to detect actual syntax errors, like misused punctuation in property keys or array elements:
a{b:1 // nope!
a}b:1 // nope!
a[b:1 // nope!
a]b:1 // nope!
[{] // nope!
[}] // nope!
Punctuation cannot occur in property values either as it terminates the value (which is what you want).
// jsonic // JSON
{a:} {"a": null}
{a:{} {"a": {}}
{a:]} // nope!
{a:[} // nope!