Schema Differences Between Archify's JSON IR Types and Validation Methods

Archify defines five distinct JSON Intermediate Representation (IR) types—architecture, workflow, sequence, lifecycle, and dataflow—each with unique required properties and type-specific collections, validated at runtime through pre-compiled Ajv validators generated from JSON Schema files in archify/schemas/.

Archify is an open-source diagramming engine (tt-a1i/archify) that stores all diagrams as JSON Intermediate Representations (IR). Understanding the schema differences between Archify's JSON IR types and their validation pipeline is essential for generating valid diagram inputs and debugging schema violations.

The Five Archify JSON IR Types

Archify supports five diagram types, each governed by its own JSON Schema file under archify/schemas/. While all share common definitions from common.schema.json, they diverge in their top-level required properties and type-specific collections.

Architecture IR

The architecture IR represents system component diagrams and requires the most diverse set of collections beyond core components.

• Constant diagram_type: "architecture"
• Required properties: schema_version, diagram_type, meta, components
• Type-specific collections: layout, boundaries, connections, cards

This schema is defined in archify/schemas/architecture.schema.json.

Workflow IR

The workflow IR models process flows using swim lanes and directed edges between nodes.

• Constant diagram_type: "workflow"
• Required properties: schema_version, diagram_type, meta, lanes, nodes, edges
• Type-specific collections: phases, groups, mainPath, cards

Defined in archify/schemas/workflow.schema.json.

Sequence IR

The sequence IR captures interaction sequences between participants with temporal ordering.

• Constant diagram_type: "sequence"
• Required properties: schema_version, diagram_type, meta, participants, messages
• Type-specific collections: segments, activations, cards

Defined in archify/schemas/sequence.schema.json.

Lifecycle IR

The lifecycle IR represents state machines with states and transitions organized in lanes.

• Constant diagram_type: "lifecycle"
• Required properties: schema_version, diagram_type, meta, lanes, states, transitions
• Type-specific collections: cards (minimal compared to other types)

Defined in archify/schemas/lifecycle.schema.json.

Dataflow IR

The dataflow IR tracks data movement through processing stages with nodes and directional flows.

• Constant diagram_type: "dataflow"
• Required properties: schema_version, diagram_type, meta, stages, nodes, flows
• Type-specific collections: cards

Defined in archify/schemas/dataflow.schema.json.

Shared Schema Foundations

All five schemas reference archify/schemas/common.schema.json for reusable definitions. This shared file defines $defs for id, point, componentType, variant, legendMode, legendEntry, guidedViews, and cards that each specific schema imports via $ref.

Every IR type requires:

• schema_version — always set to 1 (enforced by a const constraint in each schema)
• meta — containing at minimum a title, with optional fields for subtitle, output, animation, visual_preset, quality_profile, views, legend, and viewBox

JSON Schema Validation Workflow

Archify employs a two-phase validation strategy: build-time compilation and runtime execution.

Validator Generation

Standalone validators are generated at build time by scripts/generate-validators.mjs. This script loads each schema using Ajv 2020 with strict: true and emits a single ES module at renderers/shared/generated-validators.mjs.

npm run generate:validators

The generated module contains pre-compiled validator functions for all five diagram types, eliminating runtime schema compilation overhead.

Runtime Validation

The module renderers/shared/validator.mjs imports these generated validators and exposes validateSchema(diagramType, data). If validation fails, the module transforms Ajv errors into diagnostic objects that include:

• The JSON pointer path
• The nearest id or label for context
• A DiagnosticError with actionable fixes

For example, a missing required property error transforms from:

/components/0/type is missing required property "type"

To:

/components/0 (id/label: "frontend") type is missing required property "type"

CLI Usage

The archify command provides direct access to the validation engine:

# Standard validation (exits non-zero on failure)

archify validate architecture path/to/diagram.json

# JSON output for tooling integration

archify validate workflow diagram.json --json

Degraded Mode

If ajv is not installed, the renderer enters degraded mode: it skips schema validation but continues with layout checks, emitting a warning rather than failing. This ensures HTML generation never crashes, even with malformed input.

Practical Validation Examples

Minimal Architecture IR

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "My System" },
  "components": [
    {
      "id": "frontend",
      "type": "frontend",
      "label": "Web UI",
      "row": 0,
      "col": 0
    }
  ],
  "connections": []
}

Validate via CLI:

archify validate architecture my-arch.json

# → exits 0 (no output)

Minimal Workflow IR

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Order Flow" },
  "lanes": [{ "id": "order", "label": "Order" }],
  "nodes": [
    { "id": "receive", "lane": "order", "col": 0, "type": "frontend", "label": "Receive" }
  ],
  "edges": []
}

Programmatic Validation (Node.js)

import { validateSchema } from './archify/renderers/shared/validator.mjs';
import fs from 'node:fs';

const data = JSON.parse(fs.readFileSync('my-dataflow.json', 'utf8'));

try {
  validateSchema('dataflow', data);
  console.log('✅ dataflow IR is valid');
} catch (err) {
  console.error('❌ validation failed:', err.message);
}

When validation fails, the error object includes:

• code: "schema/required"
• subject.path: "/components/0/type"
• subject.identity: "frontend"
• supportedFixes: ["add required property \"type\""]

Summary

• Five distinct IR types—architecture, workflow, sequence, lifecycle, and dataflow—each enforce unique required properties and type-specific collections.
• Shared foundations in common.schema.json provide reusable definitions for identifiers, points, and component types across all schemas.
• Build-time generation via scripts/generate-validators.mjs pre-compiles Ajv validators for runtime performance.
• Diagnostic errors in renderers/shared/validator.mjs annotate validation failures with JSON pointers and nearest identifiers for rapid debugging.
• CLI and programmatic APIs support both manual validation and automated tooling integration.
• Degraded mode ensures rendering resilience when validation dependencies are unavailable.

Frequently Asked Questions

What differentiates Architecture IR from Workflow IR in Archify's JSON schemas?

Architecture IR focuses on static system structure with components, connections, and boundaries, while Workflow IR models dynamic processes using lanes, nodes, and edges with additional collections like phases and mainPath. The Architecture schema requires only components at minimum, whereas Workflow requires lanes, nodes, and edges simultaneously.

How does Archify validate diagrams if Ajv is not installed?

According to the source code in renderers/shared/validator.mjs, when ajv is unavailable the system enters degraded mode: it skips schema validation but continues with layout calculations, emitting a console warning instead of throwing a DiagnosticError. This ensures the renderer always produces output even with potentially invalid input.

Can I validate Archify IR files programmatically without using the CLI?

Yes. Import validateSchema from archify/renderers/shared/validator.mjs and call it with the diagram type string and parsed JSON data. The function throws a DiagnosticError on first schema violation or returns silently on success, making it suitable for integration testing and build pipelines.

What is the role of common.schema.json in Archify's validation system?

archify/schemas/common.schema.json serves as the shared vocabulary for all IR types, defining $defs for reusable concepts like id, point, componentType, and legendEntry. All specific schemas (architecture, workflow, etc.) reference these definitions using $ref, ensuring consistent data types and validation rules across the entire JSON IR ecosystem.

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