4 ms·

It really needs comments. Unfortunately it'll never be backwards compatible. It's very helpful for debugging

by homero 4y ago

avmich 4y ago
To me, saying that JSON - not JSON Schema - needs comments is like saying an array - the good old "int[3] foo = { 5, 6, 7 };" - needs comments. I'm sure there are ways to 1) use it profitably without comments and 2) add comments in non-invasive way if really needed.
- wewtyflakes 4y ago
  Isn't that a great example of something that would benefit from comments; a generically named int array with no context? Regarding the ability to add comments to JSON, it can be done in a cumbersome manner, such as adding a field to an object called "comment", but it is a hack since this wont work for arrays anyway.
  - avmich 4y ago
    The point is that JSON is a data structure, comment is rather unnatural there. It can be added to JSON though, just like an array could be wrapped in an object with a "comment" field. Usually array name serves as a crude comment. Literate programming isn't very popular.
    - wewtyflakes 4y ago
      This does not help if you are integrating against someone else's API.
    - dragonwriter 4y ago
      > The point is that JSON is a data structure JSON is not a data structure. JSON is a data language. A computer program is a data structure and doesn't need comments, a programming language is a format for a human to read, write, and interact with automated tooling, whoss content is a program, but for the human uses, comments are important. Similarly for data languages.
jamesappledev 4y ago
We already use comments in JSON without JSONC in lots of projects. Adding a { "//": "My Comment" } line works and most API's ignore excess fields.
- Taywee 4y ago
  A good json schema validator will usually reject excess fields.
  - relequestual 4y ago
    Actually, currently, this is not the case. The specification explicitly allows for additional fields for the purposes of extensions. We are considering changing that, and only allowing pre-defined fields, or having a way to mark specific fields as limited extensions.
    - Taywee 4y ago
      Huh, you're right. There is additionalProperties, but I mistakenly thought `"additionalProperties": false` was the default.
      - relequestual 4y ago
        It is not =] Additionally, the value is a "schema" as opposed to a boolean, meaning you can apply a subschema to any additional fields. Useful if you for instance want to make sure any additional fields start with a specific prefix. Booleans are valid schemas. It's subschemas all the way down! I wrote an article around this topic: https://json-schema.org/blog/posts/applicability-json-schema-fundamentals-part-1 https://json-schema.org/blog/posts/applicability-json-schema...
