[settings] Use JSON5 instead of JSONC for configuration files

[mischkl]

Currently configuration files are in JSONC format, which is a format without a specification, loosely standing for "JSON with comments". The VSCode version of it happens to allow trailing commas in arrays and objects, but this is a VSCode-specific implementation detail meant to make editing its own config files easier, rather than anything that is based on a specification. As such, VSCode config files are incompatible with other tools and tooling (and the fact that the file extension continues to be ".json" only exacerbates the problem).

I propose to use JSON5 instead of the more-or-less proprietary variant of JSONC (with .json extension, with trailing commas) that is currently in use in VSCode config files. JSON5 is a well-defined specification that includes comments, trailing commas, multi-line strings, single or double quotes, object keys without quotes and a couple other things borrowed from ECMAScript 5.1. It's still a strict subset of JavaScript and as such immediately understandable and usable for the vast majority of developers - in fact it could be argued that it's easier to understand than JSON, because it gets rid of some of the arbitrary and at times unexpected limitations that JSON imposes.

The most important thing, though, IMHO, is that Microsoft doesn't just forge its own path with proprietary implementations/extensions of JSON, creating essentially an "MS-JSON" variant, and instead embraces a cross-vendor, implementation-independent specification.

See also the discussion at microsoft/terminal#4232

[NotWearingPants]

Maybe while we're at it add support for YAML as well? (or strict-yaml)

[ntindle]

I agree that It needs changed but not to another JSON format. If it must be a JSON format, I do support JSON5 as the format over MSFT making their own.

[mischkl]

If you support this issue please give a thumbs up to the description! It needs 20 upvotes by August 20 in order to be added to the backlog!

[brentonhouse]

Microsoft has provided much more robust tooling for dealing with JSONC than anything provided for the struggling JSON5 community. If Microsoft wants to help the community, please don’t stop them!

Just try to do some roundtrip work with the partially abandoned JSON5 project and you will quickly find out there is absolutely no support for it.

[mischkl]

