What Are the Semantic Checks Performed on Archify Workflows? A Complete Guide

Archify workflows support four semantic checks—allowedRoots, allowedTerminals, requiredEdges, and requiredPaths—that validate structural constraints beyond JSON syntax, ensuring diagrams contain valid entry points, exit points, mandatory connections, and reachable paths.

The tt-a1i/archify project enables developers to define workflow diagrams using JSON documents that conform to a strict schema. While basic validation ensures syntactic correctness, the semantic checks performed on Archify workflows enforce deeper structural integrity by verifying that nodes follow specific connectivity rules before the renderer generates the SVG output.

Overview of Semantic Validation in Archify

Archify extends beyond standard JSON Schema validation by providing an optional semanticChecks object at the top level of workflow documents. According to the schema definition in archify/schemas/workflow.schema.json (lines 24-53), these checks allow developers to declare constraints that the renderer evaluates when loading a workflow. Violations cause the diagram to be rejected or highlighted as invalid, preventing malformed workflows from reaching production visualization.

The Four Core Semantic Checks

Archify implements four distinct validation mechanisms that control how nodes relate to one another within the directed graph structure.

allowedRoots (Entry Point Validation)

The allowedRoots check restricts which node IDs may serve as root nodes—those with no incoming edges. When specified in the semanticChecks object, every node lacking predecessors must appear in this list; otherwise, the renderer raises a validation error. If the property is omitted, any node may function as a root.

allowedTerminals (Exit Point Validation)

Similarly, allowedTerminals controls which nodes may terminate the workflow by having no outgoing edges. This ensures that only designated sink nodes conclude the process flow, preventing accidental dead ends in critical paths. Every terminal node in the diagram must appear in this array when the check is specified.

requiredEdges (Mandatory Direct Connections)

The requiredEdges array contains objects specifying { "from": <id>, "to": <id> } pairs that must exist as direct edges in the diagram. The renderer performs exact matching on edge endpoints, failing validation if any mandatory connection is absent. This check enforces immediate adjacency between specific workflow stages.

requiredPaths (Reachability Validation)

Unlike requiredEdges, which demands direct adjacency, requiredPaths validates that a directed path exists between two nodes, traversing one or more intermediate edges. The implementation performs graph traversal (depth-first or breadth-first) starting from the from node to verify that the to node is reachable. This ensures logical flow without requiring direct connections between distant nodes.

How Archify Applies Semantic Validation

The validation sequence executes in three phases when the viewer loads a workflow JSON:

1. Root and Terminal Analysis – The renderer computes sets of nodes with zero incoming edges (roots) and zero outgoing edges (terminals), validating them against allowedRoots and allowedTerminals if present.

2. Edge Existence Verification – For each entry in requiredEdges, the system searches for an exact edge match. Missing edges trigger immediate validation failure.

3. Path Traversal – For each requiredPaths entry, the viewer executes reachability analysis. If the target node is unreachable from the source, the workflow is flagged as invalid.

This logic resides in the viewer implementation, particularly within viewer/semantic-lens.js and the validation triggers in viewer/viewer-camera.js, which coordinate the semantic validation before SVG generation.

Practical Configuration Examples

Below are concrete implementations demonstrating how to configure these constraints in workflow documents.

Example 1: Comprehensive Semantic Validation

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": { "title": "Sample Pipeline" },
  "lanes": [{ "id": "l1", "label": "Backend" }],
  "nodes": [
    { "id": "src", "lane": "l1", "col": 0, "type": "source", "label": "Source" },
    { "id": "proc", "lane": "l1", "col": 1, "type": "process", "label": "Processor" },
    { "id": "dst",  "lane": "l1", "col": 2, "type": "sink",   "label": "Destination" }
  ],
  "edges": [
    { "from": "src", "to": "proc", "role": "main" },
    { "from": "proc", "to": "dst",  "role": "main" }
  ],
  "semanticChecks": {
    "allowedRoots":   ["src"],
    "allowedTerminals": ["dst"],
    "requiredEdges": [{ "from": "src", "to": "proc" }],
    "requiredPaths": [{ "from": "src", "to": "dst" }]
  }
}

This configuration enforces that:

• Only src may be a root node (allowedRoots)
• Only dst may be a terminal node (allowedTerminals)
• The edge src → proc must exist directly (requiredEdges)
• A complete path must exist from src to dst (requiredPaths)

Example 2: Enforcing Critical Infrastructure Links

{
  "semanticChecks": {
    "requiredEdges": [
      { "from": "auth", "to": "api" },
      { "from": "api",  "to": "db" }
    ]
  }
}

This pattern ensures that authentication flows invariably connect to the API layer, which in turn connects to the database, preventing orphan nodes in security-critical paths.

Example 3: Singleton Gateway Pattern

{
  "semanticChecks": {
    "allowedRoots": ["gateway"]
  }
}

Even if the graph topology permits multiple entry points, this constraint restricts valid workflows to those where gateway is the sole root node.

Key Implementation Files

The semantic validation system spans both schema definitions and viewer logic:

• archify/schemas/workflow.schema.json – Defines the JSON Schema structure for semanticChecks and its sub-properties (lines 24-53), establishing the valid syntax for constraint declarations.

• viewer/semantic-lens.js – Implements the interactive Semantic Lens UI, reading semanticChecks configurations and visualizing violations within the diagram canvas.

• viewer/viewer-camera.js – Handles mode switching logic that triggers semantic validation routines before rendering operations commence.

• archify/package.json – Declares runtime dependencies for validation libraries that enforce schema constraints during the build and runtime processes.

Summary

• Archify workflows support four semantic checks defined in the semanticChecks object: allowedRoots, allowedTerminals, requiredEdges, and requiredPaths.
• These checks validate structural correctness beyond JSON syntax, controlling entry points, exit points, mandatory connections, and node reachability.
• Validation occurs in the viewer layer (viewer/semantic-lens.js) before SVG rendering, rejecting workflows that violate declared constraints.
• The schema definition in archify/schemas/workflow.schema.json (lines 24-53) provides the formal specification for these constraints.

Frequently Asked Questions

What happens when a semantic check fails in Archify?

When the renderer detects a violation—such as an unauthorized root node or a missing required edge—it rejects the diagram and typically highlights the offending elements through the Semantic Lens interface. The workflow will not render until the JSON is corrected to satisfy all constraints declared in the semanticChecks object.

Can multiple semantic checks be combined in a single workflow?

Yes. The semanticChecks object accepts any combination of allowedRoots, allowedTerminals, requiredEdges, and requiredPaths simultaneously. The renderer evaluates all present constraints, and the workflow must satisfy every declared rule to pass validation according to the workflow.schema.json specification.

Where are semantic checks defined in the Archify source code?

The data structure and valid values for semantic checks are defined in archify/schemas/workflow.schema.json at lines 24-53. The implementation logic that executes these checks resides primarily in viewer/semantic-lens.js and the validation triggers within viewer/viewer-camera.js.

Do semantic checks impact Archify rendering performance?

The checks introduce minimal overhead during the initial load phase. Root and terminal validation operate in O(n) time relative to node count, while path reachability uses standard graph traversal algorithms. For most workflow diagrams, this validation completes in milliseconds before SVG generation begins.

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