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.

Resources

• Main website: json-schema.org
  • Implementations / Tools
• Public repository of schemas - schemastore.org
  • Github repo: schemastore/schemastore
• Online Tools:
  • JSON Schema Validator
  • JSON Schema Editor
  • QuickType (can convert from JSON Schema to actual implementation code)
• Great intros:
  • Meuleman: JSON-schemas are awesome
  • json-schema.org: Getting Started: Step-by-Step
    • Very simple example schema: address.schema.json

JSON Schema Syntax and Tips

Defaults Worth Noting

• By default, objects / interfaces accept additional properties (in TypeScript, this would be saying it has an index signature of [key: string]: unknown in addition to the explicit keys)
  • To override, use "additionalProperties": false on object definitions
• By default, all key-value pairs of an object / interfaces are marked optional
  • To override, provide a "required": ["my_key_a", "my_key_b"] to your object definition
    • Unfortunately, there is not a native way in the spec to mark all keys as required (e.g., no "allRequired": true). The only native workaround is to use "minProperties": your_number_of_properties.

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:

• The built-in json-language-features extension
• The vscode-json-languageservice package, which is used internally by json-language-features

JSON Schema Resolver in VSCode

There are multiple ways in which VSCode resolves which Schema to apply against an open 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 http://json.schemastore.org/eslintrc. 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.

Figuring out which JSON schema VSCode is validating against used to be a pain, but in the November 2021 release of VSCode, they made this much easier. They added something called JSON language indicator, which is an indicator / button in the bottom status bar - it shows you the current schema being used, and if you hover over it, even provides a link to open the exact schema definition files being used for validation.

💡 If you want the full schema name to always be displayed in the status bar, you need to pin it. Hover over the indicator, then click the pin button.

Some older (and much harder) approaches can still serve some purpose, if you are looking for lower-level info.

One 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.

Another 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.

However, if you want to simply disable schema checking for an entire file, you can do so by overriding the schema resolution mapping via a custom setting:

{
	"yaml.schemas": {
		// This will cause a look up error, but also works as a way of blocking resolution
		"": [
			"my_dir/export/data.yml",
			"my_dir/import/*"
		]
		// Another option is to define and map your own schema
	}
}