Archify Typed JSON IR Structure: A Complete Schema Reference

Archify uses a strictly-validated Typed JSON Intermediate Representation (IR) where all diagram types extend a common core schema defined in archify/schemas/common.schema.json with diagram-specific properties.

The Archify code generator (tt-a1i/archify) treats diagrams as structured data rather than visual markup. Every workflow, sequence, data-flow, lifecycle, and architecture diagram compiles to a Typed JSON IR that conforms to machine-readable JSON Schema. This enables deterministic rendering, portable outputs, and reproducible builds across environments.

---

Core IR Definitions in common.schema.json

All diagram schemas inherit shared types from archify/schemas/common.schema.json. These foundational definitions enforce consistency across the entire IR ecosystem.

Primitive Types

Property	Type / Constraints	Purpose
id	string matching ^[a-zA-Z][a-zA-Z0-9_-]*$	Unique identifier referenced throughout the IR
locale	"en" or "zh-CN"	Language for rendered output
animation	"trace" or "none"	Animation behavior for diagram playback
visual_preset	"classic", "signal-flow", "blueprint", or "editorial"	Predefined visual styling theme
quality_profile	"standard" or "showcase"	Output resolution and fidelity
side	"left", "right", "top", "bottom"	Edge routing direction
point	[number, number]	2-D coordinate for waypoints and label placement
componentType	"frontend", "backend", "database", "cloud", "security", "messagebus", "external"	Semantic category for diagram nodes
brandMark	string or {url: string, sha256: string}	Optional branding asset
variant	"default", "emphasis", "security", "dashed"	Visual variation for nodes and edges

Nested Structures

• guidedViews: Array of view descriptors with id, label, and focus properties for guided presentations
• cards: Array of informational cards containing dot color, title, and items for side-panel content
• legendMode, legendEntry: Enums and objects controlling diagram legend behavior

---

Diagram-Specific IR: Workflow Schema

The workflow diagram IR in archify/schemas/workflow.schema.json extends the common core with execution-flow semantics. This is the most extensively documented schema in the Archify source.

Top-Level Workflow Properties

Property	Type	Description
schema_version	1 or 2	Schema compatibility version
diagram_type	"workflow" (constant)	Discriminator for type routing
meta	Object with required title	Human-readable metadata (title, subtitle, locale)
lanes	Array of lane objects	Horizontal swim-lanes grouping nodes by id, label, optional variant
phases	Optional array of phase objects	Column groupings with fromCol, toCol ranges
groups	Optional array of group objects	Visual node clusters within lanes
mainPath	Array of node ids (minimum 2)	Primary execution sequence
semanticChecks	Optional validation rules	allowedRoots, allowedTerminals, requiredEdges, requiredPaths
nodes	Array of node objects	Core diagram elements
edges	Array of edge objects	Connections between nodes
cards	Optional array	Supplemental information (reuses common definition)

Workflow Node Object

{
  "id": "payment-gateway",
  "lane": "backend-services",
  "col": 2,
  "type": "backend",
  "label": "Payment Gateway",
  "sublabel": "Stripe integration",
  "tag": "critical-path",
  "brand": "stripe",
  "width": 64,
  "height": 48,
  "yOffset": 12
}

Required fields: id, lane, col, type, label

Optional visual overrides: sublabel, tag, brand (from brandMark), width (minimum 32), height (minimum 32), yOffset

Workflow Edge Object

{
  "id": "edge-001",
  "from": "payment-gateway",
  "to": "confirmation-email",
  "label": "success",
  "variant": "emphasis",
  "role": "main",
  "fromSide": "right",
  "toSide": "left",
  "route": "auto",
  "via": [[120, 200], [180, 200]],
  "labelAt": [150, 190],
  "labelDx": 0,
  "labelDy": -8,
  "labelSegment": 1,
  "channelX": 150,
  "channelY": 200,
  "bias": 0.3,
  "width": 2.0
}

Semantic role values: main, branch, async, return, error

Routing algorithms: auto, straight, drop, outside-right, return-left, bottom-channel, up-channel

---

Additional Diagram Type Schemas

Archify implements parallel schema structures for other diagram families, each with appropriate diagram_type discriminator:

