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

> Learn about Archify's schema versioning policies. Enforce stable data contracts with strict versioning, breaking change increments, and build aborts for receipt mismatches.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: best-practices
- Published: 2026-08-14

---

**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`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) and [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/.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:

```javascript
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:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/.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.