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

> Explore Archify workflow semantic checks like allowedRoots, allowedTerminals, requiredEdges, and requiredPaths. Ensure your diagrams have valid structures and paths with this complete guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js) and the validation triggers in [`viewer/viewer-camera.js`](https://github.com/tt-a1i/archify/blob/main/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

```json
{
  "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

```json
{
  "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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js)** – Implements the interactive Semantic Lens UI, reading `semanticChecks` configurations and visualizing violations within the diagram canvas.

- **[`viewer/viewer-camera.js`](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-camera.js)** – Handles mode switching logic that triggers semantic validation routines before rendering operations commence.

- **[`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js)) before SVG rendering, rejecting workflows that violate declared constraints.
- The schema definition in **[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) at lines 24-53. The implementation logic that executes these checks resides primarily in [`viewer/semantic-lens.js`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js) and the validation triggers within [`viewer/viewer-camera.js`](https://github.com/tt-a1i/archify/blob/main/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.