Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve contributing experience #3120

Merged
merged 3 commits into from
Aug 9, 2023
Merged

Improve contributing experience #3120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
86f0276
Improve contributing experience
hyperupcall Aug 6, 2023
1e6002f
Merge branch 'master' into hyperupcall-various-improvements
hyperupcall Aug 9, 2023
d957c55
tweak
hyperupcall Aug 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/nodejs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ jobs:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: "16"
cache: "npm"
node-version: "18"
cache-dependency-path: src/package-lock.json
- name: npm ci
run: |
Expand Down
233 changes: 179 additions & 54 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,66 @@
## JSON Schema
# Contributing

You can contribute in a variety of ways. For a detailed tutorial, read [Scott Addie](https://twitter.com/Scott_Addie)'s [**Community-Driven JSON Schemas in Visual Studio 2015**](https://scottaddie.com/2016/08/02/community-driven-json-schemas-in-visual-studio-2015/) blog post.
- [Introduction](#introduction)
- [Overview](#overview)
- [Recommended Extensions](#recommended-extensions)
- [Troubleshooting](#troubleshooting)
- [Best practices](#best-practices)
- [How-to](#how-to)
- [How to add a new JSON Schema](#how-to-add-a-new-json-schema)
- [How to add a schema with multiple versions](#how-to-add-a-schema-with-multiple-versions)
- [How to add a schema that is self-hosted](#how-to-add-a-schema-that-is-self-hosted)
- [How to move a schema from SchemaStore to somewhere that's self-hosted](#how-to-move-a-schema-from-schemastore-to-somewhere-thats-self-hosted)
- [How to include a `$ref` to a SchemaStore schema](#how-to-include-a-ref-to-a-schemastore-schema)
- [How to include a `$ref` to an external schema](#how-to-include-a-ref-to-an-external-schema)

1. Submit new JSON schema files
2. Add a JSON schema file to the [catalog](#catalog)
3. Modify/update existing schema files
## Introduction

[Versioning of schema](https://github.com/SchemaStore/schemastore/issues/197#issuecomment-229690162) files are handled by modifying the file name to include
the version number: _myschema-1.2.json_
Welcome! Thank you for contributing to SchemaStore!

When uploading a new schema file, make sure it targets a file that is commonly
used or has potential for broad uptake.
There are various ways you can contribute:

Keep single source of truth. Do not copy an external schema here, but point the catalog to the external schema.
- Add a new JSON Schema
- Local schema
- Remote schema
- Enhance existing JSON schema
- Fix typos
- Fix incorrect schemas
- Improving constraints within existing schemas
- Add positive or negative tests for existing schemas

If you don't have Visual Studio (using macOS or Linux?), you can check your modifications are fine by running:
Most people want to add a new schema. For steps on how to do this, read the [How to add a new JSON Schema](#how-to-add-a-new-json-schema) section below.

```sh
make
```
If you want to contribute, but not sure what needs fixing, see the [help wanted](https://github.com/SchemaStore/schemastore/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) and [good first issue](https://github.com/SchemaStore/schemastore/issues?q=is%3Aopen+label%3A%22good+first+issue%22+sort%3Aupdated-desc) labels on GitHub.

### <a name="catalog"></a>Adding to catalog
## Overview

After adding a schema file in `src/schemas`, register them in alphabetical order in the [schema catalog](src/api/json/catalog.json) by adding an entry corresponding to your schema:
Schema files are located in `src/schemas/json`. Each schema file has a corresponding entry in the [Schema Catalog](src/api/json/catalog.json). Each catalog entry has a `fileMatch` field. IDEs use this field to know which files the schema should be used for (in autocompletion).

```json
{
"description": "Schema description",
"fileMatch": ["list of well-known filenames matching schema"],
"name": "Friendly schema name",
"url": "https://json.schemastore.org/<schemaName>.json"
}
```
Some schema files have associated positive and negative tests, located at `src/test` and `src/negative_test`, respectively. This repository has Grunt tasks that automatically load these files and use a validator (either [AJV](https://ajv.js.org) or [SchemaSafe](https://github.com/ExodusMovement/schemasafe)) to ensure that they either pass or fail validation.

There are three types of schema validation modes:

- [AJV](https://ajv.js.org) [strict mode](https://ajv.js.org/strict-mode.html): The default validation mode that is most stringent
- [AJV](https://ajv.js.org) 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.json](src/schema-validation.json)
- [SchemaSafe](https://github.com/ExodusMovement/schemasafe): Helps catch errors within schemas that would otherwise be missed. This is a WIP.

### Best practices
## Recommended Extensions

We highly recommend installing the following extensions for your IDE:

- [EditorConfig](https://editorconfig.org) to automatically configure editor settings
- [Prettier](https://prettier.io) to automatically configure file formatting

If you are modifying JavaScript files, we also recommend:

- [ESLint](https://eslint.org) to automatically show JavaScript issues

## Troubleshooting

- There may be `git merge` conflicts in `catalog.json` because you added the item to the end of the list instead of alphabetically
- The `pre-commit` build server failed because the PR was created/push from an organization and not from your own account

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

Expand Down Expand Up @@ -65,30 +92,141 @@ After adding a schema file in `src/schemas`, register them in alphabetical order
[base]: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/base.json
[base-04]: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/base-04.json

### Adding tests (for [local schemas](src/schemas/json) only)
## How-to

### How to add a new JSON Schema

To make sure that files are validated against your schema correctly (we strongly suggest adding at least one before creating a pull request):
You may also want to read [Scott Addie](https://twitter.com/Scott_Addie)'s [**Community-Driven JSON Schemas in Visual Studio 2015**](https://scottaddie.com/2016/08/02/community-driven-json-schemas-in-visual-studio-2015) blog post on how to add a new JSON schema.

1. Create a subfolder in [`src/test`](src/test) named as your schema file
2. Create one or more `.json`, `.yml`, `.yaml` or `toml` files in that folder
When uploading a new schema file, make sure it targets a file that is commonly used or has potential for broad uptake.

#### Adding negative tests
Be sure to keep a single source of truth. Do not copy an external schema here; instead, [point the catalog to the external schema](#how-to-add-a-schema-that-is-self-hosted).

To make sure that invalid files fail to validate against your schema, use a subfolder in [`src/negative_test/`](src/negative_test) instead.
First, clone the repository:

#### Run build locally
```sh
git clone https://github.com/SchemaStore/schemastore
cd schemastore
```

Be sure that [NodeJS](https://nodejs.org) is installed. The minimum required NodeJS version is defined by the `engines` key in [package.json](src/package.json). Now, install dependencies and run the `new_schema` Grunt task:

```sh
cd src
npm install
npm run grunt 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](src/api/json/catalog.json)

- Install [NodeJS](https://nodejs.org) (The minimum required NodeJS version "engines" is defined in [package.json](src/package.json))
- In subdirectory `src/`, run `npm clean-install`
- In subdirectory `src/`, run `npm run build` (to test a single schema, use `./node_modules/.bin/grunt --SchemaName=<jsonFileName.json> default`)
If you do not wish to use the `new_schema` Grunt task, the manual steps are listed below 👇

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

### Self-hosting schemas
<summary>Manual Steps</summary>

If you wish to retain full control over your schema definition, simply register it in the [schema catalog](src/api/json/catalog.json) by providing a `url` pointing to the self-hosted schema file to the [entry](#catalog). Example on how to handle [multiple schema versions.](https://github.com/SchemaStore/schemastore/pull/2057#issuecomment-1024470105)
1. Create a schema file in `src/schemas/json/<name>.json`:

### How to `$ref` from `schema_x.json` to `schema_y.json`
```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](src/api/json/catalog.json):

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

</details>

Once you have created the schema and its associated testing files, you can run the Grunt task that validates that your schema is corect:

```sh
cd src
npm run grunt
```

To test a single schema, execute `npm run grunt -- --SchemaName=<schemaName.json>`.

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

### How to add a schema with multiple versions

Refer to this [`agripparc` PR](https://github.com/SchemaStore/schemastore/pull/1950/files) as an example. First, your schema names should be postfixed 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:

```json
{
"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 add a schema that is self-hosted

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](https://github.com/SchemaStore/schemastore/pull/1211/files) as an example. Simply register your schema in the [schema catalog](src/api/json/catalog.json), with the `url` field pointing to your schema file:

```json
{
"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 move a schema from SchemaStore to somewhere that's self-hosted

Simply changing the `url` field in the schema catalog 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](https://github.com/SchemaStore/schemastore/pull/2421/files) for a full example.

### How to include a `$ref` to a SchemaStore schema

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

- Both schemas must exist [locally](src/schemas/json) in SchemaStore.
- Both schemas must have the same draft (example draft-07)
Expand All @@ -97,19 +235,6 @@ If you wish to retain full control over your schema definition, simply register
- In [schema-validation.json](src/schema-validation.json), in `"options": []` list add
`"schema_x.json": {"externalSchema": ["schema_y.json"]}`

### Recommended Editor Extensions

This project uses [EditorConfig](https://editorconfig.org) to configure editor settings and [Prettier](https://prettier.io) to configure file formatting.
Please install the EditorConfig and Prettier extensions for your IDE or code editor if they are not natively supported.

### Validation mode

SchemaStore supports two types of schema validation modes:

- [Full strict mode](https://ajv.js.org/strict-mode.html) via AJV validator (SchemaStore default mode)
- Not fully strict mode via AJV validator. (The json filename is present in the `ajvNotStrictMode` list in [schema-validation.json](src/schema-validation.json))

### Avoid common PR problems
### How to include a `$ref` to an external schema

- 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.
This currently isn't possible. This is tracked by [issue #2731](https://github.com/SchemaStore/schemastore/issues/2731).
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# JSON Schema Store

The largest collection of independent JSON schemas in the world
The largest collection of independent JSON schemas in the world.

[![Build status](https://github.com/SchemaStore/SchemaStore/actions/workflows/nodejs.yml/badge.svg)](https://github.com/SchemaStore/schemastore/actions/workflows/nodejs.yml)
[![CodeQL](https://github.com/SchemaStore/SchemaStore/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/SchemaStore/schemastore/actions/workflows/codeql-analysis.yml)

The repository is meant as a universal JSON schema store, where schemas for popular JSON documents can be found.
The repository is a universal JSON schema store, where schemas for popular JSON documents can be found.

Website: [schemastore.org](https://www.schemastore.org/json/)

## Contribute

Contributions are more than welcome. Both to the website itself or to the various schema files. Before contributing, please carefully read the [guidelines](./CONTRIBUTING.md).
Contributions are more than welcome! Both to the website itself or to the various schema files. Please carefully read [CONTRIBUTING.md](./CONTRIBUTING.md).
Loading