# How Archify Handles Backward Compatibility for Schemas: A Complete Technical Guide

> Learn how Archify ensures backward compatibility for schemas using versioned JSON IR, legacy validators, add-only evolution, and automated testing. Explore the tt-a1i/archify repository for details.

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

---

**Archify guarantees backward compatibility through a versioned JSON IR with mandatory `schemaVersion` fields, bundled legacy validators, optional add-only schema evolution, and automated regression testing.**

Archify stores architectural diagrams in a typed JSON intermediate representation (IR) that must include a top-level `schemaVersion` field. This version number drives a strict validation pipeline ensuring legacy artifacts remain loadable across releases. According to the Archify source code, this policy preserves rendering capability for any previously-produced diagram while enabling safe forward evolution.

## The `schemaVersion` Field as the Compatibility Anchor

Every Archify JSON document declares its schema version explicitly. In [`/.impeccable/design.json`](https://github.com/tt-a1i/archify/blob/main//.impeccable/design.json), the design system defines this version globally:

```json
{
  "schemaVersion": 2,
  "meta": { "title": "System Architecture", "legend": [] },
  "nodes": [],
  "edges": []
}

```

This field determines which validator runs when the file loads. The version is **not optional**—omitting it causes immediate validation failure, preventing ambiguous parsing.

## Version-Aware Validator Selection

Archify bundles multiple validators alongside each release rather than replacing them. When loading a diagram:

1. The loader reads `schemaVersion`
2. It instantiates the matching validator from the bundled set
3. Validation proceeds against the schema defined for that version

This approach ensures a file stamped with `"schemaVersion": 1` validates against the v1 schema even when opened in Archify v2. The source code in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) documents this behavior explicitly, noting that legacy validators remain available indefinitely.

## Optional, Add-Only Schema Evolution

Archify enforces a strict **add-only policy** for schema changes:

- **New fields are always optional** — Existing documents load without supplying new data
- **Required fields never change shape** — Once required, a field's structure remains stable
- **Unknown optional fields are ignored** — Older releases skip unrecognized keys gracefully

Compare these two valid documents:

```json
// v1 document — minimal, fully supported
{
  "schemaVersion": 1,
  "meta": { "title": "Demo", "legend": [] },
  "nodes": [{ "id": "A", "label": "Service A" }],
  "edges": [{ "from": "A", "to": "B" }]
}

```

```json
// v2 document — adds optional fields, v1 runtime still compatible
{
  "schemaVersion": 2,
  "meta": {
    "title": "Demo",
    "legend": [],
    "description": "Optional description added in v2"
  },
  "nodes": [{ "id": "A", "label": "Service A", "role": "frontend" }],
  "edges": [{ "from": "A", "to": "B", "type": "http" }]
}

```

A v1 validator accepts the first document. A v2 validator accepts both—omitting `description`, `role`, or `type` does not cause validation errors.

## Compatibility Tests and Regression Gates

Before any schema version ships, Archify runs automated compatibility verification per [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md):

- **Compatibility corpus testing** — All previously-generated JSON artifacts must validate against the new validator
- **CI pipeline blocking** — Compatibility failures prevent release
- **Changelog documentation** — Breaking changes are explicitly versioned (see [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) release 1.5.20 for install-path compatibility preservation)

This creates a technical guarantee: **no release can ship that breaks loading of existing diagrams**.

## Key Implementation Files

| Path | Purpose |
|------|---------|
| [`/.impeccable/design.json`](https://github.com/tt-a1i/archify/blob/main//.impeccable/design.json) | Global `schemaVersion` definition and design system metadata |
| [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) | Schema evolution rules and add-only policy documentation |
| [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) | Compatibility-focused release history |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) | Validation pipeline overview |

## Summary

Archify handles backward compatibility for schemas through four integrated mechanisms:

- **Mandatory `schemaVersion` field** — Unambiguous version declaration in every document
- **Bundled legacy validators** — Old schemas remain executable in new releases
- **Add-only optional evolution** — New capabilities don't break existing documents
- **Automated regression testing** — CI gates prevent compatibility-breaking changes

This policy ensures architectural diagrams created today will render correctly in future Archify versions without migration or modification.

## Frequently Asked Questions

### What happens if I open a v1 diagram in Archify v2?

Archify detects `schemaVersion: 1` and instantiates the v1 validator. The diagram loads and renders exactly as created. Optional v2 fields are absent, which the validator treats as valid per the add-only policy.

### Can I upgrade a v1 diagram to v2 without breaking older Archify installations?

Yes. Save the document with `schemaVersion: 2` and include any new optional fields you need. Older Archify releases will reject the file at load time due to unrecognized version—this is intentional safety behavior, not data corruption.

### Does Archify ever remove deprecated validators from the bundle?

Per [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), validators are **never removed**. The compatibility corpus tests in CI ensure all historical versions remain testable and functional. This increases bundle size but eliminates legacy data loss risk.

### How does Archify prevent accidental breaking changes in schema development?

The CI pipeline runs compatibility corpus tests that verify new validators accept all historical test artifacts. Any change causing validation failure for existing documents blocks release. This mechanical enforcement makes breaking changes structurally difficult to ship.