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

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, the design system defines this version globally:

{
  "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 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:

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

// 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:

• 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 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	Global schemaVersion definition and design system metadata
archify/schemas/README.md	Schema evolution rules and add-only policy documentation
CHANGELOG.md	Compatibility-focused release history
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, 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.

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