Versioning and publishing

Schemas are published per version under https://sidedoc.app/schemas/<version>/. A published version does not change: documents record the schema they were written against ($schema in the document and x-sidedoc.version in the schema), and the app keeps every version it supports.

The version number

VERSION in the root of the schemas repository holds the version being built (0.2.2 at the time of writing). The build puts it in every $id (https://sidedoc.app/schemas/0.2.2/datasheet.json), in x-sidedoc.version of each profile and in the help file references.

Bump VERSION for every change to the datamodel: a new, removed or retyped field, a changed cardinality or vocabulary binding. Fixing a help text does not change the datamodel.

To verify

There is no written rule yet for when to bump the major, minor or patch part.

A release, step by step

1. Bump VERSION.

2. Freeze the sheet tabs into versions/<version>/, so the version can be rebuilt offline and diffed against the previous one:

   SERVICE_ACCOUNT_PATH=/path/to/key.json python3 scripts/snapshot_source_tabs.py

3. Build and publish:

   ./build.sh

   The build generates output/, runs the vocabulary checks, the schema lint and the help lint, updates help/, copies the result to the static site content repository (.../static/sites/sidedoc/content/schemas/<version>/), points the latest symlink at it and runs the Ansible publish playbook.

4. Commit the snapshot TSVs and the updated help/ files in the schemas repository.

5. Copy the bundle into the app (next section) and regenerate the reference pages:

   DOCS_SITE_DIR=<monorepo>/docs/profiles/reference ./build-local.sh

Build options

Variable	Effect
FORCE=1	Overwrite a version that is already deployed. Without it the build stops when the deploy directory for VERSION exists and is not empty. Use it only for a version that is not in use yet.
SKIP_PUBLISH=1	Copy to the content repository but do not run the Ansible publish.
SERVICE_ACCOUNT_PATH	Google service account key, for reading the sheet through the API instead of the public TSV export.
SCHEMA_LINT_STRICT=1	Stop on schema lint issues (otherwise they are warnings).
HELP_LINT_STRICT=1	Stop on help lint warnings (format errors always stop the build).
DOCS_SITE_DIR	Also write the reference pages to $DOCS_SITE_DIR/<version>/.

build-local.sh rebuilds from versions/<VERSION>/*.tsv without the sheet, without refreshing vocabularies and without deploying. Use it to check a change or to regenerate help and reference pages.

Profiles in build.sh and build-local.sh

The two scripts do not build the same set. Both build the Data Envelope (CMDI) profile from versions/<VERSION>/cmdi-data-envelope.tsv. The NDE catalog profile has no sheet tab yet: while NDE_CATALOG_DESCRIPTION_GID is empty, build.sh copies the newest published catalog schema into the new version and restamps its $id to that version, and build-local.sh does not build it at all. The 0.2.1 and 0.2.2 bundles still carry the catalog schema with its 0.2.0 $id.

The copy in the app

The app does not fetch schemas from the schema site. Each version bundle is committed in the monorepo under app/sidedoc-frontend/public/schemas/<version>/: the schemas, the docs.*.json help files, field-attachments.json, help-texts.json and example-data.json. This way the app and its container image ship with the datamodel versions they work with.

public/schemas/versions.json lists, per version, the type library and the profiles (id, file, label). The app uses it to offer profiles and to open documents of older versions. Regenerate it after adding a bundle:

python3 scripts/build_versions_manifest.py

It scans every public/schemas/<version>/ directory and puts the current datasheet first (the default for new documents). MIN_SUPPORTED_SCHEMA_VERSION (default 0.0.0) sets the oldest version the app edits directly; older documents open read-only.

The SKOS vocabularies are copied the same way, into public/vocab/, with npm run sync:vocab -w sidedoc-frontend. The backend copies the RDF mapping files from rdf-targets/ at build time.

To verify

• How a new bundle gets from output/ (or the content repository) into public/schemas/<version>/ in the monorepo. No script in either repository does this; it appears to be a manual copy.
• build_versions_manifest.py finds the app at ../app/sidedoc-frontend relative to the schemas repository, which is the layout of the old split repositories. In the monorepo layout it needs to be pointed at <monorepo>/app/sidedoc-frontend/public/schemas.
• help/help.schema.json is not deployed, although the published help files name it in $schema.