What is the Purpose of schema_version in Archify JSON? A Complete Guide

The schema_version field in Archify JSON identifies which version of the project's JSON schema a document complies with, enabling validation, backward compatibility, and safe schema migrations.

The tt-a1i/archify repository uses a structured JSON format to define software architecture documents. Every Archify JSON file includes a schema_version field at the top level that serves as the authoritative signal for how the document should be parsed, validated, and processed. This guide explains exactly how this field works based on the source code and example files in the repository.

What schema_version Does in Archify

The schema_version field operates as a contract between the document author and the Archify tooling. When present in examples/archify-repo.architecture.json and other Archify files, it performs four critical functions:

• Document validation — The parser checks that structure and data types match the expected schema for that version
• Backward compatibility — Older workflows or tools can read files they understand while newer tools detect newer versions
• Migration facilitation — When schemas evolve, the version value tells the system which conversion logic to apply
• Safe collaboration — Multiple contributors and automated pipelines exchange files with guaranteed structural understanding

Where schema_version Appears in the Repository

The examples/archify-repo.architecture.json file demonstrates the field in practice. This example file, located in the examples/ directory, shows how Archify documents begin with a clear version declaration.

The repository structure implies that DESIGN.md contains the authoritative documentation on how schema versions are managed across releases, while README.md provides the broader context on JSON format and versioning strategy.

How schema_version Enables Schema Evolution

Architectural description formats inevitably change as projects mature. The schema_version field solves the compatibility problem that arises when:

1. New properties are added to the schema
2. Existing properties are renamed or restructured
3. Data type requirements change
4. Entire sections of the document format are deprecated

When Archify loads a file, the tool reads schema_version, selects the corresponding schema definition, validates the payload, and runs any migration steps to the latest schema before processing.

Example Archify JSON with schema_version

This minimal example from the repository's example file shows the field placement:

{
  "schema_version": "2.0",
  "metadata": {
    "name": "Demo Workflow",
    "description": "A simple example"
  },
  "components": [
    {
      "type": "trigger",
      "id": "start",
      "config": {}
    }
  ]
}

Note that the schema_version field appears as the first property in the document, making it immediately accessible to parsers before full validation occurs.

Practical Implementation: Reading schema_version

This JavaScript example shows how to branch logic based on the schema_version value:

import fs from 'fs';

const doc = JSON.parse(fs.readFileSync('my-workflow.json', 'utf-8'));

switch (doc.schema_version) {
  case '1.0':
    // Apply legacy handling for early Archify formats
    break;
  case '2.0':
    // Current handling according to latest schema
    break;
  default:
    throw new Error(`Unsupported schema version: ${doc.schema_version}`);
}

Pattern matching on schema_version allows tools to support multiple document generations simultaneously without breaking existing workflows.

Key Files Related to schema_version

These repository files contain essential information about how schema_version functions:

File	Purpose
examples/archify-repo.architecture.json	Demonstrates schema_version in a real workflow definition
DESIGN.md	Documents how schema versions are managed across releases
README.md	Provides context on JSON format and versioning strategy

Summary

• schema_version is a required top-level field in every Archify JSON document
• It enables validation against the correct schema definition
• It guarantees backward compatibility across tooling versions
• It supports automated migrations when schemas evolve
• It appears first in documents, as shown in examples/archify-repo.architecture.json
• Tools branch logic based on its value to handle multiple format generations

Frequently Asked Questions

Why is schema_version required instead of optional?

Archify requires schema_version to eliminate ambiguity. Without an explicit version marker, parsers cannot distinguish between legacy and current formats, leading to silent failures or incorrect interpretation of document structure. The required field ensures every file carries self-describing metadata about its expected shape.

What happens if schema_version is missing or unrecognized?

Tools reading Archify JSON will typically fail fast with a clear error message. The schema_version check occurs before expensive validation or processing begins. An unrecognized version triggers an explicit error (as shown in the JavaScript example above), preventing undefined behavior from schema mismatches.

How does Archify handle schema version migrations?

According to the design patterns implied by the repository structure, Archify uses schema_version to select transformation logic. When a file with an older version is loaded, the system applies incremental migrations—1.0 → 1.1 → 2.0—until the document reaches the current schema version, at which point standard processing proceeds.

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