# How Archify Handles Schema Versions for Workflow Diagrams

> Learn how Archify manages schema versions for workflow diagrams. Discover automatic migration and backward compatible rendering pipelines for seamless updates.

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

---

**Archify determines which validation rules to apply by reading a mandatory `schema_version` field from the JSON-IR workflow definition, automatically migrating legacy version 1 diagrams to version 2 while maintaining full backward compatibility through version-agnostic rendering pipelines.**

Archify, an open-source diagramming framework maintained at `tt-a1i/archify`, defines workflow diagrams using a JSON-IR format that explicitly declares its schema version. This declarative approach ensures that every diagram is validated against the correct specification and can be seamlessly upgraded as the format evolves without breaking existing visualizations.

## Schema Version Declaration and Defaults

Every Archify workflow diagram must include a `schema_version` field that tells the validator which version of the workflow schema the diagram conforms to. According to [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) (lines 16‑20), the schema enumerates two supported values: `1` and `2`.

When a diagram is authored without an explicit version, Archify assumes `schema_version: 1`. All historic examples in the repository default to version 1, ensuring that legacy diagrams remain valid without modification.

### Version 1 Workflow Example

The following JSON represents a basic version 1 workflow diagram. Note that while the field can be omitted, explicit declaration is recommended for clarity:

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Deploy Pipeline" },
  "lanes": [{ "id": "dev", "label": "Development" }],
  "nodes": [{ "id": "build", "label": "Build", "lane": "dev" }],
  "edges": [{ "from": "build", "to": "test" }]
}

```

### Version 2 Workflow Example

Version 2 extends the metadata structure while maintaining core compatibility. The `schema_version` field is explicitly set to `2`:

```json
{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": { "title": "Deploy Pipeline", "subtitle": "v2 format" },
  "lanes": [{ "id": "dev", "label": "Development" }],
  "nodes": [{ "id": "build", "label": "Build", "lane": "dev" }],
  "edges": [{ "from": "build", "to": "test" }]
}

```

## Automatic Migration from Version 1 to Version 2

Archify ships with a built-in migration script located at `archify/migrations/workflow-v2.mjs` that programmatically upgrades version 1 payloads to version 2 format. The transformation handles structural changes between schemas while preserving all visual and semantic data.

The CLI automatically invokes this migration when a diagram is loaded with the `--to-schema 2` flag, or when the validator encounters a version 1 payload and the user requests a newer schema:

```bash

# Automatically migrate a v1 diagram to v2

node archify/bin/archify.mjs migrate workflow diagram-v1.json --to-schema 2 --json

```

This ensures that users can convert legacy diagrams without manual JSON manipulation.

## AJV Validation and Error Handling

Before any rendering occurs, Archify validates the incoming JSON against the appropriate schema using **AJV** (Another JSON Schema Validator). The validator checks that the `schema_version` field is present and matches one of the enumerated values defined in [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json).

If the `schema_version` value is missing or specifies an unsupported version, the validator yields a schema-validation error with the precise diagnostic code `schema/additionalProperties`. This strict validation guarantees that only supported versions are processed by the rendering pipeline.

To validate a diagram without rendering, use the CLI:

```bash

# Validate a diagram (the validator picks the correct schema based on schema_version)

node archify/bin/archify.mjs validate workflow diagram.json --json

```

## Backward Compatibility and Testing Strategy

Older diagrams using schema version 1 continue to function because the migration script can be invoked retroactively, and the core rendering pipeline is **version-agnostic** once the JSON has been normalized to the target schema.

The repository includes comprehensive test coverage in `archify/test/v1-compatibility.test.mjs` to ensure that both schema versions produce identical visual output after migration. This test suite validates that the migration script preserves lane configurations, node positions, and edge relationships across versions.

## Summary

- **Schema Detection**: Archify reads the `schema_version` field (values `1` or `2`) from [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) to determine validation rules.
- **Default Behavior**: When omitted, `schema_version` defaults to `1` for backward compatibility with historic diagrams.
- **Automated Migration**: The `workflow-v2.mjs` script transforms version 1 diagrams to version 2 via the `--to-schema 2` CLI flag.
- **Strict Validation**: AJV validates against the declared version, returning `schema/additionalProperties` errors for unsupported versions.
- **Version-Agnostic Rendering**: The rendering pipeline normalizes diagrams to a common format, ensuring forward compatibility through `v1-compatibility.test.mjs`.

## Frequently Asked Questions

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

Archify defaults to version 1 when the `schema_version` field is missing. This ensures that all historic diagrams in the repository remain valid without requiring manual updates, while still allowing explicit version declaration for newer features.

### How do I migrate an existing version 1 diagram to version 2 in Archify?

Invoke the built-in migration via the CLI using the command `node archify/bin/archify.mjs migrate workflow diagram-v1.json --to-schema 2 --json`. This executes `archify/migrations/workflow-v2.mjs` to transform the JSON structure while preserving all visual elements.

### What validation error occurs if I specify an unsupported schema version?

The AJV validator returns a `schema/additionalProperties` error code when the `schema_version` field contains a value outside the enumerated set (`1` or `2`). This prevents processing of malformed or future-version diagrams that the current engine cannot render.

### Are version 1 diagrams still supported in the latest Archify release?

Yes. Version 1 diagrams remain fully supported through automatic retroactive migration and version-agnostic rendering pipelines. The test suite in `archify/test/v1-compatibility.test.mjs` continuously verifies that version 1 payloads render identically to their migrated version 2 counterparts.