Skip to content

Latest commit

 

History

History
105 lines (70 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

105 lines (70 loc) · 5.43 KB
Raw

JSON Schema

You can contribute in a variety of ways. For a detailed tutorial, read Scott Addie's Community-Driven JSON Schemas in Visual Studio 2015 blog post.

  1. Submit new JSON schema files
  2. Add a JSON schema file to the catalog
  3. Modify/update existing schema files

Versioning of schema files are handled by modifying the file name to include the version number: myschema-1.2.json

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

Keep single source of truth. Do not copy an external schema here, but point the catalog to the external schema.

If you don't have Visual Studio (using macOS or Linux?), you can check your modifications are fine by running:

make

Adding to catalog

After adding a schema file in src/schemas, register them in alphabetical order in the schema catalog by adding an entry corresponding to your schema:

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

Best practices

✔️ Use the lowest possible schema draft needed, preferably Draft v4, to ensure interoperability with as many supported editors, IDEs and parsers as possible.

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

❌ Don't forget add test files.

  • Be consistent across your schema: order properties and describe in the one style.
  • Use $comment to note about something to developers. You can refer to some issues here.
  • Use title when documentation mentions title explicitly.
  • Always use description, type, additionalProperties.
    • Always set additionalProperties to false until documentation permits additional properties explicitly. that tool the JSON schema is created for can be changed in the future to allow wrong extra properties.
  • Use minLength/maxLength/pattern/etc for property values.
  • Don't end title/description values with colon.

Adding tests (for local schemas only)

To make sure that files are validated against your schema correctly (we strongly suggest adding at least one before creating a pull request):

  1. Create a subfolder in src/test named as your schema file
  2. Create one or more .json, .yml, .yaml or toml files in that folder

Adding negative tests

To make sure that invalid files fail to validate against your schema, use a subfolder in src/negative_test/ instead.

Run build locally

  • Install NodeJS (The minimum required NodeJS version "engines" is defined in package.json)
  • in subdirectory src/ run npm run build (to test a single schema, use npm run build -- --SchemaName=<jsonFileName.json> default)
  • or optionally for macOS or Linux in the project root directory run make

If the build succeeds, your changes are valid and you can safely create a PR.

Self-hosting schemas

If you wish to retain full control over your schema definition, simply register it in the schema catalog by providing a url pointing to the self-hosted schema file to the entry. Example on how to handle multiple schema versions.

How to $ref from schema_x.json to schema_y.json

  • Both schemas must exist locally in SchemaStore.
  • Both schemas must have the same draft (example draft-04)
  • 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#..."
  • In schema-validation.json, in "options": [] list add "schema_x.json": {"externalSchema": ["schema_y.json"]}

JSON formatter

This project contains an .editorconfig file. If your IDE or code editor doesn't natively support it, please install the EditorConfig plugin.

Validation mode

SchemaStore supports three types of schema validation mode.

Avoid common PR problems

  • git merge conflict in catalog.json because you added the item to the end of the list instead of alphabetically.
  • Prettier build server failed because the PR was created/push from an organization and not from your own account.