Skip to content
Almathal Handbook

ADR-0020: Manifest Schema Versioning

Accepted

Date: 2026-06-10

Context

The Manifest schema will evolve. Today’s fields might be insufficient in six months; new categories of metadata may need to be expressed. Versioning the schema is necessary to allow evolution without breaking existing Manifests.

Decision

The Manifest schema is versioned with integer major versions (e.g., manifest-v1, manifest-v2):

  • Backward-compatible additions (new optional fields, new enum values) stay within the same major version. Old Manifests remain readable.
  • Breaking changes (removing fields, changing field semantics, restructuring) require a major version bump.
  • Migration tooling is provided for any major version bump. Old Manifests can be auto-converted.

The Archetype Spec schema follows the same versioning policy.

Old Manifests at older schema versions remain readable by the platform indefinitely — no forced migration.

Rationale

  • Integer versioning matches the interface-like nature of schemas (Capabilities and Contracts use the same model — ADR-0010).
  • Backward-compatible additions allow incremental evolution without ceremony.
  • Breaking changes are uncommon and warrant the migration investment.
  • Old Manifests remaining readable preserves audit trail integrity.

Consequences

  • Every Manifest declares its schema version at the top (manifest_version: "adapter-manifest/v1").
  • The platform’s Manifest parser supports multiple schema versions concurrently.
  • Schema documentation is versioned: /schemas/adapter-manifest-v1/, /schemas/adapter-manifest-v2/, etc.
  • Schema changes go through ADR review.

References