Joshua's Docs - JSON Schema - Resources, Notes, and VSCode Tips

Ever wondered how VSCode provides auto-complete and intellisense for standard config files, like tsconfig.json, or if you have the right extensions installed, .eslintrc.json, .prettierrc, etc.? Welcome to the magical world of JSON Schema!

The TLDR of this is that JSON Schema is a standardized way to write (with JSON) a specification for how a certain JSON file type should always look. It is powerful in that it can be used for both autocomplete and intellisense (providing hints to the user on what certain fields are for), as well as validation.


JSON Schema in VSCode

JSON Schema Service in VSCode

For the implementation of JSON Schema, and other JSON language features in VSCode, there are a few important packages and areas of the codebase to be extra aware of:

JSON Schema Resolver in VSCode

There are multiple ways in which VSCode resolves which Schema to apply against an open JSON file - the main docs covering this are here. To summarize though, the main options are:

  • In the file itself, via the $schema attribute (path)
  • In VSCode settings.json, under json.schemas:
    • json.schemas: Array<{ fileMatch: Array<fileGlobs>, url: schemaPath }>
  • Through a VSCode extension, by contributing through jsonValidation:
    • jsonValidation: Array<{ fileMatch: fileGlob, url: schemaPath }>
    • This is how bundled language extensions that come with VSCode, like configuration-editing, internally contribute schema resolvers (example)

Note: For the $schema or url value, the path to the schema file does not have to be local; many extensions and plugins use a public URL, such as It can also point to special internal paths, like in VSCode, with vscode://schemas/...

Here are some practical examples:

  • Here is how the vscode-eslint extension contributes schemas
    • This is why .eslintrc has intellisense if the extension is installed
    • Here is the schema that gets merged with NPM for package.json - specifically for the eslintConfig key
  • Here is a similar contribution from prettier-vscode

🚨 Certain schemas might disallow additionalProperties on either the root or nested objects, which means you cannot add arbitrary key-value pairs that are not strictly part of the schema. This also might mean that you get an error when trying to add $schema itself, if that is not part of the given schema.

VSCode - Show JSON Schema Being Used for Open File

Sometimes VSCode will provide Intellisense / schema validation for an open JSON file, but you aren't sure where that schema is actually coming from. In those cases, you might be wondering if there is a way to do a reverse lookup - have VSCode tell you the schema being used for validation.

Unfortunately, there is not a handy "Go to schema" command (I wish!), but there is still some ways you can find out.

The hard way is to built VSCode from source, and debug the JSON language service. There is a quick overview of this approach here, but it's quite a bit of work if you just need to find the schema being used for a single file.

A quicker approach is to turn on verbose message logging of that aforementioned JSON language service. You can do this by adding "json.trace.server": "verbose" to your setting.json file. Once you have done this, try editing the JSON file you want to debug schema for, and then bring up the Output panel in VSCode, and select JSON Language Server in the filter dropdown.

VSCode - Ignore JSON Schema Issue

If you want to ignore a specific JSON schema error (as in a VSCode IDE problem reported), for example if the schema is not expecting the use of $schema, that is unfortunately not really possible (AFAIK). However, in many cases the actual code that is consuming the JSON file might be rather lax with input, and might not care.

Markdown Source Last Updated:
Sun Jan 02 2022 05:44:41 GMT+0000 (Coordinated Universal Time)
Markdown Source Created:
Wed Jul 07 2021 09:06:35 GMT+0000 (Coordinated Universal Time)
© 2022 Joshua Tzucker, Built with Gatsby