Key Fields for Archify Architecture Diagrams: A Complete Schema Guide

Archify architecture diagrams require three mandatory root fields—schema_version, diagram_type, and meta—plus a components array, with optional objects for layout, boundaries, connections, and cards that together define a strictly validated JSON structure.

The tt-a1i/archify repository defines architecture diagrams through a rigid JSON schema that enforces deterministic rendering and versioning. Understanding the key fields for Archify architecture diagrams ensures your infrastructure visualizations validate correctly against the architecture.schema.json specification and render predictably across different environments.

Required Root Fields

Every architecture diagram must include four top-level keys. According to the schema defined in archify/schemas/architecture.schema.json, these fields form the immutable foundation of the document.

schema_version

The schema_version field is a constant integer set to 1. This field enables future versioning of the Archify specification while maintaining backward compatibility for existing diagrams.

diagram_type

This field must contain the string "architecture" to distinguish infrastructure diagrams from other diagram types supported by the Archify ecosystem. The value is strictly enforced by the schema enum definition.

meta

The meta object stores human-readable metadata and rendering controls. It requires at least one sub-field:

• title (required): The display name of the diagram
• locale: Language and region settings
• subtitle: Descriptive text displayed beneath the title
• output: Target format specifications
• animation: Playback controls for generated visuals
• visual_preset: Predefined styling profiles
• quality_profile: Rendering fidelity settings
• engineering_profile: Technical detail density controls
• repository: Object containing url and revision for source linking
• views: Alternative display configurations
• legend: Object with mode and entries for diagram keys
• viewBox: Coordinate system boundaries for the canvas

components

The components array contains the visual elements of your architecture. Each component object requires three fields:

• id: Unique identifier referenced by connections and boundaries
• type: Visual category defined in archify/schemas/common.schema.json (frontend, backend, database, cloud, security, messagebus, or external)
• label: Display text for the node

Optional component fields include sublabel, tag, brand, sources, row, col, pos, and size. These types drive visual styling such as icon selection and color coding.

Optional Structural Fields

Beyond the required root objects, Archify supports four optional arrays that control layout, grouping, relationships, and documentation.

layout

The layout object controls grid-based positioning with fields including mode (typically "grid"), origin coordinates, cols count, gapX and gapY spacing, plus cellW and cellH dimensions. When omitted, Archify applies automatic layout algorithms.

boundaries

Boundaries group components into visual regions or security zones. Each boundary entry requires:

• kind: Classification of the grouping
• label: Display name for the region
• wraps: Array of component id strings contained within the boundary

connections

The connections array defines directed edges between components. Required fields are from and to, both referencing component id values. Optional routing and styling fields include:

• label: Text displayed on the edge
• variant: Visual style (default, emphasis, security, or dashed)
• fromSide and toSide: Connection attachment points
• route: Path algorithm (auto, straight, orthogonal-h, orthogonal-v)
• via: Intermediate waypoints
• labelAt, labelDx, labelDy, labelSegment: Label positioning controls
• width: Line thickness

cards

The cards array attaches informational callouts to the diagram. These objects follow definitions imported from common.schema.json and support rich text content without affecting the core component graph.

Schema Validation and Constraints

Archify enforces strict validation through JSON Schema constraints. The architecture.schema.json explicitly sets "additionalProperties": false at multiple levels, preventing typos and unsupported fields from passing validation. This strict mode ensures that every diagram adheres to a predictable structure compatible with the rendering engine.

Component types are validated against the componentType enum defined in archify/schemas/common.schema.json. This centralization allows the Archify team to add new visual categories—such as ai or iot—in future schema versions while maintaining type safety.

Practical Implementation

Below is a minimal valid architecture diagram illustrating a three-tier web application:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Simple Web App",
    "subtitle": "Frontend ↔ Backend ↔ Database"
  },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "React UI" },
    { "id": "backend", "type": "backend", "label": "Node API" },
    { "id": "db", "type": "database", "label": "PostgreSQL" }
  ],
  "connections": [
    { "from": "frontend", "to": "backend", "variant": "default" },
    { "from": "backend", "to": "db", "variant": "default" }
  ]
}

For comprehensive examples, reference examples/archify-repo.architecture.json in the repository, which demonstrates advanced usage of meta controls, layout grids, boundaries, and connection routing. Test fixtures located at archify/test/fixtures/v1-baseline/web-app.architecture.json provide additional validation examples used by the Archify test suite.

Summary

• Required fields include schema_version (constant 1), diagram_type (fixed to "architecture"), meta (requiring title), and the components array (requiring id, type, and label).
• Optional fields encompass layout for grid control, boundaries for component grouping, connections for relationship edges, and cards for documentation.
• Strict validation via "additionalProperties": false ensures schema compliance and prevents runtime rendering errors.
• Component types are centralized in common.schema.json and drive visual styling through categories like frontend, backend, and security.

Frequently Asked Questions

What is the minimum valid Archify architecture diagram?

A valid diagram requires the schema_version set to 1, diagram_type set to "architecture", a meta object containing at least a title, and a components array with at least one element containing id, type, and label fields. The schema rejects any document missing these required fields or containing undefined properties.

Where are component types like "frontend" and "database" defined?

Component types are defined in the componentType enum within archify/schemas/common.schema.json. This schema imports into architecture.schema.json to validate the type field of each component object. The current allowed values include frontend, backend, database, cloud, security, messagebus, and external.

Can I add custom fields to an Archify diagram?

No. The schema explicitly sets "additionalProperties": false at the root level and within component objects. Any custom fields will cause validation errors. To extend functionality, use the meta object's supported sub-fields (such as repository or engineering_profile) or attach information through the cards array.

How do I control the visual routing of connections between components?

Use the route field within a connection object to specify path algorithms. Valid options include auto (default), straight, orthogonal-h (horizontal-first elbows), and orthogonal-v (vertical-first elbows). Additional positioning controls like fromSide, toSide, and via arrays provide granular control over attachment points and waypoints.

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