# What Optional Semantic Checks Are Available for Archify Workflow Diagrams

> Discover optional semantic checks for Archify workflow diagrams like allowedRoots and requiredPaths. Enforce structural contracts at compile time for robust graph design.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`."*

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

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

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

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

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

```bash
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:

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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json).