@brentonhouse helping "the community" (there's a JSONC community?) with tooling that only they themselves use?

If they had invested a similar amount of effort into moving JSON5 forward we wouldn't be having this discussion.

[brentonhouse]

@mischkl - nope. It’s open-source and available for anyone to use. I use it in a lot of different projects and I would have never had the time to design, build, and test such an extensive library myself.

[mischkl]

@brentonhouse what library are you referring to?

[brentonhouse]

https://github.com/microsoft/node-jsonc-parser

[mischkl]

Ah, right. Now I recall seeing that, and it does indeed look useful. However I don't see any reason they couldn't extend that existing code with JSON5 capabilities.

My issue is not with the code they've written but rather with the fact that anyone outside of the Node ecosystem, or indeed anyone seeking an alternative to that exact library, is sore out of luck in terms of compatibility because there is no standard. It's already begun with MS submitting a patch to the jsoncpp library just to allow trailing commas in its Terminal config files - which of course is again limited to just one library that MS puts its weight behind, as opposed to anything standardized.

[brentonhouse]

@mischkl - I actually used the JSON5 project early on in some of my projects but quickly found out that it is basically a personal project that wasn't updated much. Also, unless I am missing something, I see no way of actually updating JSON5 files using their library. There was one ticket that was closed back in 2016 but it doesn't look like that feature was ever implemented. json5/json5#121. Without that, it is just a fancy way of reading JSON with comments and has little real-world practical value. If VS Code relied on using JSON5, how would the settings file get updated if you changed a setting using the GUI?

[mischkl]

@brentonhouse to be clear, I am rallying for Microsoft to adopt JSON5 as a format, not for them to limit themselves to the reference implementation. Just like for advanced use cases hardly anyone would rely solely on Douglas Crockford's reference implementation of the JSON2 library.

They could for instance extend/fork the existing node-jsonc-parser library (seeing as JSON5 is essentially a better-defined superset of JSONC) and keep all existing format-roundtripping features.

[Lemmingh]

I support @mischkl.

There is no standard of JSONC, just conventions. However, JSON5 is a format with spec.

With a clear standard, we can absolutely throw away the reference implementation, and do everything with confidence. But without it, to reduce inconsistencies between implementations, we have to check what others are doing quite often.

I've seen at least 5 projects struggling with it. Even VS Code itself has to keep a lot of lists to distinguish JSONC:

vscode/extensions/json/package.json

Lines 45 to 61 in 4c99db1

	{
	"id": "jsonc",
	"aliases": [
	"JSON with Comments"
	],
	"extensions": [
	".jsonc",
	".eslintrc",
	".eslintrc.json",
	".jsfmtrc",
	".jshintrc",
	".swcrc",
	".hintrc",
	".babelrc"
	],
	"configuration": "./language-configuration.json"
	}

vscode/extensions/configuration-editing/package.json

Lines 27 to 45 in 23c359d

	{
	"id": "jsonc",
	"extensions": [
	".code-workspace",
	"language-configuration.json",
	"icon-theme.json",
	"color-theme.json",
	".code-snippets"
	],
	"filenames": [
	"settings.json",
	"launch.json",
	"tasks.json",
	"keybindings.json",
	"extensions.json",
	"argv.json",
	"profiles.json"
	]
	}

vscode/extensions/typescript-basics/package.json

Lines 40 to 52 in f564bbd

	{
	"id": "jsonc",
	"filenames": [
	"tsconfig.json",
	"jsconfig.json"
	],
	"filenamePatterns": [
	"tsconfig.*.json",
	"jsconfig.*.json",
	"tsconfig-*.json",
	"jsconfig-*.json"
	]
	}

Besides, in history, "no standard" almost killed a number of languages.

[aeschli]

We have currently no plans to change the format of the settings files.

[ssbarnea]

What I find really annoying about this subject is not the use of jsonc but is the incorrect use of .json extension for a file that in fact is .jsonc, which is incompatible with JSON.

[thw0rted]

.jsonc isn't actually a thing -- read upthread a bit, "JSON with comments" isn't a standard, there is no spec, there is no requirement that it use one particular file extension, and in fact there are a bunch of arguments over what file extension it should use. That's why this issue exists: instead of rolling their own poorly-described variant of a standard, the community would like Microsoft to switch to a well-defined standard (including a standard file extension!) that includes the capabilities they want.

[kaiba42]

I know this is closed, but there must be some plan to move away from abusing the .json extension for these settings files right?

[cwtuan]

Currently, configuration files in VSCode are in JSONC format, which is a proprietary variant of "JSON with comments". This format lacks a specification and is incompatible with other tools and tooling. The fact that the file extension is still ".json" exacerbates the problem.

JSON5 is a well-defined specification that includes comments, trailing commas, multi-line strings, single or double quotes, object keys without quotes, and other features borrowed from ECMAScript 5.1. It is a strict subset of JavaScript and is immediately understandable.

Switching to JSON5 would prevent Microsoft from creating its own "MS-JSON" variant and would embrace a cross-vendor, implementation-independent specification. JSONC is not a standard, and the lack of a spec results in multiple arguments over what file extension it should use.

Let's move away from a proprietary format and switch to a well-defined standard that includes the capabilities we need.

NPM Donwloads Comparsion: json5, jsonc-parser, bson, and hjson

[allan-bonadio]

Microsoft has provided much more robust tooling for dealing with JSONC than anything provided for the struggling JSON5 community. If Microsoft wants to help the community, please don’t stop them!

Just try to do some roundtrip work with the partially abandoned JSON5 project and you will quickly find out there is absolutely no support for it.

70 million downloads a week is hardly 'abandoned' or 'struggling'.
https://npmtrends.com/bson-vs-json5-vs-jsonc-vs-jsonc-parser

Unlike yaml or hjson, it's a subset of JS, so you can set your editor to use JS syntax. Or, copy/paste it into JS code. So if you don't see json5 as an option for your editor, or whatever, this could be why.

The json5 spec hasn't changed in 5 years - that means it's a stable standard, not 'abandoned'. The json5 NPM package was last updated 6 mo ago. There's json5 packages also in Java, Python, Golang, PHP, perl5, C++, C#, Ruby, ...

[jessestricker]

Even on GitHub, a product owned by Microsoft, the highlighting of .vscode/settings.json files containing comments is wrong, because GitHub thinks they are standard JSON files. All comments are marked as errors with screaming red backgrounds.

This could be avoided by either using the correct file extension .jsonc or a properly standardized file format.

[DamianSuess]

If this is to remain closed, is there at least a trustworthy alternative extension?

[markonop93]

🤡 :) ⊞ :) 🤡