Diagram Type	Schema File	Key Specialization
Sequence	archify/schemas/sequence.schema.json	Lifelines, activation bars, message numbering
Data-flow	archify/schemas/dataflow.schema.json	Data stores, processes, external entities
Lifecycle	archify/schemas/lifecycle.schema.json	State transitions, phases, milestones
Architecture	archify/schemas/architecture.schema.json	Component hierarchies, deployment boundaries

Each schema reuses common definitions (id, componentType, point, variant) and adds type-specific fields. All enforce additionalProperties: false for strict validation.

---

Minimal Valid Workflow IR Example

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "User Registration Flow"
  },
  "lanes": [
    { "id": "client", "label": "Client App" },
    { "id": "api", "label": "API Layer" },
    { "id": "db", "label": "Database" }
  ],
  "nodes": [
    { "id": "submit", "lane": "client", "col": 0, "type": "frontend", "label": "Submit Form" },
    { "id": "validate", "lane": "api", "col": 1, "type": "backend", "label": "Validate Input" },
    { "id": "create", "lane": "db", "col": 2, "type": "database", "label": "Create Record" }
  ],
  "edges": [
    {
      "from": "submit",
      "to": "validate",
      "role": "main",
      "fromSide": "right",
      "toSide": "left"
    },
    {
      "from": "validate",
      "to": "create",
      "role": "main",
      "fromSide": "right",
      "toSide": "left"
    }
  ],
  "mainPath": ["submit", "validate", "create"]
}

---

Validation and Schema Strictness

According to the Archify source code, every Typed JSON IR undergoes schema validation with these characteristics:

• additionalProperties: false: Rejects unrecognized fields at any level
• required arrays: Explicitly list mandatory properties per object type
• Pattern constraints: id fields must match ^[a-zA-Z][a-zA-Z0-9_-]*$
• Numeric bounds: Visual dimensions enforce minimums (e.g., width ≥ 32)

The semanticChecks object in workflow schemas enables declarative validation beyond structural correctness—specifying allowed root nodes, required terminal nodes, mandatory edges, and obligatory paths through the diagram.

---

Source File Reference

File	Purpose
archify/schemas/common.schema.json	Shared type definitions inherited by all schemas
archify/schemas/workflow.schema.json	Full workflow diagram specification
archify/schemas/sequence.schema.json	Sequence diagram specification
archify/schemas/dataflow.schema.json	Data-flow diagram specification
archify/schemas/lifecycle.schema.json	Lifecycle/state diagram specification
archify/schemas/architecture.schema.json	Architecture/component diagram specification

---

Summary

• Archify's Typed JSON IR unifies all diagram types under a strict, schema-driven JSON structure
• Common definitions in common.schema.json provide reusable primitives: id, componentType, point, variant, brandMark
• Diagram-specific schemas extend the core with specialized fields—workflow IR adds lanes, phases, mainPath, and semanticChecks
• Validation is strict: additionalProperties: false, explicit required fields, and pattern constraints prevent malformed IR
• Five diagram families share the same structural approach: workflow, sequence, data-flow, lifecycle, and architecture

---

Frequently Asked Questions

What makes Archify's IR "typed"?

The "typed" designation refers to JSON Schema validation. Every IR document validates against a strict schema that defines precise types, allowed values, required fields, and constraints. This prevents runtime errors and ensures reproducible rendering across different environments and Archify versions.

Can I extend the Typed JSON IR with custom properties?

No. Archify schemas enforce additionalProperties: false, which rejects any fields not explicitly defined in the schema. This strictness guarantees forward compatibility and consistent rendering. Custom data should be stored in extensible fields like meta or conveyed through tag strings where permitted.

How does the diagram_type field affect processing?

The diagram_type constant ("workflow", "sequence", etc.) acts as a discriminator that routes the IR to the appropriate validator and renderer. According to the source schemas, this field is required at the top level and must match the schema file being used for validation.

What is the difference between lanes and phases in workflow IR?

Lanes are vertical or horizontal groupings that organize nodes by responsible party or system component (swim-lane semantics). Phases are logical column ranges that span across lanes, enabling timeline or stage-based visualization. A node belongs to exactly one lane but may fall within a phase range.

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