A JSON superset with additional types from CSS (and comments!)
CSSON is a superset of JSON* that is parsed according to CSS syntax. All JSON can be handled as CSSON, though not every CSS style sheet can be parsed as CSSON.
It aims to be a more flexible and forgiving syntax for humans to work with compared to JSON, and also let developers encode common formats like fragment identifiers and urls.
* a superset of JSON as far as tested - CSS character escapes and JSON string escapes may overlap in a mutually exclusive way in the current implementation — if you know how to verify this, test this, or support this, please open an issue and report any bugs you find!
Since CSSON is parsed according to CSS syntax, any CSS comments /* */
will be safely ignored during parsing or conversion to JSON.
/* It's like JSON… */
{
/* but with comments… */
"demo": [1, 2, 3] /* that can go anywhere! */
}
CSSON is comprised of three kinds of objects: the JSON data types, a few additional types from CSS, and two special CSSON-only enhancements of JSON types that allow CSSON objects as values.
<json-number>
is any JSON-compatible number<json-string>
is any JSON-compatible string, whether single-quoted''
or double-quoted""
<json-true>
is the tokentrue
<json-false>
is the tokenfalse
<json-null>
is the tokennull
<json-array>
is a[
-block containing a,
-separated list of any JSON objects as values<json-object>
is a{
-block containing a,
-separated list of properties with any<json-string>
(single-quoted or double-quoted) for keys and any JSON object as values
<css-ident>
is any CSS-compatible ident token, excluding the reservedtrue
,false
, andnull
JSON types<css-hash>
is any CSS-compatible hash token that starts with#
<css-url>
is any CSS-compatible URL token, whether unquotedurl()
, single-quotedurl('')
or double-quotedurl("")
<css-qualified-rule>
is any CSS-compatible qualified rule containing an optional prelude (used for a selector in CSS), followed by a{
-block containing a;
-separated list of properties with any<css-ident>
for keys and any CSSON object as values
<csson-array>
is a[
-block containing a,
-separated list of any CSSON object as values<csson-object>
is a{
-block containing a,
-separated list of properties with and<css-ident>
as keys and any CSSON object as values
While it's possible to use CSSON to take advantage of the additional types it includes (like URLs) to describe your data in a richer way, if you only want to use CSSON as a more friendly way to managing JSON files or include comments in JSON files that should be fine as well.
CSSON always attemps to parse a JSON type first, so 1
will always be a <json-number>
, not a <css-number>
.
When converting to JSON there are predefined type conversions built into CSSON objects:
ident
"ident"
#hash
"#hash"
url(https://url.com)
"https://url.com"
[one, #two, url(three)]
["one", "#two", "three"]
{
one: one,
two: #two,
three: url(three)
}
{
"one": "one",
"two": "#two",
"three": "three"
}
selector {
property: value;
}
{
"selector": {
"property": "value"
}
}
This package is available on npm and is delivered in two formats:
- index.js is an ES module for use with Deno, QuickJS, browsers, and ES module bundlers
- index.cjs is a CommonJS module for use with Node and CommonJS bundlers
Below are some of the ways you can consume and use this package.
$ npx @csson/csson '/* example CSSON */ [1, 2, 3, a, #b, url(c)]'
$ npx @csson/csson path/to/data.csson
import csson from 'https://unpkg.com/@csson/csson'
console.log(
csson`
/* CSSON Demo */
{
one: one,
two: #two,
three: url(three)
}
`
)
const CSSON = require('@csson/csson/index.cjs')
console.log(
csson`
/* CSSON Demo */
{
one: one,
two: #two,
three: url(three)
}
`
)
To convert a string of CSSON to JSON, supply a string to the CLI script as the first argument:
$ node cli/node.js '/* example CSSON */ [1, 2, 3, a, #b, url(c)]'
$ deno cli/deno.js '/* example CSSON */ [1, 2, 3, a, #b, url(c)]'
$ qjs cli/quickjs.js '/* example CSSON */ [1, 2, 3, a, #b, url(c)]'
To convert a CSSON file to JSON, supply a pathname to the CLI script as the first argument:
$ node cli/node.js path/to/data.csson
$ deno --allow-read cli/deno.js path/to/data.csson
$ qjs cli/deno.js path/to/data.csson
You can run
npm link
if you want to usecli/node.js
on your system as the commandcsson
It's possible to build self-contained executables from the files in this repository in a few different ways.
The first way we can build this into an executable is to use the QuickJS compiler. This will compile cli/quickjs.js into C bytecode, and then compile that into a small self-contained executable:
$ qjsc -o csson-quickjs cli/quickjs.js
For a more optimized output, the QuickJS compiler allows you to exclude unused features. Building CSSON with the following options will produce the smallest executable:
$ qjsc -o csson-quickjs -fno-eval -fno-string-normalize -fno-regexp -fno-proxy -fno-map -fno-typedarray -fno-promise -fno-bigint cli/quickjs.js
The second way to build executables from this repository is to use Node and the pkg package to compile cli/node.js into a self-contained executable that can run even without Node installed:
npx pkg --output csson-node cli/node.js
You may need to supply a
--targets
argument, e.g.--targets node12
, to build this with pkg if there are no build targets available for the latest node version
The default function this package exports can be used with a string, or as a tagged template function, this means you can use it like this:
csson('/* demo */a {}')
csson`{time: ${new Date().toString()}}`
import csson from 'https://unpkg.com/@csson/csson'
// Either of these work
console.log(csson`[one, #two, url(three)]`)
console.log(csson(`[one, #two, url(three)]`))
import csson from 'https://unpkg.com/@csson/csson'
const data = csson`[one, #two, url(three)]`
console.log(String(data))
import csson from 'https://unpkg.com/@csson/csson'
const data = csson`[one, #two, url(three)]`
console.log(JSON.stringify(data))
To see some examples of CSSON files, check out the files in the examples/ folder
Check out the CSSON to JSON converter online