Schema Versions for Archify Diagrams: Understanding the Single Version System

Archify uses a single schema version 1 for all diagram types, enforced through JSON Schema constants in the archify/schemas directory.

The tt-a1i/archify repository defines a unified approach to schema versioning for its JSON-based diagram formats. Every diagram file—whether architecture, workflow, sequence, lifecycle, or dataflow—must declare "schema_version": 1 at the root level to pass validation. This design ensures consistent parsing and prevents rendering errors across the entire Archify ecosystem.

Schema Version Architecture

The Universal Version Constant

Archify standardizes on version 1 as a required constant. In archify/schemas/architecture.schema.json, the schema enforces this through a const declaration:

"schema_version": { "const": 1 }

This pattern is replicated across all diagram-specific schemas. Any JSON file claiming to be an Archify diagram must contain exactly "schema_version": 1; no other values are accepted.

Diagram Types Covered

The single schema version applies uniformly to all five supported diagram types. Each schema file in archify/schemas/ references the same version constant:

• Architecture diagrams: Defined in architecture.schema.json
• Workflow diagrams: Defined in workflow.schema.json
• Sequence diagrams: Defined in sequence.schema.json
• Lifecycle diagrams: Defined in lifecycle.schema.json
• Dataflow diagrams: Defined in dataflow.schema.json

Schema Validation Implementation

AJV Validation Logic

Archify uses the ajv (Another JSON Schema Validator) library to enforce compliance. During validation, ajv checks that the schema_version field exists and equals 1. The test suite in archify/test/golden.mjs confirms that diagrams with missing or incorrect schema versions trigger validation failures, protecting the rendering pipeline from incompatible data structures.

Creating Compliant Diagrams

When authoring a new diagram, include the schema_version property as the first field in your JSON object. Here is a minimal valid architecture diagram:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Simple Service",
    "description": "A tiny example architecture diagram"
  },
  "components": [
    {
      "id": "svc",
      "type": "service",
      "label": "Service",
      "position": { "x": 100, "y": 100 },
      "size": { "width": 120, "height": 60 }
    }
  ]
}

All example files in the repository follow this pattern, including examples/archify-repo.architecture.json and examples/agent-tool-call.workflow.json.

Validating Schema Versions

Node.js Programmatic Validation

Use the built-in validator to check schema compliance before processing:

import { validateArchitecture } from '@archify/validator';

const diagram = require('./my-diagram.json');
const result = validateArchitecture(diagram);

if (!result.valid) {
  console.error('Schema validation failed:', result.errors);
} else {
  console.log('Diagram is valid and ready for rendering');
}

CLI Validation

For quick checks from the command line, use the Archify CLI:

npx archify validate ./my-diagram.json

# → [ok] Standalone schema validators

# → Diagram conforms to schema version 1

Where Schema Versions Are Defined

The schema version constant is centralized in shared definitions and referenced by individual diagram schemas:

• archify/schemas/common.schema.json — Shared definitions used by all diagram schemas
• archify/schemas/architecture.schema.json — Architecture diagram schema with the schema_version const definition
• archify/schemas/workflow.schema.json — Workflow diagram schema
• archify/schemas/sequence.schema.json — Sequence diagram schema
• archify/schemas/lifecycle.schema.json — Lifecycle diagram schema
• archify/schemas/dataflow.schema.json — Dataflow diagram schema

Summary

• Archify uses schema version 1 as the sole valid version across all diagram types
• The schema_version property must be present at the top level of every diagram JSON file
• Validation uses ajv to enforce the constant value defined in archify/schemas/architecture.schema.json
• All diagram types—including architecture, workflow, sequence, lifecycle, and dataflow—share this universal version
• Example files in the examples/ directory demonstrate proper usage with "schema_version": 1

Frequently Asked Questions

What happens if I omit the schema_version field in an Archify diagram?

The diagram will fail validation. According to the test suite in archify/test/golden.mjs, ajv rejects any diagram lacking the schema_version property or containing a value other than 1. The validator returns specific error messages indicating the missing or mismatched field, preventing the diagram from being processed further.

Can I use schema version 2 or higher for custom diagrams?

No. The JSON Schema definitions in archify/schemas/ explicitly set "const": 1 for the schema_version field. Any value other than 1 causes immediate validation failure, ensuring that all diagrams conform to the single supported schema version before reaching the rendering engine.

Do different diagram types have different schema versions?

No. All five diagram types (architecture, workflow, sequence, lifecycle, and dataflow) use the same schema version 1. While each diagram type has its own schema file in archify/schemas/, they all reference the same version constant, ensuring unified compatibility across the entire diagram ecosystem.

How do I check which schema version an existing diagram uses?

Examine the top-level schema_version field in the JSON file. Valid Archify diagrams will show "schema_version": 1 immediately after the opening brace. You can also run npx archify validate on the file to confirm it conforms to the expected version according to the source code validation logic.

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