What Optional Semantic Checks Are Available for Archify Workflow Diagrams

Archify workflow diagrams support four optional semantic checks—allowedRoots, allowedTerminals, requiredEdges, and requiredPaths—that enforce structural contracts on your graph at compile time.

The semantic checks feature in Archify lets you declare structural expectations for workflow diagrams beyond basic schema validation. When you include a semanticChecks object in your workflow definition, the compiler validates the graph against these rules and emits precise diagnostics if any contract is violated. This article covers all four available checks with implementation details from the tt-a1i/archify source code.

Available Semantic Checks

Archify defines four optional checks in archify/schemas/workflow.schema.json (lines 24–53) and enforces them in archify/renderers/workflow/workflow-compiler.mjs (lines 639–746). You can use any subset of these checks.

allowedRoots

allowedRoots whitelists node IDs that are permitted to have no incoming edges (source nodes).

When a node lacks an incoming edge and its ID is not in allowedRoots, Archify reports: "Workflow node X has no incoming edge and is not declared in semanticChecks.allowedRoots."

{
  "semanticChecks": {
    "allowedRoots": ["input", "trigger"]
  }
}

allowedTerminals

allowedTerminals whitelists node IDs that are permitted to have no outgoing edges (sink nodes).

Violations produce: "Workflow node X has no outgoing edge and is not declared in semanticChecks.allowedTerminals."

{
  "semanticChecks": {
    "allowedTerminals": ["output", "complete"]
  }
}

requiredEdges

requiredEdges lists directed edges that must exist in the workflow, specified as { from, to } objects.

Missing edges trigger: "Missing required edge from A → B."

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

requiredPaths

requiredPaths declares directed reachability requirements—the compiler verifies that a path exists through any number of intermediate nodes.

Unreachable paths produce: "Required path from A → B is not reachable in authored direction."

{
  "semanticChecks": {
    "requiredPaths": [
      { "from": "start", "to": "end" }
    ]
  }
}

Complete Workflow Example with Semantic Checks

Here's a minimal workflow demonstrating all four checks as implemented in the Archify source:

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": { "title": "Sample checkout flow" },
  "lanes": [{ "id": "frontend", "label": "Frontend" }],
  "nodes": [
    { "id": "request", "lane": "frontend", "col": 0, "type": "task", "label": "Request" },
    { "id": "service", "lane": "frontend", "col": 1, "type": "task", "label": "Service" }
  ],
  "edges": [{ "from": "request", "to": "service" }],
  "semanticChecks": {
    "allowedRoots": ["request"],
    "allowedTerminals": ["service"],
    "requiredEdges": [{ "from": "request", "to": "service" }],
    "requiredPaths": [{ "from": "request", "to": "service" }]
  }
}

Validating with the Archify CLI

Run semantic validation using the CLI as defined in archify/bin/archify.mjs:

node archify/bin/archify.mjs validate workflow checkout.json --quality showcase --json

The --quality showcase flag enables full semantic checking. With --json, diagnostics include exact JSON Pointer paths (e.g., /semanticChecks/requiredEdges/0) for programmatic processing.

Error Examples

Missing Required Path

Given this semanticChecks configuration:

{
  "semanticChecks": {
    "requiredPaths": [{ "from": "request", "to": "database" }]
  }
}

When no route exists from request to database, the compiler outputs:

Required path from "request" → "database" is not reachable in authored direction.

Undeclared Root Node

Adding a node without incoming edges that isn't in allowedRoots:

{
  "nodes": [
    { "id": "orphan", "lane": "backend", "col": 0, "type": "task" }
  ],
  "semanticChecks": {
    "allowedRoots": ["validStart"]
  }
}

Produces: "Workflow node "orphan" has no incoming edge and is not declared in semanticChecks.allowedRoots."

Key Implementation Files

File	Purpose
archify/schemas/workflow.schema.json	Defines the semanticChecks object structure and sub-properties
archify/renderers/workflow/workflow-compiler.mjs	Compiles workflows and executes semantic validation logic
archify/renderers/workflow/README.md	Documents the workflow renderer including semanticChecks
archify/test/workflow-semantic-contract.test.mjs	Test suite verifying each semantic check
examples/agent-tool-call.workflow.json	Real-world example with optional semantic checks

Summary

• Archify workflow diagrams support four optional semantic checks: allowedRoots, allowedTerminals, requiredEdges, and requiredPaths
• Checks are declared in the semanticChecks object and validated at compile time in workflow-compiler.mjs
• Violations produce precise diagnostics with JSON Pointer paths for tooling integration
• All checks are independent—include only those your workflow architecture requires
• Use archify.mjs validate with --quality showcase to enable full semantic validation

Frequently Asked Questions

What happens if I omit semanticChecks entirely?

Archify performs only baseline schema validation. Your workflow will compile successfully regardless of graph structure, provided it meets the JSON schema requirements in workflow.schema.json.

Can I use semantic checks with other Archify diagram types?

No. According to the source schema, semanticChecks is currently defined only for the workflow diagram type. Other renderers like sequence or block diagrams do not implement this feature.

Do requiredPaths and requiredEdges overlap in functionality?

They serve different purposes. requiredEdges demands specific direct connections, while requiredPaths only requires reachability through any path length. A workflow can satisfy requiredPaths without satisfying requiredEdges if intermediate nodes bridge the gap.

How do I debug semantic check failures?

Run validation with --json to receive structured diagnostics including exact paths. Check archify/test/workflow-semantic-contract.test.mjs for expected behavior patterns and compare your workflow against working examples like examples/agent-tool-call.workflow.json.

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