Schemas

Schema versioning

Versions never change meaning. Requests say which one they used.

A schema is identified by name@version. A saved version is immutable: saving the same version again with different content returns 409 version_exists. Saving identical content is a no-op. To change a schema, save a new version.

Choosing a version

-F schema=restaurant_order          # latest version
-F schema=restaurant_order@1.0      # pinned
-F schema=restaurant_order -F schemaVersion=1.0   # pinned, as a separate field

Every result carries schema and schemaVersion, so you always know which contract produced it.
A session pins the version it started with, even if a newer one is saved meanwhile.
GET /api/v1/schemas/{name}/versions lists them; an unknown version returns 404 with the versions that exist.
Production integrations should pin a version; the dashboard and tests can follow the latest.

Storage

In the prototype, schemas are JSON files: built-ins in schemas/, yours under SCHEMA_STORE_DIR (default data/schemas). The store is one class, ready to move to a database.