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

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.

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:

{
  "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 in the tt-a1i/archify repository. This schema validates the syntax of your semanticChecks configuration before the compiler applies semantic rules.

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