Archify Schema Versioning Policies: Ensuring Stable Data Contracts Across the Repository

Archify enforces strict schema versioning by requiring a schema_version field in every JSON schema and artifact, incrementing the version only for breaking changes, and aborting builds when receipts mismatch the current schema version defined in .impeccable/design.json.

The tt-a1i/archify repository maintains data integrity across diagrams, workflows, and runtime artifacts through mandatory schema versioning documented in archify/schemas/README.md. Every JSON schema file includes a required top-level schema_version property that monotonically increments when breaking changes occur, allowing downstream tools to detect incompatible data formats immediately.

Mandatory Schema Version Fields

Every schema definition in archify/schemas/—including workflow.schema.json and sequence.schema.json—declares a required schema_version property at the root level. This field serves as the contract version between the repository and any consumer of Archify-generated JSON.

Generated artifacts also embed this metadata. Receipt files like examples/checkout-platform-delta.receipt.json and gallery manifests include the current schemaVersion value, enabling runtime validation before processing.

Breaking Changes vs. Additive Updates

The versioning policy distinguishes between breaking and non-breaking modifications. The schema_version value increments only when changes alter the contract incompatibly.

Breaking changes that require a version bump include:

• Removing a required property
• Renaming an existing field
• Altering the type of an existing attribute

Non-breaking changes that preserve the current version:

• Adding new optional fields
• Expanding enumeration values without removing existing ones
• Adding metadata that does not affect parsing logic

Build Pipeline Enforcement

The repository's build pipeline validates every receipt and manifest against the current schema version before accepting artifacts. According to docs/research-visual-evolution-round-44.md, the pipeline aborts the gallery build immediately if a receipt's schemaVersion does not match the expected current version.

This enforcement ensures that stale or manually edited artifacts cannot enter the distribution pipeline, protecting downstream renderers and CI integrations from processing incompatible data.

Repository-Wide Version Tracking

The .impeccable/design.json file tracks the canonical schema version for the entire repository. Currently set to version 2, this file acts as the source of truth for the build pipeline and validation tools.

When contributors introduce breaking changes, they must increment this repository-wide version number in addition to updating individual schema files.

Validating Schema Versions in Practice

Consumers can validate Archify artifacts programmatically by checking the embedded version field and validating against the schema definition.

Check receipt compatibility before processing:

import receipt from './checkout-platform-delta.receipt.json';

if (receipt.schemaVersion !== 2) {
  throw new Error(`Unsupported schema version ${receipt.schemaVersion} – please upgrade Archify.`);
}

Validate a diagram against the workflow schema using AJV:

import Ajv from 'ajv';
import workflowSchema from '../archify/schemas/workflow.schema.json';
import diagram from './my-diagram.json';

const ajv = new Ajv();
const validate = ajv.compile(workflowSchema);

if (!validate(diagram)) {
  console.error(validate.errors);
  throw new Error('Diagram does not match current workflow schema.');
}

Summary

• Archify requires a schema_version field in every schema and generated artifact
• Version numbers increment monotonically and only for breaking changes
• The build pipeline aborts when detecting version mismatches in receipts
• .impeccable/design.json tracks the current repository-wide schema version
• Optional additive fields do not trigger version increments

Frequently Asked Questions

What happens if a receipt uses an outdated schema version?

The build pipeline aborts the gallery build immediately upon detecting a mismatch between the receipt's schemaVersion and the current version defined in the repository. Downstream tools should throw errors when encountering unsupported versions to prevent processing incompatible data.

Do optional fields require a schema version increment?

No. Adding optional fields or expanding metadata without removing existing properties constitutes a backward-compatible change. The schema_version only increments for breaking changes such as removing required fields, renaming properties, or altering existing types.

Where is the current schema version defined?

The .impeccable/design.json file stores the repository-wide schema version, currently set to 2. This file serves as the canonical source for build pipeline validation and consumer compatibility checks.

How does Archify validate JSON artifacts?

All JSON artifacts undergo validation against their respective schemas in archify/schemas/ before acceptance into the repository or publication as ZIP artifacts. The validation ensures that schema_version fields match the expected values and that all required properties conform to the current contract.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}