[jmjoy]

I think this issue can be reopened.
Regardless of whether to use json5 or standardize jsonc, I think it is a good idea.

[thw0rted]

This is a for-profit company, not a democracy. The community asked them to please switch from a custom parser to a standardized one, and they declined. I'm not happy about it but have no reason to expect them to change their minds or re-open the issue.

[HaydenReeve]

The fact that JSON5 isn't supported is kind of crazy. Gives competitors like Jetbrains a big advantage who do offer that ability. 🙁

Really sad to see that the issue is closed too, and doesn't look like it's being considered for future development.

[mohkale]

I know this issue isn't getting resolved, just thought it's worth reiterating if microsoft has no intention of using a standard extension to communicate when one of its configuration files is not parseable by a standard json parser they could at least document which files have this breaking behaviour. As it stands I have to keep googling to find out. This seemed like an authoritative source but seems like but doesn't seem like .vscode/tasks.json is listed there but it definitely allows comments.

[Malix-Labs]

This issue should be either closed as unplanned or reopened

[aeschli]

The issue is already closed as unplanned (out-of-scope)

[stamminator]

Why doesn't Microsoft just establish an official open-source spec for JSONC? This solution has a lot going for it.

• It wouldn't require VS Code to change its implementation.
• It would implement the most useful and asked-for features (comments and trailing commas) while setting aside the more controversial and complex features from JSON5.
• It's low enough in complexity that Microsoft's .NET implementations could choose one of two paths with neither of them being bad (up for debate):
  • Extend System.Text.Json and Microsoft.Extensions.Configuration.Json so that JSONC features are non-breaking and opt-in.
    Or...
  • Ship independent System.Text.Jsonc and Microsoft.Extensions.Configuration.Jsonc packages which are slim and depend on their respective "parent" implementations.
• Existing implementations of JSON5 would be fully compatible with JSONC on a read-only basis, so at least some cross-platform functionality would be supported on day one.

[jmjoy]

Why doesn't Microsoft just establish an official open-source spec for JSONC? This solution has a lot going for it.

I also agree with the standardization of JSONC.

Another very important role of standardizing JSONC is to allow other languages ​​to benefit from it.

One reason why other languages ​​refuse to implement JSONC serializers is because JSONC is not standardized.

Some package managers that use json for configuration can also benefit from this, such as composer.json and package.json. These configuration files currently cannot make comments and trailing commas.

[Malix-Labs]

I would prefer a proper JSON5 implementation than a standardization of JSONC if you ask me

[stamminator]

I would prefer a proper JSON5 implementation than a standardization of JSONC if you ask me

I respect your viewpoint, but I don't think there's much value in rehashing the ask for JSON5 at this point. The primary complaint against JSON5 is that it's too complex, and minds are unlikely to change on that matter.

What's actually being asked for the vast majority of the time? Comments and trailing commas. The JSON5 features beyond those two are nice, but offer diminishing returns on productivity while ratcheting up the complexity. Simply put, comments and trailing commas offer the maximum "bang for the buck" in terms of value vs complexity. That's exactly what JSONC offers. It just needs to be codified.