# JSON Schema

> The published JSON Schema for .well v2, where it comes from, and how to validate files with it in editors and in languages other than TypeScript.

The `.well` v2 JSON Schema describes the shape of a valid file in a form every language can use. It is published at a stable address, which is also its `$id`:

```text
https://welldot.org/schema/v2/well.schema.json
```

[Open the schema](https://welldot.org/schema/v2/well.schema.json). It uses JSON Schema draft 2020-12.

## Where it comes from

The schema is generated from the Zod validators of [`@welldot/core`](/core), the reference implementation, so the schema and the library accept the same documents. It lives in the repository at [`spec/schema/v2/well.schema.json`](https://github.com/welldothq/welldot/blob/main/spec/schema/v2/well.schema.json) and is never edited by hand; CI fails when it is out of date. It also ships in the npm package as `@welldot/core/well.schema.json`.

The prose specification remains the authority on meaning. The schema covers structure: required fields, types, enumerations and patterns. Rules that need context, such as how a reader handles a v1 file, are in the spec and in `parseWell` ([Schema validation](/format/spec/v2/interoperability#schema-validation)).

## In an editor

Add `$schema` to a file to get completion and inline errors in editors that support JSON Schema, such as VS Code (map `*.well` to JSON first):

```json
{
  "$schema": "https://welldot.org/schema/v2/well.schema.json",
  "version": "2.4"
}
```

## In code

::code-group

```ts [JavaScript (ajv)]
import Ajv2020 from 'ajv/dist/2020.js';
import addFormats from 'ajv-formats';

const schema = await (
  await fetch('https://welldot.org/schema/v2/well.schema.json')
).json();
const ajv = new Ajv2020({ allErrors: true, strict: false });
addFormats(ajv);
const validate = ajv.compile(schema);

if (!validate(JSON.parse(text))) console.log(validate.errors);
```

```python [Python (jsonschema)]
import json, urllib.request
from jsonschema import Draft202012Validator

url = "https://welldot.org/schema/v2/well.schema.json"
schema = json.load(urllib.request.urlopen(url))
validator = Draft202012Validator(schema)

with open("PT-01.well", encoding="utf-8") as f:
    for error in validator.iter_errors(json.load(f)):
        print(list(error.path), error.message)
```

::

In TypeScript, prefer `parseWell` from `@welldot/core`: it is the same rule set, returns typed data and upgrades v1 files ([Parsing and validating](/core/guides/parsing-and-validating)).

## Versions of the schema

There is one schema per major version. The v2 schema accepts every v2 revision, from the integer `2` to `"2.4"`. A future v3 would get its own address ([deprecation policy](/format/spec/v2/format-reference#deprecation-policy)).

## Related

- [Object reference](/format/reference/objects): the schema rendered as one page per object.
- [Validating](/format/guides/validating): all the ways to check a file.