microsoft/vscode

Documentation for JSON Schema support needs updating

gregsdennis opened this issue · 1 comments

gregsdennis commented

This isn't a feature request but an issue with your documentation. This template seemed to work best for that.

The documentation for JSON Schema support has a couple problems.

Meta-schema URI

In an example, it lists http://json-schema.org/schema a value to use for $schema, but this is not a valid meta-schema URI. We used to host the latest there, but that practice was stopped quite a while ago.

Furthermore, $schema holds a basic URI, not a URL. It's not intended for implementations to fetch a meta-schema from the value provided in $schema. http://json-schema.org/schema should not resolve to a meta-schema.

Instead, one of the versioned URIs below (the exact string) needs to be used:

  • http://json-schema.org/draft-06/schema#
  • http://json-schema.org/draft-07/schema#
  • https://json-schema.org/draft/2019-09/schema
  • https://json-schema.org/draft/2020-12/schema

Draft Support

The documentation says that it supports draft 4 through draft 2020-12. As there are features in 2019-09 and 2020-12 that are not supported, notably unevaluated* and $dynamic*, this statement is misleading.

It would be more correct to state that draft 4 through draft 7 are supported with limited support for drafts 2019-09 and 2020-12.

Also, it would be good to indicate which features in the later drafts are not supported.

We get numerous questions about VSCode support for JSON Schema, and it would be great to have accurate documentation that we can point them to.

aeschli commented

Thanks, I made the suggested changes: microsoft/vscode-docs@0627e8f

  • 👍1
  • 🎉3