Ensure schema JSON documents are valid JSON

[mike-north]

Currently, the presence of comments

https://github.com/Microsoft/web-build-tools/blob/138e943e283e4a5a271094389a89bce80861b676/apps/api-extractor/src/api/api-json.schema.json#L5-L12

and at least one trailing comma

https://github.com/Microsoft/web-build-tools/blob/138e943e283e4a5a271094389a89bce80861b676/apps/api-extractor/src/api/api-json.schema.json#L662-L665

makes these files way more difficult to work with than ideal (i.e., consumers cannot use JSON.parse)

Comments are easy to deal with thanks to strip-json-comments, but the trailing comma is a bit more annoying.

Suggestion

In CI, strip comments and run schema JSON documents through a json validator of some sort

Version

    "@microsoft/api-extractor": "^6.3.0",

[octogonz]

You are right: Technically the JSON Schema specification defines a $comment field presumably because their dialect of JSON does not support JavaScript comments:

https://json-schema.org/latest/json-schema-core.html#rfc.section.9

However, I have yet to see an editor or tool that doesn't support this simple extension to the JSON language. I'm curious -- which specific software are you using that had trouble loading our schemas?

(i.e., consumers cannot use JSON.parse)

(In particular, we never use JSON.parse() in any of our tooling, because it's missing a ton of features -- for example, schema validation. :-) )

[mike-north]

In tooling that I'm building, I'm looking to consume parts of the api-extractor schema (as a JSON document) in order to ensure my schema is a mechanical transform away from what api-extractor emits.

This is only important in the context of acceptance testing my own tool

[octogonz]

Our JsonFile API internally uses jju for parsing JSON. It's a really good JSON parser. (By comparison JSON.parse has the major downside of not providing line number information in its error messages, as well as no support for comments, which are a critical requirement for any nontrivial JSON config file.) The jju library also has a cool feature where it can save modifications to a commented JSON file without disturbing the original spacing/indentation.

We've been using z-schema for validating schemas, although ajv has been rapidly evolving, so we're considering switching to that. For some strange reason, the schema validators always report errors as JSON paths without line numbers.

[octogonz]

PR #3560 introduces an API that can fix this problem

[elliot-nelson]

Closing for now, as we won't be requiring "valid" JSON (i.e. parseable with JSON.parse, anyway). For tools that want to read Rush config files or schemas without using a Rush API, a parser like jju is the best bet.