# What Are the semanticChecks Available for Archify Workflow Diagrams? A Complete Guide to Structural Validation

> Discover Archify's semanticChecks: allowedRoots, allowedTerminals, requiredEdges, and requiredPaths. Enforce structural constraints on your workflow diagrams at compile time. Learn more now.

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

---

**Archify provides four `semanticChecks`—`allowedRoots`, `allowedTerminals`, `requiredEdges`, and `requiredPaths`—that enforce structural constraints on workflow diagrams at compile time.**

The `semanticChecks` section in an Archify workflow JSON definition encodes architectural constraints that the compiler validates during the build process. These checks ensure that nodes, edges, and paths conform to intended design patterns before rendering. According to the tt-a1i/archify source code, these validations occur in `archify/renderers/workflow/workflow-compiler.mjs` and prevent common structural errors like orphaned nodes or missing required connections.

## The Four semanticChecks Available in Archify

Archify supports four distinct structural validations within the `semanticChecks` object. Each check targets specific graph topology requirements and generates diagnostic errors when constraints are violated.

### allowedRoots

The **`allowedRoots`** check declares which node IDs may appear without incoming edges. In `workflow-compiler.mjs` (lines 639-693), the compiler identifies all nodes lacking inbound edges and validates them against this whitelist. Any orphan node not listed in `allowedRoots` triggers a compilation error.

This check is essential for enforcing entry-point constraints in workflows where specific nodes must serve as the graph origin.

### allowedTerminals

The **`allowedTerminals`** check specifies node IDs that may appear without outgoing edges. The compiler validates nodes lacking outbound edges against this list in `workflow-compiler.mjs` (lines 694-709).

Use this constraint to designate valid exit points in your workflow diagrams and prevent accidental dangling nodes that should connect to downstream processes.

### requiredEdges

The **`requiredEdges`** check mandates the existence of specific source-target pairs. The compiler asserts the presence of each listed edge in `workflow-compiler.mjs` (lines 720-735).

This validation ensures critical connections—such as mandatory handoffs between processing stages—exist in the diagram definition.

### requiredPaths

The **`requiredPaths`** check demands that a directed path exists from a given source to a given target, regardless of intermediate hops. The compiler runs reachability analysis for each entry in `workflow-compiler.mjs` (lines 746-756).

Unlike `requiredEdges`, this check validates connectivity semantics without restricting the specific route taken through the graph.

## Where semanticChecks Are Implemented

The validation logic for `semanticChecks` resides in **`archify/renderers/workflow/workflow-compiler.mjs`**, specifically between lines 639 and 756. The compiler extracts the checks from `workflow.semanticChecks` and builds diagnostics for each violation case.

The JSON Schema defining the `semanticChecks` object structure is located in **[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)**.

Test coverage demonstrating each semantic rule—including rejection of undeclared roots and missing required edges—is available in **`archify/test/workflow-semantic-contract.test.mjs`**.

## Configuring semanticChecks in Your Workflow

To enable structural validation, add a `semanticChecks` object to your workflow diagram's JSON definition. The following example demonstrates all four checks:

```json
{
  "diagram_type": "workflow",
  "semanticChecks": {
    "allowedRoots": ["start"],
    "allowedTerminals": ["end"],
    "requiredEdges": [
      { "from": "start", "to": "processA" },
      { "from": "processB", "to": "end" }
    ],
    "requiredPaths": [
      { "from": "start", "to": "end" }
    ]
  },
  "nodes": [
    { "id": "start", "type": "start" },
    { "id": "processA", "type": "process" },
    { "id": "processB", "type": "process" },
    { "id": "end", "type": "end" }
  ],
  "edges": [
    { "from": "start", "to": "processA" },
    { "from": "processA", "to": "processB" },
    { "from": "processB", "to": "end" }
  ]
}

```

In this configuration:

- `start` is permitted to have no incoming edges.
- `end` can appear without outgoing edges.
- The exact edges `start → processA` and `processB → end` must be present.
- At least one directed path must exist from `start` to `end` (the compiler traces intermediate hops).

## Summary

- Archify workflow diagrams support four `semanticChecks` that validate graph structure at compile time.
- **`allowedRoots`** controls which nodes may lack incoming edges (lines 639-693 of `workflow-compiler.mjs`).
- **`allowedTerminals`** controls which nodes may lack outgoing edges (lines 694-709).
- **`requiredEdges`** enforces mandatory direct connections between specific nodes (lines 720-735).
- **`requiredPaths`** ensures reachability between designated source and target nodes (lines 746-756).
- The `semanticChecks` section is optional, but including it provides early validation of architectural intent and prevents structural bugs.

## Frequently Asked Questions

### What happens if a workflow violates a semanticCheck?

The compiler generates a diagnostic error specifying the offending node, edge, or path along with a helpful suggestion for fixing the diagram. The build fails until all constraints in `semanticChecks` are satisfied.

### Are semanticChecks required for all Archify workflow diagrams?

No. The `semanticChecks` section is optional. Workflow diagrams function without it, but omitting these validations removes compile-time safeguards against orphans, missing edges, and connectivity gaps.

### How do requiredPaths differ from requiredEdges?

**`requiredEdges`** mandates specific direct connections between two nodes, while **`requiredPaths`** only requires that some directed route exists between a source and target, allowing any number of intermediate hops. Use `requiredEdges` for mandatory direct handoffs and `requiredPaths` for high-level connectivity requirements.

### Where can I find the schema definition for semanticChecks?

The JSON Schema defining the `semanticChecks` object structure is located in **[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)** in the tt-a1i/archify repository. This schema validates the syntax of your `semanticChecks` configuration before the compiler applies semantic rules.