How to Find the Typed JSON IR Schemas for Different Diagram Types in Archify

Archify stores its typed JSON IR schemas as JSON Schema draft-07 files in the archify/schemas/ directory, with separate schema files defining the structure for architecture, workflow, sequence, lifecycle, and dataflow diagrams.

The tt-a1i/archify repository uses formal JSON Schema definitions to validate its intermediate representation (IR) for diagrams before rendering. These schemas specify required properties, allowed values, and structural constraints for each diagram category, enabling both internal validation and external tool integration.

Schema Location and Structure

All typed JSON IR schemas reside in the archify/schemas/ directory at the repository root. The collection follows the JSON Schema draft-07 specification and provides strict contracts for diagram generation and validation.

The primary schema files include:

• archify/schemas/architecture.schema.json – Defines nodes, edges, and layout constraints for architecture diagrams
• archify/schemas/workflow.schema.json – Specifies stages, actions, and routing logic for workflow diagrams
• archify/schemas/sequence.schema.json – Structures lifelines and message sequences for sequence diagrams
• archify/schemas/lifecycle.schema.json – Captures states and transitions for lifecycle diagrams
• archify/schemas/dataflow.schema.json – Describes sources, sinks, and pipeline structures for dataflow diagrams
• archify/schemas/common.schema.json – Contains shared definitions for component types and labeling reused across all diagram types

Validating Diagram IR Against the Schemas

You can programmatically enforce these typed contracts using standard validation libraries in JavaScript, Python, or via command-line tools.

Node.js Validation with Ajv

Use ajv with the ajv-formats plugin to validate architecture IR files against the schema:

import Ajv from "ajv";
import addFormats from "ajv-formats";
import architectureSchema from "./archify/schemas/architecture.schema.json";
import fs from "fs";

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);               // adds support for `uri`, `date-time`, etc.

const validate = ajv.compile(architectureSchema);

// Load a sample architecture IR (JSON file)
const architectureIR = JSON.parse(
  fs.readFileSync("./examples/web-app.architecture.json", "utf8")
);

if (validate(architectureIR)) {
  console.log("✅ Architecture IR is valid!");
} else {
  console.error("❌ Validation errors:", validate.errors);
}

Python Validation with jsonschema

The jsonschema library can type-check workflow IR files against workflow.schema.json:

import json
import jsonschema
from pathlib import Path

# Load the schema

with open(Path("archify/schemas/workflow.schema.json")) as f:
    workflow_schema = json.load(f)

# Load a workflow IR example

with open(Path("archify/examples/web-app.workflow.json")) as f:
    workflow_ir = json.load(f)

# Perform validation

try:
    jsonschema.validate(instance=workflow_ir, schema=workflow_schema)
    print("✅ Workflow IR is valid")
except jsonschema.ValidationError as err:
    print("❌ Validation error:", err.message)

Command-Line Validation

For quick validation of sequence diagrams without writing code, use the jsonschema CLI:

# Install the CLI (if not already available)

pip install jsonschema

# Validate a sequence diagram JSON file

jsonschema -i archify/examples/async-job-roundtrip.sequence.json \
           archify/schemas/sequence.schema.json

Using Common Definitions

The archify/schemas/common.schema.json file contains reusable definitions imported by other schemas. When extending Archify or building custom validators, reference this file to ensure component types and labeling conventions remain consistent across different diagram categories.

Example files for each diagram type are available in archify/examples/ to serve as reference implementations and test fixtures.

Summary

• Locate schemas in the archify/schemas/ directory, with each diagram type having a dedicated .schema.json file
• Architecture diagrams use architecture.schema.json to define nodes and edges
• Workflow, sequence, lifecycle, and dataflow diagrams each have specific schemas (workflow.schema.json, sequence.schema.json, etc.)
• Common definitions are centralized in common.schema.json for cross-schema consistency
• Validate programmatically using standard libraries like ajv (Node.js) or jsonschema (Python) against the draft-07 schemas
• Example IR files in archify/examples/ demonstrate valid structures for testing

Frequently Asked Questions

Where are the typed JSON IR schemas for Archify diagram types stored?

The schemas are stored in the archify/schemas/ directory of the repository. Each diagram type has its own JSON Schema file (draft-07), such as architecture.schema.json for architecture diagrams and workflow.schema.json for workflow diagrams.

What JSON Schema version does Archify use for its IR definitions?

Archify uses JSON Schema draft-07 for all typed IR definitions. This allows compatibility with standard validation tools like ajv, jsonschema, and various IDE plugins that support schema validation.

Can I validate my diagram JSON against Archify's schemas before rendering?

Yes. You can validate diagram IR programmatically using libraries like ajv in Node.js or jsonschema in Python, or use the jsonschema CLI tool. The schemas enforce required properties and structural constraints to ensure the JSON conforms to Archify's expected format.

What is the purpose of the common.schema.json file?

The common.schema.json file contains shared definitions for component types, labeling conventions, and other reusable structures that are referenced by multiple diagram-specific schemas. It ensures consistency across different diagram types in the Archify system.

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