Contributing

Introduction
Overview
Recommended Extensions
Schema Authoring
Schema Validation
About catalog.json
- Avoiding Generic fileMatch patterns
Compatible Language Servers and Tools
Troubleshooting
- Dependency Errors
- pre-commit fails to format files in CI
How-to
Older Links
- use-of-codeowners-file

Introduction

Welcome! Thank you for contributing to SchemaStore!

There are various ways you can contribute:

Add a new JSON Schema
- Local schema
- Remote schema
Enhance existing JSON schemas:
- Fix typos
- Fix bugs
- Improve constraints
- Add positive/negative tests
- Refactor to pass under strict mode

Most people want to add a new schema. For steps on how to do this, read the How to add a JSON Schema that's hosted in this repository section below. Find instructions for other tasks under the How To section.

If you want to contribute, but not sure what needs fixing, see the help wanted and good first issue labels on GitHub.

Overview

Schema files are located in src/schemas/json. Each schema file has a corresponding entry in the Schema Catalog. Each catalog entry has a fileMatch field. IDEs and language servers use this field to know which files the schema should be used for (in autocompletion).

Some schema files have associated positive and negative tests, located at src/test and src/negative_test, respectively. These tests may be in JSON, YAML, or TOML format.

Multiple libraries are used for validation to increase the compatibility and correctness of schemas. All schemas must correctly validate against their positive and negative tests using Ajv. Other JSON Schema libraries can be optionally used. And, the schemas themselves can be linted using "Ajv strict mode" and other libraries. More details under Schema Validation.

Recommended Extensions

We highly recommend installing the following extensions for your IDE:

EditorConfig to automatically configure editor settings
Prettier to automatically configure file formatting

If you are modifying cli.js, we also recommend:

ESLint to automatically show JavaScript issues
TypeScript language server (Bundled with VSCode)

Schema Authoring

The goal of JSON Schemas in this repository is to correctly validate schemas that are used by the actual tools. That means, if a property is undocumented or deprecated, it should still be included in the schema.

Best practices

We recommend using the draft-07 JSON schema version. Later versions of JSON Schema are not yet recommended for use in SchemaStore until IDE and language support improves for those versions.

❌ Don't forget add test files.

Useful Conventions

Consider using documentation URLs in "description" to improve UX. Most schemas use the format <description>\n<url>. For example: "Whether to ignore a theme configuration for the current site\nhttps://jekyllrb.com/docs/configuration/options/#global-configuration"
When writing description, avoid phrases like "there are three possibilities" and "valid values are" in favor of adding the constraints to the schema directly.
If you choose to use title, we recommend formatting it so that object values look like types in programming languages. This includes:
- Omitting leading articles and trailing punctuation
- Beginning it with a lowercase letter
- Using nouns instead of sentences

Avoiding Overconstraint

Complexity

Sometimes, constraints do more harm than good. For example, cron strings validation regexes. In general, do not add a constraint if:

false positives are likely (due to their complexity or abundance of implementations)
its error message is too confusing or not helpful

So, we recommend avoiding regex patterns for:

cron regexes
string-embedded DSLs
SSH URLs, HTTPS URLs, and other complex URIs

Enums

Be wary when adding exhaustive support to enum-type fields (without a "type": "string" fallback). Keep in mind:

New enum values that are supported by a new tool version (and not yet added to SchemaStore) should not error
The schema may be extended by a tool that you have no knowledge of

Properties

Do not blindly add "additionalProperties": false. Keep in mind that:

New properties that are supported by a new tool version (and not yet added to SchemaStore) should not error
The schema may be extended by a tool that you have no knowledge of

It is recognized that stricter checking may be desired, as in the case of checking for typos. In that case, check to see if your validator has an option for stronger checks. For example, Tombi enables a strict mode by default.

Undocumented Features

The use of undocumented features in schemas is permitted and encouraged. However they must be labeled as such.

It is preferred to add UNDOCUMENTED. to the beginning of description.

{
  "type": "object",
  "properties": {
    "experimental_useBranchPrediction": {
      "type": "string",
      "description": "UNDOCUMENTED. Enables branch prediction in the build."
    }
  }
}

However, that is not always possible or correct. Alternatively, use $comment:

{
  "type": "object",
  "tsBuildInfoFile": {
    "$comment": "The value of 'null' is UNDOCUMENTED.",
    "description": "Specify the folder for .tsbuildinfo incremental compilation files.",
    "default": ".tsbuildinfo",
    "type": ["string", "null"]
  }
}

In this case, { "tsBuildInfoFile": null } is not documented. Using a string value is, however.

Deprecated Features

Software that reads a schema may deprecate and eventually remove particular properties or features.

For most schemas, we don't recommend removing properties from schemas, especially immediately after they are no longer supported. They are useful during the migration process or if users are stuck on an older version.

To note that a property or feature is deprecated, use the same strategy as described in Undocumented Features. For example:

{
  "description": "DEPRECATED. Documentation of this property. Migrate to this alternative."
}

Note that JSON Schema draft 2019-09 adds support for a deprecated field:

{
  "description": "Documentation of this property. Migrate to this alternative.",
  "deprecated": true
}

While this would be the best option, most schemas in this repository are draft-07. As a result, IDEs and language servers may not use it.

API Compatibility

Care must be taken to reduce breaking changes; some include:

1. Preserving schema names

When renaming a schema name, the old version must continue to exist. Otherwise, all references to it will break. The content of the old schema must look something like:

{
  "$ref": "https://json.schemastore.org/NEWNAME.json"
}

The process of renaming schemas is similar to this section.

2. Preserving schema paths

Many tools, such as validate-pyproject, accept passing in subpaths for validation like so:

validate-pyproject --tool cibuildwheel=https://json.schemastore.org/cibuildwheel.toml#/properties/tool/properties

This means that renames in subschema paths is a potentially a breaking change. However, it needs to be possible to refactor internal schema structures.

It is okay when refactoring the subschema to a location under $defs or definitions. Otherwise, use your best judgement. If a rename is necessary, it is recommended to keep the old path and $ref to the new location, if possible.

Documenting Enums

There are several ways to document enums. It is recommended to use this solution:

{
  "oneOf": [
    { "const": "foo", "description": "Description foo" },
    { "const": "bar", "description": "Description bar" }
  ]
}

It is also possible to use x-intellij-enum-metadata:

{
  "enum": ["foo", "bar"],
  "x-intellij-enum-metadata": {
    "foo": {
      "description": "Description foo"
    },
    "bar": {
      "description": "Description bar"
    }
  }
}

Or, enumDescriptions:

{
  "enum": ["foo", "bar"]
  "enumDescriptions": [
    "Description foo",
    "Description bar"
  ]
}

The latter two approaches are not recommended because they use editor-specific, non-standard properties. See Non-standard Properties for details.

Language Server Features

There are several language servers that use SchemaStore:

Non-standard Properties

Some language servers support non-standard properties. They include:

allowTrailingCommas

Used by: vscode-json-languageservice.

Whether trailing commas are allowed in the schema itself. Use the allowTrailingCommas field. See this PR if you wish to add this for your schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "allowTrailingCommas": true,
  ...
}

defaultSnippets

Used by: vscode-json-languageservice.

markdownDescription

Used by: vscode-json-languageservice.

enumDescriptions

Used by: vscode-json-languageservice. See Documenting Enums for details.

markdownEnumDescriptions

Used by: vscode-json-languageservice. See Documenting Enums for details.

x-taplo

Used by: tamasfe/taplo.

x-taplo-info

Used by: tamasfe/taplo.

x-tombi-toml-version