Overview

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:

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

Open the schema. It uses JSON Schema draft 2020-12.

Where it comes from

The schema is generated from the Zod validators of @welldot/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 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).

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

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

In code

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

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

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

Object reference: the schema rendered as one page per object.
Validating: all the ways to check a file.