Skip to content

Latest commit

 

History

History
657 lines (452 loc) · 28.2 KB

CONTRIBUTING.md

File metadata and controls

657 lines (452 loc) · 28.2 KB
Raw

Contributing

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.

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

✔️ Use the most recent JSON Schema version (specified by $schema) that's widely supported by editors and IDEs. Currently, the best supported version is draft-07. Later versions of JSON Schema are not recommended for use in SchemaStore until editor/IDE support improves for those versions.

✔️ Use base.json schema for draft-07 and base-04.json for draft-04 with some common types for all schemas.

There is an unofficial draft-07 schema that uses JSON Schema to validate your JSON Schema. It checks that:

  • type, title, description properties are required
  • There are no empty arrays. For instance, it's impossible to write less than 2 sub-schemas for allOf
  • type can't be an array, which is intentional, anyOf/oneOf should be used in this case
  • It links to understanding-json-schema for each hint/check

To check your schema against that schema, use node cli.js check-strict --schema-name=<schemaName.json>.

❌ Don't forget add test files.

  • Always be consistent across your schema: order properties and describe in the same style.
  • Always use description, type, additionalProperties.
    • Always set additionalProperties to false unless documentation permits additional properties explicitly. That tool the JSON schema is created for can be changed in the future to allow wrong extra properties.
  • Don't end title/description values with colon.
  • Always omit leading articles for title-s and trailing punctuation to make expected object values look more like types in programming languages. Also start title-s with a lowercase letter and try use nouns for titles instead of sentences.
  • Always add documentation url to descriptions when available in the following format: <description>\n<url> like "Whether to ignore a theme configuration for the current site\nhttps://jekyllrb.com/docs/configuration/options/#global-configuration".

Avoiding Overconstraint

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, do not add regex patterns for any of the following:

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

In addition, be wary when adding exhaustive support to enum-type fields. Often, when applications expand support (thus expanding the set of allowable enums), the schema will become invalid.

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, Editors and IDEs 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.

x-taplo

Used by: tamasfe/taplo.

x-taplo-info

Used by: tamasfe/taplo.

x-intellij-language-injection

Used by Intellij.

x-intellij-html-description

Used by Intellij.

x-intellij-enum-metadata

Used by Intellij. See Documenting Enums for details.

Using the CODEOWNERS file

This repository uses the the code-owner-self-merge GitHub action to give project maintainers more control over their schema. It allows for:

  • Mentioning a user when a schema is modified in a PR
  • Enabling a user to merge a PR, so long it only modifies files that is "owned" by that user

See the CODEOWNERS file, the action configuration, and action documentation for more information.

Schema Validation

After authoring a schema, you'll want to validate so it behaves as intended against popular validators.

This repository validations JSON Schemas in multiple ways:

Ajv strict mode

  • The default validation mode that is most stringent
  • Checks schema to prevent any unexpected behaviors or silently ignored mistakes
  • Fixing strict mode errors does not change validation results, it only serves to improve schema quality
  • More info at Ajv Strict mode docs

Ajv non-strict mode

  • Some rules are relaxed for the sake of brevity
  • To validate under non-strict mode, add your schema to the ajvNotStrictMode field in schema-validation.jsonc

SchemaSafe

  • Helps catch errors within schemas that would otherwise be missed. This is a WIP

To actually run the validation checks, see How to validate a JSON Schema.

About catalog.json

The catalog.json file is generally used by editors and extensions to determine which schemas apply to what files. Specifically:

Sometimes, catalog.json is interpreted differently:

And, generally, if a software supports multiple formats, stick with configuration file formats like JSON and avoid JavaScript. See this issue.

Compatible Language Servers and Tools

redhat-developer/yaml-language-server

tamasfe/taplo

Microsoft/vscode-json-languageservice

  • Used by VSCode
  • Used by Zed (see source)
  • Used by Emacs's LSP Mode (see docs)
  • More information here

Other

Troubleshooting

Some common errors include:

Dependency Errors

When updating the working tree, you may suddenly come across issues with dependencies like the following:

