How Archify Handles Schema Versions for Workflow Diagrams

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

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

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

# 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.

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:

# 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 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.

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