Schema for Archify Architecture Diagrams: Structure, Validation, and Examples

The schema for Archify architecture diagrams is defined in the JSON Schema file archify/schemas/architecture.schema.json, which specifies required top-level fields including schema_version, diagram_type, meta, and components, and references shared type definitions from common.schema.json.

The tt-a1i/archify repository provides a structured format for defining architecture diagrams as code. Understanding the schema for Archify architecture diagrams is essential for creating valid diagrams that can be rendered and validated by the toolchain. This schema ensures consistency across diagram definitions by enforcing strict typing for components, connections, layouts, and metadata.

Schema Location and Core Structure

The definitive schema resides in archify/schemas/architecture.schema.json within the repository. This file serves as the single source of truth for what constitutes a valid architecture diagram in the Archify ecosystem.

Primary Schema File

The architecture.schema.json file defines the required top-level fields and allowed properties for each diagram. According to the tt-a1i/archify source code, every valid architecture diagram must include schema_version, diagram_type, meta, and components at the root level. The schema also specifies optional constructs for connections between components, layout boundaries, and diagram-specific visual attributes.

Shared Type Definitions

Rather than duplicating type definitions, the architecture schema references archify/schemas/common.schema.json. This shared file provides reusable types including:

• id – Unique identifier format for components
• point – Coordinate definitions for positioning
• componentType – Enumerated types of architectural elements
• variant – Styling and display variants

This modular approach ensures that type definitions remain consistent across different diagram formats in the project.

Required Fields and Diagram Structure

A valid Archify architecture diagram must conform to the following structure as defined in the schema:

• schema_version – Integer identifying the schema revision (currently version 1)
• diagram_type – Must be set to "architecture" for this schema
• meta – Object containing metadata such as title, description, and author
• components – Array of component objects, each requiring an id, type, and label

Additional optional fields include connections for defining relationships between components, boundaries for grouping elements, and layout options for controlling visual presentation.

Validating Architecture Diagrams

You can validate diagram files against the schema using JavaScript validation libraries, direct schema references, or the built-in Archify CLI.

Programmatic Validation with AJV

For Node.js applications, use the ajv library to compile and validate against the schema:

import fs from 'fs';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

// Load schema
const schema = JSON.parse(
  fs.readFileSync(
    new URL('../archify/schemas/architecture.schema.json', import.meta.url),
    'utf8'
  )
);

// initialise validator
const ajv = new Ajv({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(schema);

// Example diagram JSON (a minimal valid architecture diagram)
const diagram = {
  schema_version: 1,
  diagram_type: 'architecture',
  meta: { title: 'Sample Architecture' },
  components: [{ id: 'svc-1', type: 'service', label: 'Service 1' }]
};

// Validate
const valid = validate(diagram);
if (!valid) console.error(validate.errors);
else console.log('Diagram is valid!');

Schema References in Diagram Files

You can reference the schema directly within your JSON diagram files using the $schema property:

{
  "$schema": "https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json",
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "My System" },
  "components": [
    {
      "id": "db",
      "type": "database",
      "label": "PostgreSQL"
    }
  ]
}

CLI Validation

The Archify CLI provides built-in validation against the official schema:

# Assuming the CLI is installed globally

archify validate --schema archify/schemas/architecture.schema.json \
                  --input examples/archify-repo.architecture.json

Related Schema Files

The archify/schemas/ directory contains additional schemas for different diagram types. While architecture.schema.json handles system architecture diagrams, the repository also includes:

• workflow.schema.json – Schema for workflow and process diagrams
• sequence.schema.json – Schema for sequence diagrams
• lifecycle.schema.json – Schema for component lifecycle diagrams
• dataflow.schema.json – Schema for data flow diagrams

Each of these schemas extends the base definitions found in common.schema.json, maintaining type consistency across the entire Archify diagram ecosystem.

Summary

• The schema for Archify architecture diagrams is located at archify/schemas/architecture.schema.json in the tt-a1i/archify repository.
• Required fields include schema_version, diagram_type, meta, and components.
• The schema references common.schema.json for shared types like id, point, and componentType.
• Validation can be performed programmatically using AJV, via the $schema reference in JSON files, or through the archify validate CLI command.

Frequently Asked Questions

Where is the schema for Archify architecture diagrams located?

The schema resides at archify/schemas/architecture.schema.json in the repository root. This file defines the complete JSON Schema specification for architecture diagrams, including all required fields, component properties, and validation rules used by the Archify toolchain.

What are the required fields in an Archify architecture diagram?

Every architecture diagram must include four top-level fields: schema_version (integer), diagram_type (set to "architecture"), meta (object containing at minimum a title), and components (array of component objects). Each component within the array must have an id, type, and label property.

How do I validate an architecture diagram against the schema?

You can validate diagrams using three methods: programmatically with the AJV library in Node.js by compiling architecture.schema.json, by including the "$schema" reference in your JSON file pointing to the schema URL, or by running the command archify validate --schema archify/schemas/architecture.schema.json --input <your-file>.json in the terminal.

What is the relationship between architecture.schema.json and common.schema.json?

The architecture.schema.json file references common.schema.json for reusable type definitions. This includes fundamental types like id for unique identifiers, point for coordinates, componentType for element classifications, and variant for styling options. This shared approach ensures that type definitions remain synchronized across all diagram schemas in the Archify project.

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