$ node ./cli.js
node:internal/modules/esm/resolve:838
  throw new ERR_MODULE_NOT_FOUND(packageName, fileURLToPath(base), null);
        ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'ajv' imported from .../schemastore/cli.js
    at packageResolve (node:internal/modules/esm/resolve:838:9)
    ...
    at ModuleJob._link (node:internal/modules/esm/module_job:132:49) {
  code: 'ERR_MODULE_NOT_FOUND'
}

Node.js v23.0.0

To fix dependencies it is recommended to run npm clean-install. The command npm install should work as well.

pre-commit fails to format files in CI

The pre-commit.ci action can "mysteriously" fail to automatically commit formatted files. This happens because the repository corresponding to the pull request branch is not owned by a user account. This constraint is detailed in GitHub's documentation.

To fix this, run the formatter manually:

npm run prettier:fix

Note this will also format the following files:

$ git status --short
M src/test/prettierrc/.prettierrc.yml
M src/test/prettierrc/prettierrc.json

Do not add those two files; pre-commit.ci seems to have issue with them. (Undo modifications to those files by running git restore -- 'src/test/prettierrc/*')

To run Prettier on scpecific files, run:

# Run on a schema file
./node_modules/.bin/prettier --config .prettierrc.cjs --ignore-path .gitignore --write src/schemas/json/<schemaName.json>
# Run on test files
./node_modules/.bin/prettier --config .prettierrc.cjs --ignore-path .gitignore --write src/test/<schemaName>/

How-to

How to add a JSON Schema that's hosted in this repository

Follow these instructions if you want to add the JSON schema file directly to this repository. If you want to keep the JSON schema hosted elsewhere, see How to add a JSON Schema that's self-hosted/remote/external.

When uploading a new schema file, make sure it targets a file that is commonly used or has potential for broad uptake.

First, clone the repository:

git clone https://github.com/SchemaStore/schemastore
cd schemastore

Be sure that NodeJS is installed. The minimum required NodeJS version is defined by the engines key in package.json. Now, install dependencies and run the new-schema task:

npm clean-install
node cli.js new-schema

You will be prompted for the name of the schema. Once you enter your schema name, the task will:

  • Create a new schema file at src/schemas/json/<schemaName>.json
  • Create a positive test file at src/test/<schemaName>/<schemaName>.json
  • Print a string for you to add to the Schema Catalog

If you do not wish to use the new-schema task, the manual steps are listed below 👇

Manual Steps

  1. Create a schema file in src/schemas/json/<name>.json:

    {
  "$id": "https://json.schemastore.org/<schemaName>.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": true,
  "properties": {},
  "type": "object"
}

  2. Add positive test files at src/test/<schemaName>/<testFile>: (optional, but strongly recommended)

    File extensions .json, .toml, .yml, and .yaml are supported.

  3. Add negative test files at src/negative_test/<schemaName>/<testFile> (optional)

  4. Register your schema (in alphabetical order) in the schema catalog:

    {
  "description": "Schema description",
  "fileMatch": ["list of well-known filenames matching schema"],
  "name": "Friendly schema name",
  "url": "https://json.schemastore.org/<schemaName>.json"
}

Finally, validate your changes. See How to Validate a JSON Schema for details.

How to add a JSON Schema that's self-hosted/remote/external

You may wish to serve a schema from https://json.schemastore.org/<schemaName>.json, but keep the content of the schema file at a place you control (not this repository).

See this PR as an example. Simply register your schema in the schema catalog, with the url field pointing to your schema file:

{
  "name": "hydra.yml",
  "description": "ORY Hydra configuration file",
  "fileMatch": [
    "hydra.json",
    "hydra.yml",
    "hydra.yaml",
    "hydra.toml"
  ],
  "url": "https://raw.githubusercontent.com/ory/hydra/master/.schema/version.schema.json"
},

How to edit an existing JSON Schema

First, clone the repository:

git clone https://github.com/SchemaStore/schemastore
cd schemastore

Be sure that NodeJS is installed. The minimum required NodeJS version is defined by the engines key in package.json.

Now, modify the schema you intend to modify. Schemas are located under src/schemas/json.

Finally, validate your changes. See How to Validate a JSON Schema for details.

How to add a JSON Schema with multiple versions

Refer to this agripparc PR as an example. First, your schema names should be suffixed with the version number.

  • src/schemas/json/agripparc-1.2.json
  • src/schemas/json/agripparc-1.3.json
  • src/schemas/json/agripparc-1.4.json