user3939382 4y ago
I put my JSONSchema in .json5 files. I then convert the json5->json with a tool before it’s interpreted. One extra step, not a huge deal.
JoBrad 4y ago
I agree. Yes, you can support comments using a non-standard method, but the standard needs to include them.
AdieuToLogic 4y ago
> It really needs comments. Unfortunately it'll never be backwards compatible. It's very helpful for debugging If you want to have comments, consider using YAML for definitions where possible as it is a superset of JSON[0]: YAML is also a superset of JSON, so JSON files are valid in YAML. 0 - https://www.redhat.com/en/topics/automation/what-is-yaml https://www.redhat.com/en/topics/automation/what-is-yaml
- AdieuToLogic 4y ago
  Just for fun, I wondered if YAML '#' comments could exist within a multi-line formatted JSON file. I cannot say the below holds for all YAML libraries, but can say the below works. Assume there is a file named "foo.yaml" which has the following content: { # this is a comment "hello" : "world", array : [ # first number 1, # second number 2 ] } Running: ruby -ryaml -rjson -e 'puts JSON.pretty_generate(YAML.load(ARGF))' < foo.yaml Yields the below without error: { "hello": "world", "array": [ 1, 2 ] } HTH
  - verdverm 4y ago
    you can reduce further this by running: cue export foo.yaml --out json If you have an existing JSON file, add // comments wherever and run: cue export cue: - --out json < file.json The `cue: -` tells cue how to interpret stdin and has many options
magicalhippo 4y ago
It already has comments[1]? [1]: https://json-schema.org/understanding-json-schema/reference/generic.html#comments https://json-schema.org/understanding-json-schema/reference/...
- homero 4y ago
  I guess I mean like commenting out a whole line like in JavaScript
deleted 4y ago
[deleted]

It really needs comments. Unfortunately it'll never be backwards compatible. It's very helpful for debugging

by homero 4y ago

It really needs comments. Unfortunately it'll never be backwards compatible. It's very helpful for debugging

To me, saying that JSON - not JSON Schema - needs comments is like saying an array - the good old "int[3] foo = { 5, 6, 7 };" - needs comments. I'm sure there are ways to 1) use it profitably without comments and 2) add comments in non-invasive way if really needed.

wewtyflakes 4y ago
Isn't that a great example of something that would benefit from comments; a generically named int array with no context? Regarding the ability to add comments to JSON, it can be done in a cumbersome manner, such as adding a field to an object called "comment", but it is a hack since this wont work for arrays anyway.
- avmich 4y ago
  The point is that JSON is a data structure, comment is rather unnatural there. It can be added to JSON though, just like an array could be wrapped in an object with a "comment" field. Usually array name serves as a crude comment. Literate programming isn't very popular.
  - wewtyflakes 4y ago
    This does not help if you are integrating against someone else's API.
  - dragonwriter 4y ago
    > The point is that JSON is a data structure JSON is not a data structure. JSON is a data language. A computer program is a data structure and doesn't need comments, a programming language is a format for a human to read, write, and interact with automated tooling, whoss content is a program, but for the human uses, comments are important. Similarly for data languages.

jamesappledev 4y ago

We already use comments in JSON without JSONC in lots of projects. Adding a { "//": "My Comment" } line works and most API's ignore excess fields.

Taywee 4y ago
A good json schema validator will usually reject excess fields.
- relequestual 4y ago
  Actually, currently, this is not the case. The specification explicitly allows for additional fields for the purposes of extensions. We are considering changing that, and only allowing pre-defined fields, or having a way to mark specific fields as limited extensions.
  - Taywee 4y ago
    Huh, you're right. There is additionalProperties, but I mistakenly thought `"additionalProperties": false` was the default.
    - relequestual 4y ago
      It is not =] Additionally, the value is a "schema" as opposed to a boolean, meaning you can apply a subschema to any additional fields. Useful if you for instance want to make sure any additional fields start with a specific prefix. Booleans are valid schemas. It's subschemas all the way down! I wrote an article around this topic: https://json-schema.org/blog/posts/applicability-json-schema-fundamentals-part-1 https://json-schema.org/blog/posts/applicability-json-schema...

user3939382 4y ago

I put my JSONSchema in .json5 files. I then convert the json5->json with a tool before it’s interpreted. One extra step, not a huge deal.

JoBrad 4y ago

I agree. Yes, you can support comments using a non-standard method, but the standard needs to include them.

AdieuToLogic 4y ago

> It really needs comments. Unfortunately it'll never be backwards compatible. It's very helpful for debugging If you want to have comments, consider using YAML for definitions where possible as it is a superset of JSON[0]: YAML is also a superset of JSON, so JSON files are valid in YAML. 0 - https://www.redhat.com/en/topics/automation/what-is-yaml https://www.redhat.com/en/topics/automation/what-is-yaml

AdieuToLogic 4y ago
Just for fun, I wondered if YAML '#' comments could exist within a multi-line formatted JSON file. I cannot say the below holds for all YAML libraries, but can say the below works. Assume there is a file named "foo.yaml" which has the following content: { # this is a comment "hello" : "world", array : [ # first number 1, # second number 2 ] } Running: ruby -ryaml -rjson -e 'puts JSON.pretty_generate(YAML.load(ARGF))' < foo.yaml Yields the below without error: { "hello": "world", "array": [ 1, 2 ] } HTH
- verdverm 4y ago
  you can reduce further this by running: cue export foo.yaml --out json If you have an existing JSON file, add // comments wherever and run: cue export cue: - --out json < file.json The `cue: -` tells cue how to interpret stdin and has many options

magicalhippo 4y ago

It already has comments[1]? [1]: https://json-schema.org/understanding-json-schema/reference/generic.html#comments https://json-schema.org/understanding-json-schema/reference/...

homero 4y ago
I guess I mean like commenting out a whole line like in JavaScript

deleted 4y ago

[deleted]