ADR 0003: Index Schema Versioning Policy

Status: Accepted for architectural direction.

Date: 2026-05-11.

Context

The scraper pipeline will emit SQLite runtime indexes.

The backend will load those indexes at startup.

The index schema will evolve as parser coverage improves.

The backend API will evolve as query features grow.

The frontend will depend on stable backend responses.

A backend built for one index schema may misread another schema.

Silent index/backend mismatch would create incorrect course and credential answers.

The project needs an explicit compatibility contract.

The project also needs catalog-version metadata in every runtime artifact.

The index must distinguish source calendar version from UWScrape schema version.

The index must distinguish parser version from index schema version.

Decision

Every runtime index must include explicit version metadata.

The SQLite database must include an index_metadata table.

The index_metadata table must include index_schema_version.

The index_metadata table must include catalog_id.

The index_metadata table must include catalog_slug.

The index_metadata table must include catalog_title.

The index_metadata table must include catalog_start_date.

The index_metadata table must include catalog_end_date.

The index_metadata table must include source_snapshot_id.

The index_metadata table must include source_snapshot_hash.

The index_metadata table must include parser_version.

The index_metadata table must include validation_status.

The index_metadata table must include validation_summary_hash.

The index_metadata table must include built_at.

The index_metadata table must include build_tool_version.

The backend must check index_schema_version before serving.

The backend must have an explicit list of supported index schema versions.

The backend must refuse unsupported index schema versions by default.

The backend must report unsupported versions clearly.

The backend must expose loaded index metadata through a health or catalog endpoint.

Index schema versions must use semantic versioning.

Breaking table or column semantics require a major version bump.

Backward-compatible additions require a minor version bump.

Build metadata-only changes may require a patch version bump.

The initial schema version should be 0.1.0.

Version Meanings

index_schema_version describes SQLite table and data semantics.

parser_version describes parser behavior.

source_snapshot_id describes the raw data snapshot.

catalog_id describes the upstream Kuali catalog.

catalog_slug describes the local publication name.

validation_status describes whether the artifact passed release checks.

build_tool_version describes the UWScrape build command version.

These values must not be collapsed into one version.

They answer different compatibility questions.

Compatibility Rules

The backend may support one major schema version at a time initially.

The backend may support multiple minor versions if table additions are safe.

The backend should not attempt best-effort reads of unsupported major versions.

The index builder should write the newest schema version it supports.

The validator should validate the schema version before publication.

The backend should expose a clear startup error for schema mismatch.

The backend should not auto-migrate published read-only indexes at startup.

Index migration should be a build-time operation.

If migration is needed, it should produce a new published index directory.

Alternatives Considered

Alternative 1: Rely on SQLite Table Shape

The backend could inspect tables and infer compatibility.

This avoids explicit version maintenance.

However, table presence does not prove semantic compatibility.

It also makes error messages worse.

This alternative is rejected.

Alternative 2: Single Project Version

The project could use one global UWScrape version for everything.

This is simpler.

However, parser changes, schema changes, and source catalog changes are independent.

One version would obscure compatibility.

This alternative is rejected.

Alternative 3: Runtime Auto-Migrations

The backend could migrate older indexes at startup.

This is convenient in some applications.

However, UWScrape indexes are generated artifacts.

Runtime mutation would violate the read-only artifact boundary.

This alternative is rejected for the initial architecture.

Consequences

Backend startup becomes safer.

Index build output becomes more self-describing.

Future migrations require explicit build tooling.

The project must maintain schema version notes.

The project can support historical catalogs without confusing schema compatibility.

The frontend can display source catalog metadata accurately.

Follow-Up

Define the initial SQLite schema in the backend/index architecture spec.

Define supported schema versions in backend configuration.

Add a schema compatibility check before any query endpoint serves traffic.

Add validation report fields that mirror index metadata.