Then, use the versions field to list each of them. Add the latest version to the url field:

{
  "description": "JSON schema for the Agrippa config file",
  "fileMatch": [".agripparc.json", "agripparc.json"],
  "name": ".agripparc.json",
  "url": "https://json.schemastore.org/agripparc-1.4.json",
  "versions": {
    "1.2": "https://json.schemastore.org/agripparc-1.2.json",
    "1.3": "https://json.schemastore.org/agripparc-1.3.json",
    "1.4": "https://json.schemastore.org/agripparc-1.4.json"
  }
}

How to move a JSON Schema from SchemaStore to somewhere that's self-hosted

Simply changing the url field in the schema catalog (as described here) is not enough. You must also:

  • Keep the original schema files in the repository and point to your schema with $ref
  • Add an entry under skiptest so the remaining schema file isn't tested

See this PR for a full example.

How to add a $ref to a JSON Schema that's hosted in this repository

$ref from schema_x.json to schema_y.json

  • Both schemas must exist locally in SchemaStore.
  • Both schemas must have the same draft (ex. draft-07)
  • schema_y.json must have id or $id with this value "https://json.schemastore.org/schema_y.json"
  • In schema_x.json, add ref to schema_y.json: "$ref": "https://json.schemastore.org/schema_y.json#..."
  • Within schema-validation.jsonc, in "options": [], add an entry: { "schema_x.json": {"externalSchema": ["schema_y.json"] } }

How to add a $ref to a JSON Schema that's self-hosted

This currently isn't possible. This is tracked by issue #2731.

How to validate a JSON Schema

To validate all schemas, run:

node ./cli.js check

Because there are hundreds of schemas, you may only want to validate a single one to save time. To do this, run:

node ./cli.js check --schema-name=<schemaName.json>

For example, to validate the ava.json schema, run node ./cli.js check --schema-name=ava.json

Note that <schemaName.json> refers to the filename that the schema has under src/schemas/json.

How to ignore validation errors in a JSON Schema

Note Please only do this if you must. Validating in strict mode catches many common errors by schema authors and improves schema quality.

Sometimes, the build fails due to a failed validation check. See a list of validation checks here. An error may look like:

>> compile              | schemas/json/prefect-deploy.json (draft-07)(FullStrictMode)
>> Error: strict mode: use allowUnionTypes to allow union type keyword at "#/definitions/prefect_docker.deployments.steps.push_docker_image/properties/credentials" (strictTypes)

To ignore most validation errors, you need to modify ./src/schema-validation.jsonc:

  • If a strict error fails, you need to add your JSON Schema to the ajvNotStrictMode array
  • If you are getting "unknown format" or "unknown keyword" errors, you need to add your JSON Schema to the options object
  • If you are using a recent version of the JSON Schema specification, you will need to add your JSON Schema to the highSchemaVersion array

How to name schemas that are subschemas (partial-)

Often, it is useful to extract a subschema into its own file. This can make it easier to write tests, find schemas pertaining to a particular project, and logically separate extremely large schemas. The partial- prefix makes it easier for SchemaStore developers and subschema consumers to identify that the schema is a subschema.

A subschema should be extracted to its own file based on the following rules:

  • If a schema represents an existing project that could be its own file, then simply use that file for the "subschema". In other places, $ref that file where appropriate.
    • For example, mypy reads configuration from both mypy.ini and pyproject.toml's tool.mypy key. Because mypy.ini is its own file, then name the schema mypy.json like you usually would.
    • Same with Prettier. It reads from .prettierrc.json (among other files) and package.json's prettier key.
  • If the schema cannot be its own file, then extracting the subschema may be an improvement
    • For example, Poetry reads configuration only from pyproject.toml's tool.poetry key. Because the Poetry subschema is relatively complex and a large project, it has been extracted to its own file, partial-poetry.json.
  • If the schema must exist locally to workaround issue #2731, then the subschema should be extracted
    • In a top-level $comment, you must add the date at which you copied the original. See #3526 for an example

Use your best judgement; if the project or schema is small, then the drawbacks of extracting the subschema to its own file likely outweigh the benefits.

Older Links

use-of-codeowners-file

See Using the CODEOWNERS file.