## Authoring a type schema

For each type, there are two files:

- `<type>.schema.yaml` is the JSON Schema, written in YAML, for the type.

- `<type>.md` documentation for the type including examples and a description of design considerations for the schema

### Writing `<type>.schema.yaml` files

See [Writing Schema Definitions](docs/writing-schema-definitions.md)

### Writing `<type>.md` documentation

See [Writing Schema Docs](docs/writing-schema-docs.md)

## Authoring a type schema

For each type, there are two files:

- `<type>.schema.yaml` is the JSON Schema, written in YAML, for the type.

- `<type>.md` documentation for the type including examples and a description of design considerations for the schema

### Writing `<type>.schema.yaml` files

See [Writing Schema Definitions](docs/writing-schema-definitions.md)

### Writing `<type>.md` documentation

See [Writing Schema Docs](docs/writing-schema-docs.md)

## Autogenerated Schema Bindings

We derive language binding files such as [types.ts](./ts/types.ts),
[types.py](./py/stencila/schema/types.py), and [types.R](./r/R/types.R) from
the [schema YAML files](./schema/).

Despite those files being auto-generated, there are a couple of reasons why it is useful to include them in this repository.

- Having them so that packages can be installed from the Git repo e.g.

```r
devtools::install_github("stencila/schema", subdir = "r", upgrade = "ask")
```

```bash
pip install -e git+https://github.com/stencila/schema.git#subdirectory=py
```

- Allows us to more easily compare changes to the bindings and potentially identify issues.

However, since these files are derived from the YAML files, there is
potential risk of the type bindings and schema YAML to drift out of sync.

One remedy we have in place is to use [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).
This allows us to automatically build the schema, detects changes in the bindings, and commit them prior to each push command.

To see the exact steps being performed, please see the [`checkBindings`](./Makefile) command in the `Makefile`.

Add note re. Autogenerated Schema Bindings
docs(Contributing): Add note re. Autogenerated Schema Bindings
