search

json5 / json5-spec

The JSON5 Data Interchange Format
https://spec.json5.org
MIT License
49 stars 11 forks source link

Example in spec mentions backward compatibility with JSON #55

Closed jamesblacklock closed 4 months ago

jamesblacklock commented 4 months ago

The documentation says here that JSON5 is "backwards compatible" with JSON. This is not correct. JSON5 is forward compatible with JSON.

If JSON5 were backwards compatible with JSON, that would mean, "any valid JSON5 is valid JSON," which is clearly not the case.

However, JSON5 is forward compatible with JSON—in other words, "any valid JSON is valid JSON5."

jordanbtucker commented 4 months ago

Thanks for the suggestion. I think you have your definitions of backward and forward compatibility reversed.

Backward compatibility (sometimes known as backwards compatibility) is a property of an operating system, software, real-world product, or technology that allows for interoperability with an older legacy system, or with input designed for such a system, especially in telecommunications and computing. https://en.wikipedia.org/wiki/Backward_compatibility

backward compatible compatible with older equipment or previous versions of software https://www.merriam-webster.com/dictionary/backward%20compatible

Since JSON5 is the newer standard and adds more features on top of JSON, JSON5 is backward compatible with JSON in its syntax (every JSON document is a valid JSON5 document).

jamesblacklock commented 4 months ago

JSON5 is not "compatible with older equipment or previous versions of software." It will not parse when using old software. I think my usage is correct. But if you still disagree I will let it go :)

jamesblacklock commented 4 months ago

Aha, so I see now why we are seeing it differently.

The JSON5 format is not backwards compatible. However, the JSON5 parser is backwards compatible.

I understood the documentation to be talking about the format.

jordanbtucker commented 4 months ago

Yeah, I understand how the term backward compatible can be a bit ambiguous here. This non-normative example is taken from the reference implementation project, whose API is backward compatible with the JSON API. The normative sections of the spec do not use the term backward compatible but instead use superset.

I think it would be good to change the example to say "superset": "of JSON".

aseemk commented 4 months ago

Good discussion! =)

I think you may be technically right @jamesblacklock, but I'll say that I think it's helpful to put most people's minds at ease to clearly say that JSON5 is "backwards compatible" with JSON.