How JSON IR Schemas Validate Diagram Structure in Archify: A Complete Technical Guide

Archify enforces strict structural validation on every diagram by running JSON Intermediate Representation (IR) through JSON Schema draft 2020-12 using AJV, rejecting any input that violates type constraints or missing required fields before rendering begins.

Archify converts architecture, workflow, sequence, and lifecycle diagrams into JSON Intermediate Representation (IR) documents before visualization. The system validates these payloads against specialized JSON IR schemas to ensure type safety and structural integrity, acting as a fail-closed gatekeeper that prevents malformed data from reaching the rendering pipeline. This schema-first approach guarantees consistent diagram output across all supported diagram types in the tt-a1i/archify repository.

The Validation Pipeline

Archify’s validation process follows a strict sequence that checks every layer of the diagram IR. The system uses AJV (Another JSON Validator) to compile schemas and validate incoming JSON against the specific diagram type being processed.

Schema Selection by Diagram Type

Every diagram must declare its structure upfront in the root object. The schema requires four mandatory fields: schema_version, diagram_type, meta, and a type-specific payload such as components or connections. All schemas set additionalProperties: false to strictly forbid extraneous fields.

In archify/schemas/architecture.schema.json, the root object enforces schema_version locked to integer 1 and diagram_type restricted to specific enum values like "architecture" or "workflow". This guarantees that the validator loads the correct schema file for the specific diagram variant being processed.

Shared Definitions via $ref

Common primitives are defined once in archify/schemas/common.schema.json and referenced across all diagram schemas using JSON Schema’s $ref keyword. This centralizes definitions for:

• id: String identifiers for components and connections
• point: Coordinate arrays for positioning
• componentType: Enumerated node types (frontend, backend, database, etc.)
• legendEntry and guidedViews: UI metadata structures

By referencing these shared definitions, Archify maintains a single source of truth for validation rules while keeping individual schema files focused on diagram-specific logic.

Structural Validation Layers

Each schema validates distinct aspects of the diagram IR, from high-level metadata to low-level connection geometry.

Metadata and View Configuration

The meta block (defined in archify/schemas/architecture.schema.json lines 12-66) validates optional presentation fields including title, subtitle, output format, animation settings, quality profiles, and viewBox dimensions. This ensures that renderers receive consistent configuration objects regardless of the diagram source.

Components, Nodes, and Layouts

Architecture diagrams validate components arrays (lines 82-125 in architecture.schema.json) requiring each element to contain id, type (from the componentType enum), and label. Optional positioning fields like row, col, pos, and size are strictly type-checked against the shared point definition.

Workflow diagrams use similar constraints in archify/schemas/workflow.schema.json (lines 19-68), validating nodes arrays with lane assignments and grid coordinates. Layout objects enforce numeric constraints for origin, cols, gapX, gapY, cellW, and cellH, ensuring grid-based diagrams calculate correct cell boundaries.

Connections and Edge Integrity

Every relationship must reference valid endpoints. In archify/schemas/architecture.schema.json (lines 145-171), the connections array requires from and to properties that must match existing component IDs. Optional routing fields like variant, fromSide, toSide, and via are validated against enumerated values or the shared point array definition.

Workflow schemas implement similar validation for edges (lines 70-108 in workflow.schema.json), checking that from and to reference valid node IDs within the same diagram context.

Validating Diagrams with AJV

Archify implements validation using AJV in Node.js environments. The validator loads the base schema and any referenced common definitions before testing the JSON IR.

import Ajv from "ajv";
import architectureSchema from "./archify/schemas/architecture.schema.json";
import commonSchema from "./archify/schemas/common.schema.json";

const ajv = new Ajv({ allErrors: true });
ajv.addSchema(commonSchema, "common");
const validate = ajv.compile(architectureSchema);

const diagramData = {
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Demo Architecture" },
  "layout": { "mode": "grid", "cols": 4, "gapX": 10, "gapY": 10, "cellW": 80, "cellH": 30 },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "Web UI", "row": 0, "col": 0 },
    { "id": "backend", "type": "backend", "label": "API", "row": 0, "col": 1 }
  ],
  "connections": [
    { "from": "frontend", "to": "backend", "variant": "default" }
  ]
};

const valid = validate(diagramData);
if (!valid) {
  console.error(validate.errors);
} else {
  console.log("Diagram structure validated successfully");
}

For workflow diagrams, substitute workflow.schema.json and adjust the payload structure:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Order Processing" },
  "lanes": [{ "id": "lane1", "label": "Customer" }],
  "nodes": [
    { "id": "n1", "lane": "lane1", "col": 0, "type": "frontend", "label": "Checkout" }
  ],
  "edges": [
    { "from": "n1", "to": "n1", "role": "main", "variant": "default" }
  ]
}

Schema File Reference

Archify organizes validation logic into discrete schema files within the archify/schemas/ directory:

• archify/schemas/common.schema.json: Centralizes shared type definitions including identifiers, coordinate points, enumerations, and card structures referenced via $ref across all diagram types.

• archify/schemas/architecture.schema.json: Defines validation for system architecture diagrams including component grids, connection routing, and boundary enclosures.

• archify/schemas/workflow.schema.json: Validates swimlane-based workflow diagrams with node positioning and edge routing constraints.

• archify/schemas/sequence.schema.json: Enforces message sequence diagrams with lifelines and activation boxes.

• archify/schemas/lifecycle.schema.json: Validates state transition diagrams and lifecycle flows.

• archify/schemas/dataflow.schema.json: Defines schemas for data pipeline and ETL process visualizations.

Summary

• JSON IR schemas in Archify use JSON Schema draft 2020-12 to enforce strict type checking on diagram structures before rendering.
• AJV validation runs as a fail-closed gatekeeper, rejecting any diagram with missing required fields, type mismatches, or undefined component references.
• Shared definitions in common.schema.json eliminate duplication by centralizing primitives like IDs, points, and enums across all diagram-specific schemas.
• Structural constraints ensure that components, connections, nodes, and edges maintain referential integrity and valid geometric properties.
• Schema versioning via schema_version and diagram_type fields enables Archify to evolve its IR format while maintaining backward compatibility validation.

Frequently Asked Questions

What JSON Schema version does Archify use?

Archify implements JSON Schema draft 2020-12 for all IR validation. This modern specification supports advanced features like $ref dereferencing and strict type checking required for the complex nested structures in architecture and workflow diagrams.

How does Archify handle invalid diagram JSON?

When AJV detects validation errors, Archify immediately halts processing and returns a detailed error list specifying which fields failed constraints. This fail-closed approach prevents malformed diagrams from reaching the rendering engine, avoiding runtime visualization errors.

Can I extend the schemas with custom properties?

No, Archify schemas explicitly set additionalProperties: false on root objects and most nested structures. This strictness ensures cross-compatibility between different renderers and prevents undefined behavior from unexpected fields. To add custom metadata, use the extensible meta object or propose changes to the shared definitions in common.schema.json.

What happens if a connection references a non-existent component ID?

The schema validates that from and to properties in connections and edges reference valid IDs defined within the same JSON document. While the JSON Schema enforces string type and format constraints, Archify’s validation layer verifies referential integrity to ensure every connection points to a defined component or node before processing continues.

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