RJSON

[sebmck]

Rome contains a custom JSON parser at packages/@romejs/codec-json. The primary motivation for building this was JSON.parse does not emit detailed information for syntax errors. So I decided to build a vanilla JSON parser with detailed errors that emits Rome diagnostics (#3).

Once I had this built, it was quite easy to add JSON extensions. So I did. They are only enabled when a filename is passed in that ends in .rjson, so the parser can parse with and without.

These extensions do not add additional data types and are purely syntactic. When using extensions with a regular JSON file, the error messages will specifically mention it.

The features of RJSON are as followed.

Unquoted keys

If a property key is a valid identifier then the quotes can be omitted, just like in regular JavaScript.

{
  unquotedKey: true
}

Optional commas

Commas are not required to separate elements of an array or object properties.

Example

[
  1
  2
  3
]

{
  a: 1
  b: 2
  c: 3
}

Numeric separators

With the addition of numeric separators in JavaScript, support has been added in RJSON.

Example

5_000

Comments

Standard JS comments are supported. Both line and block comments.

The comment support also allows the manipulation of an RJSON file, while retaining comments.

Example

{
  // Line comment
  /* Block comment */
  foo: "bar"
}

Implicit top level object

Curly braces at the top level aren't required if it's just a list of properties.

Empty input is treated as an empty implicit object.

Example

foo: "bar"
"bar": "foo"

[Haroenv]

What is the reason you added no-comma support? Three others are js features, so that makes sense, but I haven’t seen commaless before. Is it to be closer to yaml/rc?

[sebmck]

I added optional commas because they can unambiguously be added. I started with just omitting all the syntax I could while still feeling JSONish. Colons could also theoretically be made optional but I feel like that's stepping over "the line".

[ishpartko]

I added optional commas because they can unambiguously be added. I started with just omitting all the syntax I could while still feeling JSONish. Colons could also theoretically be made optional but I feel like that's stepping over "the line".

Why do you need to create another data format when there are formats already familiar to the people? Like .js/.ts/.json/.yaml

It's good when people read about this new format, but usually it's easier for people who work a lot to use the familiar syntaxes.

And it will be easier for code editors, they are more comfortable dealing with familiar syntaxes than with "erroneous json"/ "plain text" in their opinion.

What do you think, @sebmck ?

[sebmck]

You can already use .json. There does not exist a JS parser and stringifier today for YAML or another format that has the ability to retain comments, which I see as the sole motivation for having a custom JSON format.

[talentlessguy]

json5 support for configs would be cool too

https://json5.org/

[sebmck]

JSON5 does not allow for the reserialization of files and retaining comments. Are you proposing that it be reimplemented?

[talentlessguy]

@sebmck

maybe I got you wrong but:

json5 allows making comments

also what does "reserialization" mean?

[talentlessguy]

sorry, for getting away from the issue topic, but

another cool format that I just remembered, Toml

npm package | toml repo

I suggest TOML because unlike yml or json it is actually readable and simple. Example

[dev_server]
port = 3000
host = '127.0.0.1'

[stephenwf]

@talentlessguy This I believe: https://codesandbox.io/s/recursing-star-33xfn when you parse you only have the option of getting back an object representation. consumeJSONExtra in RJSON implementation keeps the comments.

[sebmck]

@talentlessguy

also what does "reserialization" mean?

Reading a file, changing something, and then reserializing it back and retaining the original comments. Exactly what @stephenwf said.

[sebmck]

@talentlessguy Do you know of any JavaScript tooling that uses TOML? Previously Rome did actually use TOML but after reading https://hitchdev.com/strictyaml/why-not/toml/ and seeing it's extremely limited usage in the JavaScript community I pivoted. I know it sounds contradictory since RJSON is some unique-only-for-Rome JSON, but I would consider syntax omission to not be as big of a deal.

[sebmck]

RJSON adds the same syntax extensions as JSON5 except RJSON allows omitting syntax and you cannot use single quotes.

[sebmck]

This article resonated strongly and motiviated some of the syntax omission such as top-level curlies etc https://www.lucidchart.com/techblog/2018/07/16/why-json-isnt-a-good-configuration-language/

[talentlessguy]

@talentlessguy Do you know of any JavaScript tooling that uses TOML? Previously Rome did actually use TOML but after reading https://hitchdev.com/strictyaml/why-not/toml/ and seeing it's extremely limited usage in the JavaScript community I pivoted. I know it sounds contradictory since RJSON is some unique-only-for-Rome JSON, but I would consider syntax omission to not be as big of a deal.

oh I see. As I understood Rome config will be very nested and big, so TOML won't work :/. So we have to use something json-like

[talentlessguy]

@stephenwf @sebmck

hm ok I see that json5 doesn't save comments. But why Rome should save comments in the configuration? Shouldn't they be erased after config consumption?

[sebmck]

Rome has the ability to modify the config and then save it. This allows us to have commands like rome config enable-category lint and have it load, modify, and save while retaining comments.

[MrHIDEn]

This article resonated strongly and motiviated some of the syntax omission such as top-level curlies etc https://www.lucidchart.com/techblog/2018/07/16/why-json-isnt-a-good-configuration-language/

In that article you mentioned there is HJSON format, very similar to yours RJSON. I agree with you with the idea of RJSON. I believe it is too late for that format but it is interesting thing.