# Schema Versions for Archify Diagrams: Understanding the Single Version System

> Discover Archify diagram schema versions. Archify enforces a single schema version 1 for all diagram types using JSON Schema constants. Learn more about diagram versioning.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-15

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), the schema enforces this through a const declaration:

```json
"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`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)
- **Workflow diagrams**: Defined in [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)
- **Sequence diagrams**: Defined in [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json)
- **Lifecycle diagrams**: Defined in [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)
- **Dataflow diagrams**: Defined in [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) and [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json).

## Validating Schema Versions

### Node.js Programmatic Validation

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

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) — Shared definitions used by all diagram schemas
- [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) — Architecture diagram schema with the `schema_version` const definition
- [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) — Workflow diagram schema
- [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) — Sequence diagram schema
- [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) — Lifecycle diagram schema
- [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.