# How to Render an Archify Diagram with Validation: Complete Guide

> Learn to render an Archify diagram with validation using the CLI or programmatically. Ensure your diagram is schema-compliant before generating HTML/SVG output. Get the complete guide.

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

---

**Use the Archify CLI with `npx archify render` or call `renderWorkflow()` programmatically to validate your diagram against the workflow schema before generating HTML/SVG output.**

Archify is a declarative, schema-driven tool for authoring, visualising, and validating software-architecture diagrams. When you render an Archify diagram, validation happens automatically before any visual output is produced, ensuring structural integrity and preventing wasted rendering cycles on malformed definitions.

## How Archify's Validation-First Rendering Works

The rendering pipeline in `archify/renderers/workflow` enforces a strict five-step process:

1. **Load the diagram definition** — the JSON or YAML file is read and parsed.
2. **Schema validation** — Archify validates against [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), checking required fields, data types, and relational constraints (unique node IDs, permissible edge directions). Failures throw `SchemaValidationError` with detailed path-based messages.
3. **Create the internal model** — validated definitions become a graph model for the layout engine.
4. **Layout and render** — the model generates responsive HTML/SVG output embeddable in documentation.
5. **Optional post-render checks** — semantic contracts in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) verify "no orphan nodes" and layer ordering constraints.

Because validation precedes all rendering work, you receive immediate feedback without resource waste. The CLI exits non-zero on failure, making CI integration straightforward.

## Render an Archify Diagram Using the CLI

The simplest way to render an Archify diagram with validation is through the command-line interface.

```bash

# Render a diagram and automatically validate it

npx archify render path/to/diagram.architecture.json \
  --output dist/diagram.html

```

Validation errors halt execution with descriptive messages:

```

✖ Validation error: "nodes[3].id" is missing required property "id"

```

The CLI implementation resides in `scripts/run-tests.mjs`, with the rendering entry point documented in [`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md).

### Validate Without Rendering

Use `--dry-run` for pure validation without output generation:

```bash
npx archify render diagram.architecture.json --dry-run

```

This flag enables fast pre-commit or CI validation checks.

## Render an Archify Diagram Programmatically in Node.js

For custom integrations, import `renderWorkflow` from `archify/renderers/workflow`:

```javascript
import { renderWorkflow } from 'archify/renderers/workflow';
import { readFile } from 'fs/promises';

async function renderDiagram(filePath) {
  const raw = await readFile(filePath, 'utf8');
  const diagram = JSON.parse(raw);

  // Validates against workflow schema before rendering
  const html = await renderWorkflow(diagram, { output: 'string' });

  console.log('Rendered diagram HTML:', html);
}

renderDiagram('examples/maka-architecture.architecture.json')
  .catch(err => {
    console.error('Rendering failed:', err.message);
    // SchemaValidationError contains detailed path info
  });

```

The `renderWorkflow` function signature accepts:
- **First argument**: the parsed diagram object
- **Second argument**: options including `output: 'string'` or `output: 'file'`

## Integrate Archify Validation into CI/CD Pipelines

Archify's non-zero exit codes and `--dry-run` flag enable seamless CI integration:

```yaml

# .github/workflows/archify.yml

name: Validate & Render Archify Diagrams
on: [push, pull_request]

jobs:
  archify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Archify
        run: npm ci
      - name: Validate all diagrams
        run: |
          for f in $(git ls-files '**/*.architecture.json'); do
            npx archify render "$f" --dry-run || exit 1
          done
      - name: Render production diagrams
        run: |
          npx archify render docs/architecture.architecture.json \
            --output public/diagram.html

```

This workflow fails fast on schema violations before attempting production renders.

## Key Schema and Validation Files

| File | Purpose |
|------|---------|
| [`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md) | Core rendering API and validation flow |
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | JSON-Schema defining diagram structure |
| [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) | Semantic post-render constraints |
| `scripts/run-tests.mjs` | CLI entry point wiring validation to rendering |
| [`examples/maka-architecture.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json) | Reference diagram for testing |

## Summary

- **Validation is automatic**: every render path validates against [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) first.
- **CLI or programmatic**: use `npx archify render` or `renderWorkflow()` from `archify/renderers/workflow`.
- **Fast feedback**: `--dry-run` enables validation-only CI checks without file generation.
- **Detailed errors**: `SchemaValidationError` provides path-specific messages for rapid debugging.

## Frequently Asked Questions

### What happens if my Archify diagram fails validation?

Rendering aborts immediately with a `SchemaValidationError` containing the exact JSON path and description of each violation. The CLI prints these details and exits with a non-zero status code.

### Can I skip validation when rendering an Archify diagram?

No. The rendering pipeline in `archify/renderers/workflow` enforces validation as a mandatory first step. This design prevents the generation of misleading or broken visualizations from malformed input.

### How do I validate multiple Archify diagrams at once?

Use shell iteration with `--dry-run` as shown in the CI example above. The `render` command accepts single files; batch operations require scripting or CI workflow loops.

### What is the difference between schema validation and semantic checks?

Schema validation (in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)) verifies structural correctness—required fields, types, unique IDs. Semantic checks (defined in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md)) run optionally after rendering to enforce architectural rules like "no orphan nodes" or correct layer ordering.