Schemas and datamodel versions

Every SideDoc document records the datamodel version it was written with, in its $schema pointer (for example https://sidedoc.app/schemas/0.2.2/datasheet.json). A deployment serves the schemas of several versions side by side, so older documents keep opening against the schema they were made with.

What is served

The schemas come from the separate schemas repository. The app repository holds committed copies in app/sidedoc-frontend/public/schemas/, which end up in every build and image:

Path	Content
/schemas/<version>/	One immutable bundle per version: the profile schemas (datasheet.json, dcat-ap-dataset.json, ...), type-library.json, help texts and examples.
/schemas/versions.json	Manifest: the latest version and, per version, its type library and profiles. The app reads it to know which profiles exist.
/schemas/*.json	Unversioned flat copies, the last fallback when a versioned path is missing (see below).

To see which versions an image contains, read the manifest:

curl -s http://127.0.0.1:8080/schemas/versions.json | jq '.latest, (.versions | keys)'

At the time of writing these are 0.1.1, 0.1.2, 0.2.1 and 0.2.2, with 0.2.2 the latest.

How the app picks a schema

For a document with schema version v and profile file f, the app tries, in order:

1. schemas/<v>/<f>: the document's own version.
2. schemas/<current>/<f>: the version the app is pinned to.
3. schemas/<f>: the flat copy.

New documents use the pinned version.

Settings

Container	Build	Default	Effect
SIDEDOC_SCHEMA_VERSION	VITE_SCHEMA_VERSION	0.2.2	Version new documents are created with. The container checks that the bundle exists and refuses to start otherwise.
SIDEDOC_MIN_SUPPORTED_SCHEMA_VERSION	VITE_MIN_SUPPORTED_SCHEMA_VERSION	0.0.0	Documents with an older version open read-only and must be converted before editing.

You normally leave both alone: each release is built and tested against its own default. Set SIDEDOC_SCHEMA_VERSION to an older bundled version to hold back a datamodel change for a while after upgrading the app. Raise the minimum only when the release notes say an old datamodel is no longer supported for editing.

The build default lives in app/sidedoc-frontend/src/config/schemaVersion.ts.

Updating the schemas

Schemas change in the schemas repository; the app picks them up through a new release. To bring a new datamodel version into the app repository:

1. Build the schemas repository (build.sh writes to output/) and note its VERSION.

2. Copy the bundle to app/sidedoc-frontend/public/schemas/<version>/. Never change a bundle that has already been published: documents point at it.

3. Regenerate public/schemas/versions.json with scripts/build_versions_manifest.py from the schemas repository. The script writes into ../app/sidedoc-frontend/public/schemas relative to the schemas checkout (the layout from before the monorepo), so point it at this repository, or copy the result.

4. Sync the SKOS vocabularies:

   SIDEDOC_SCHEMAS_DIR=/path/to/schemas npm run sync:vocab -w sidedoc-frontend

5. Regenerate the vocabulary index and DCAT mappings in the backend, which also needs the schemas checkout:

   SIDEDOC_SCHEMAS_DIR=/path/to/schemas npm run prebuild -w @sidedoc/backend

   The output is deterministic: an unchanged schemas checkout gives no diff.

6. Bump the default in src/config/schemaVersion.ts, run the tests and commit everything.

A deployment then only needs the new image or build. The profiles themselves are documented in the Profiles & schemas section.

Schema URLs and sidedoc.app

Schema $ids point at https://sidedoc.app/schemas/<version>/.... A self-hosted SideDoc serves the same files under its own origin and resolves documents against them, so it does not depend on sidedoc.app being reachable. Other tools that dereference a document's $schema will still go to sidedoc.app.