> lacks comments [..] super super bad for configuration files

Not that that matters when applications take it upon themselves to re-save the config file in some kind of normalisation effort. Bye-bye comments, hope they're checked in somewhere.

I'm lookin' at you, kubernetes...

This hits home. Every time I've ever had to make the decision I've chosen yaml, for exactly this reason. Funny how the seemingly small things can be absolute show stoppers when it comes to making decisions in production.

JSON5 supports comments, and is only slightly more complex than JSON. https://json5.org/

The barrier here would be whether there's support in enough implementations to feel safe using it in the wild, which I'm guessing will take a while at the very least.

What’s incredible here is that we’re not at the beginning of programming, when we built temporary languages that ended up becoming forgotten. Web may be a final form of IT, Angular may be the « right », the final, the perfect way to build applications even in 50 years, just like HTML has become the final way to build websites for the last 25 years, JSON may make legacy, and my grandson might even struggle with parsers that still use JSON instead of this new tech called JSON5...

The popularity of transpilers might help overcome that barrier. IDE's and task runners can watch for file modifications and run a simple program to convert to the old format.

But I'm curious what you mean by "in the wild"? If you're using (producing) it, something needs to consume it, and you would probably have control over both in whatever project you were using it for.

If you're going to do this kind of thing why would you not add a standard date format

Just use a string and ISO 8601? “2018-03-25”

Wow, I can "just" use that, thanks. The problem is that JSON is an interchange format, meaning that I need to implement this serialization and deserialization quirk on every producer/consumer of my API (which, you know, avoiding is kind of the point of using a standard interchange format). Furthermore, because everything is a string, I can't unambiguously indicate something is meant to be a string in that format rather than a date.

What's the timezone?

Do you need a time zone for dates?

Consider if I'm storing a user's (local) birthday on my server:

    {..., "birthday": "2018-03-25"}

If my server is located in New York City, and the user is in Sydney, then my server isn't going to wish them happy birthday in time.

So maybe we could do:

    {..., "birthday": "2018-03-25", "location": "Sydney/AU"}

But at this point we might as well use a standardized time format (UTC) with a timezone offset. Maybe I'm thinking too far into it?

ISO 8601 has you covered:

   Year:
      YYYY (eg 1997)
   Year and month:
      YYYY-MM (eg 1997-07)
   Complete date:
      YYYY-MM-DD (eg 1997-07-16)
   Complete date plus hours and minutes:
      YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)
   Complete date plus hours, minutes and seconds:
      YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00)
   Complete date plus hours, minutes, seconds and a decimal fraction of a second
      YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)
  where:

     YYYY = four-digit year
     MM   = two-digit month (01=January, etc.)
     DD   = two-digit day of month (01 through 31)
     hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
     mm   = two digits of minute (00 through 59)
     ss   = two digits of second (00 through 59)
     s    = one or more digits representing a decimal fraction of a second
     TZD  = time zone designator (Z or +hh:mm or -hh:mm)

Most parsers will not support JSON5.

More like browsers can de-serialize JSON5 natively. writing a JSON5 parser is not difficult. It's just not part of most std libs in most languages, but I would argue that most std libs don't parse YAML either.

JSON5 is a good compromise.

Neither Chrome nor Firefox's JSON.parse accept JSON5. I'm not sure what browser API you mean.

For example,

  JSON.parse(`{"foo":"bar",}`)

throws a syntax error.

> Neither Chrome nor Firefox's JSON.parse accept JSON5. I'm not sure what browser API you mean.

This is a typo, I meant "can't" not "can". Off course browsers don't support JSON5 or my message makes no sense whatsoever.

The lack of template string support is a weird part of that.

In our JSON config files we do:

{ "ConfigKeyComment": "This is for blah blah blah", "ConfigKey": "Foo" }

Obviously this wouldn't work in all cases (you're putting more work on your parser to interpret unused keys basically), but if we're talking config files specifically, I see this as an acceptable approach since there's little chance you'll be parsing such files more than once each (plus, writing a simple tool to strip the comments out would be very trivial).

I've tried something similar but found it way too painful if the comments need to be long...

    # Never enable this config, because if you do the space-time
    # continuum will collapse into itself and the cloud servers
    # will disappear in a puff of steam. However, if you really
    # must enable it, remember that it's boolean and go read
    # TICKET-8675309 for the extensive list of side effects.
    TurboFactorRenoberation = false
    

...so people just end up writing stuff like:

    {
        "ConfigKeyComment": "TICKET-8675309",
        "ConfigKey": "TurboFactorRenoberation",
        "ConfigVal": false
    }

[edit]: formatting

That's not JSON anymore, that's pretty much enough to be considered a unique DSL. Scary that this is more or less required.

Almost all applications evolve their config files into unique DSLs over time. They may choose a generic serialization for the DSL's AST but it will end up being an underspecified application specific DSL regardless.

Interesting approach.

Maybe I'm lazy but avoiding increasing cost to commenting is one of the few absolutes I abide by. Often I find myself tired after a long stretch of code, trying to convince myself that's it's understandable on it's own.

This is one of those systematic rules I have to enforce to shutdown my lazy lizard brain.

edit: But I can see how highly structured comments could actually come in handy as well for viewing configs in a gui

>Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.

-Douglas Crockford, creator of JSON

There is no issue using JSON with comments for a config file.

Blurg, now every tooling pipeline that uses JSON needs to include a JSMin step...

If you're making comments for yourself in config files you control:

/\/\/.*/gm

https://regexr.com/3rbgb

"hello // syntax error"

You are 100% correct. For not single line comments, "//" in the datastructure, and everything else there are already well tested solutions for the problem. https://github.com/sindresorhus/strip-json-comments

My point is only that this isn't a big issue. I don't understand why so many see it as a large issue. Instead, projects use non-standard YAML or other problematic solutions only because "JSON doesn't have comments".

Yes, except for the fact that ECMAScript has a syntax for comments, but not JSON. Standards matter.

Or pipe through json5 which has other conveniences one might want like trailing commas.

I love json5, but it's not always an option.

Yes, but ITT we're talking about someone apparently having the option to pick which format they're using for config, and they'd use JSON if it wasn't for one dealbreaker.

JSON lacks comments (both line-level and block level)

    “_comment”: “blah blah blah”,

Simples

That doesn't work if you use a strict parser where superfluous fields are an error. It's quite rare, but there are good use cases for that kind of strictness.

Or when no fields are superfluous. For instance, when the code iterates over all the fields and does something with each, instead of just looking for known keys.

Or when the place you need to put the comment doesn't happen to be inside an object literal.

This is ugly.