open-standards/wai/schema/README.md

Project file schemas

wai-json-1.schema.json is the JSON Schema of wai.json, a WAI project file, version 1 (JSON Schema 2020-12). Its $id, and the $schema member every project file wai create writes names, is https://wai.transaction.science/schema/wai.json/1, the address it is to be served from. The release of wai waits for it: the tag build (.github/workflows/wai-release.yml) fails while that address does not serve this file, so no release writes a project file that names a schema an editor or an agent cannot fetch.

wai/wai-rs/src/bin/wai_cli/dx/project.rs is the reader. Its tests hold this file to it: the same members in the file and in its dev block, the same modes, the same name rule, and the same verdict, accept or refuse, on every template's project file and on a set of files each breaking one rule. A change to either is a change to both.

Versions

Version 1 stays open until the first release of wai that writes it. From that release on, its readers are in use, and a reader refuses any member it does not know, so version 1 does not change: a member added to it would be refused, as unknown, by every reader of that release. A later version is a new schema at …/schema/wai.json/<version>, beside this one. A reader refuses a file of a later version as that version (upgrade wai), by its wai member or by its $schema, before it reads any other member, so the members the later version adds never stop it first.

The project file's other members in the toolchain's design (requires, room, package, conform, breaking, targets, receipts, and port in dev) are version 2's. Each joins the file with the operation that reads it, as every member of version 1 has its reader; a member accepted with nothing to read it would be one the strict reader ignores, which is what it refuses to do.