Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Enforce JSON IR schemas at runtime via ajv

tt-a1ifd2a2b683a42
diff --git a/.gitignore b/.gitignore
index 1dd711a2..4501e648 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
.DS_Store
*.DS_Store
.harnessed/
+archify/node_modules/
diff --git a/archify/SKILL.md b/archify/SKILL.md
index b7370c83..5c3360b1 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -40,6 +40,18 @@ When the user says "data flow", "pipeline", "ETL", "ELT", "lineage", "analytics"
When the user says "state", "status", "lifecycle", "state machine", "terminal", "retry", "cancel", "timeout", "order lifecycle", "deployment lifecycle", "agent run lifecycle", or asks how an object changes state over time, use the `lifecycle` mode.
+### Schema Validation (all renderer modes)
+
+Every JSON file is validated against its schema (`archify/schemas/*.schema.json`) before any layout work runs. Schema violations exit non-zero with a path-prefixed error message — for example `/cards/0/dot must be equal to one of the allowed values ["cyan","emerald","violet","amber","rose","orange","slate"]` or `/nodes/0/id must match pattern "^[a-zA-Z][a-zA-Z0-9_-]*$"`. Common things the schema catches before the renderer touches the file:
+
+- Unknown node/participant/state `type`, unknown card `dot`
+- IDs containing spaces or starting with a digit
+- Extra/misspelled fields (`additionalProperties: false` is set on every object)
+- Missing required fields (`label`, `meta.title`, etc.)
+- `schema_version` not equal to `1`
+
+If a render fails with a schema error, fix the JSON and re-run; do not edit the renderer.
+
### Workflow Mode
Workflow diagrams use a compact JSON IR:
@@ -75,9 +87,8 @@ The renderer:
- Places nodes by lane + column instead of raw SVG coordinates
- Routes edges through explicit anchors and orthogonal route presets
- Uses `c-lane` swimlanes plus the normal semantic component classes
-- Hides labels on short adjacent links unless a label is truly necessary
- Adds a `c-mask` label background for routed labels
-- Fails fast when nodes overlap, leave their lane, or short arrows become unreadable
+- Fails fast on schema violations, overlapping nodes, out-of-lane placement, and labeled short links — keep adjacent-step labels minimal in the JSON to avoid the short-link error
Use workflow labels sparingly. Adjacent steps should often be unlabeled; reserve labels for cross-lane transitions, approval decisions, async trace writes, and return paths.
@@ -117,7 +128,7 @@ The renderer:
- Uses semantic message variants: `emphasis`, `security`, `return`, and `dashed`
- Uses activation bars to show ownership duration
- Uses light segment bands as story landmarks
-- Fails fast when participants overflow, message endpoints are unknown, or message rows are too tight
+- Fails fast on schema violations, overflowing participants, unknown message endpoints, and rows that are too tight
Use sequence diagrams when the important thing is order over time. Keep labels short; prefer "GET /path", "verify JWT", "cache miss", "emit trace", and "200 JSON" over prose sentences.
@@ -160,7 +171,7 @@ The renderer:
- Uses vertical stage bands for source, ingest, process, store, and consume boundaries
- Uses flow labels to name data assets, plus optional `classification` for PII/governance context
- Uses semantic variants: `emphasis` for the primary data path, `security` for PII/policy/consent/restricted joins, and `dashed` for async or batch derivations
-- Fails fast when nodes overlap, stages overflow, flow endpoints are unknown, labels are missing, or arrows become unreadably short
+- Fails fast on schema violations, node overlap, stage overflow, unknown flow endpoints, missing labels, and unreadably short arrows
Use data-flow diagrams when the important thing is data lineage and governance. Keep labels asset-like: "clickstream", "identity map", "normalized facts", "feature vectors", "restricted join". Put sensitivity in `classification`: "PII touch", "encrypted PII", "approved only", "non-PII", "read-only".
@@ -201,7 +212,7 @@ The renderer:
- Uses lanes to separate the happy path, wait states, and exception/recovery paths
- Uses semantic state types: `start`, `active`, `waiting`, `decision`, `success`, `failure`, and `neutral`
- Uses transition variants: `emphasis` for the primary lifecycle, `security` for failure/cancel/timeout/policy paths, and `dashed` for retry/resume paths
-- Fails fast when states overlap, leave their lane, reference unknown lanes, use unknown transition endpoints, or push the legend outside the viewBox
+- Fails fast on schema violations, state overlap, out-of-lane placement, unknown lanes, unknown transition endpoints, and legends pushed outside the viewBox
Use lifecycle diagrams when the important thing is state, not step-by-step work. Keep transition labels event-like: "start", "plan ready", "needs approval", "retry", "timeout", "cancel". Put terminal states on the right or in the bottom lane so endings are visually unambiguous.
diff --git a/archify/package-lock.json b/archify/package-lock.json
new file mode 100644
index 00000000..175917db
--- /dev/null
+++ b/archify/package-lock.json
@@ -0,0 +1,69 @@
+{
+ "name": "archify",
+ "version": "2.4.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "archify",
+ "version": "2.4.0",
+ "license": "MIT",
+ "dependencies": {
+ "ajv": "^8.17.1"
+ }
+ },
+ "node_modules/ajv": {
+ "version": "8.20.0",
+ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+ "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+ "license": "MIT",
+ "dependencies": {
+ "fast-deep-equal": "^3.1.3",
+ "fast-uri": "^3.0.1",
+ "json-schema-traverse": "^1.0.0",
+ "require-from-string": "^2.0.2"
+ },
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/sponsors/epoberezkin"
+ }
+ },
+ "node_modules/fast-deep-equal": {
+ "version": "3.1.3",
+ "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+ "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+ "license": "MIT"
+ },
+ "node_modules/fast-uri": {
+ "version": "3.1.0",
+ "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+ "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "BSD-3-Clause"
+ },
+ "node_modules/json-schema-traverse": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+ "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+ "license": "MIT"
+ },
+ "node_modules/require-from-string": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+ "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ }
+ }
+}
diff --git a/archify/package.json b/archify/package.json
new file mode 100644
index 00000000..ec20ebee
--- /dev/null
+++ b/archify/package.json
@@ -0,0 +1,11 @@
+{
+ "name": "archify",
+ "version": "2.4.0",
+ "private": true,
+ "type": "module",
+ "description": "JSON-IR diagram renderers (workflow / sequence / dataflow / lifecycle).",
+ "license": "MIT",
+ "dependencies": {
+ "ajv": "^8.17.1"
+ }
+}
diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjs
index 9a808478..d5914b1f 100644
--- a/archify/renderers/dataflow/render-dataflow.mjs
+++ b/archify/renderers/dataflow/render-dataflow.mjs
@@ -2,11 +2,13 @@ import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
+import { validateSchema } from '../shared/validator.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
const inputPath = path.resolve(process.argv[2] || path.join(skillRoot, 'examples/product-analytics.dataflow.json'));
const dataflow = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+validateSchema('dataflow', dataflow);
const templatePath = path.join(skillRoot, 'assets/template.html');
const template = fs.readFileSync(templatePath, 'utf8');
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 94bb8088..b02f7a6f 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -2,11 +2,13 @@ import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
+import { validateSchema } from '../shared/validator.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
const inputPath = path.resolve(process.argv[2] || path.join(skillRoot, 'examples/agent-run.lifecycle.json'));
const lifecycle = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+validateSchema('lifecycle', lifecycle);
const templatePath = path.join(skillRoot, 'assets/template.html');
const template = fs.readFileSync(templatePath, 'utf8');
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index f83b6822..eb9b4f37 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -2,11 +2,13 @@ import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
+import { validateSchema } from '../shared/validator.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
const inputPath = path.resolve(process.argv[2] || path.join(skillRoot, 'examples/cache-miss-request.sequence.json'));
const sequence = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+validateSchema('sequence', sequence);
const templatePath = path.join(skillRoot, 'assets/template.html');
const template = fs.readFileSync(templatePath, 'utf8');
diff --git a/archify/renderers/shared/validator.mjs b/archify/renderers/shared/validator.mjs
new file mode 100644
index 00000000..a0023bbf
--- /dev/null
+++ b/archify/renderers/shared/validator.mjs
@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const schemasDir = path.resolve(__dirname, '../../schemas');
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+
+const validators = {};
+for (const type of ['workflow', 'sequence', 'dataflow', 'lifecycle']) {
+ const schema = JSON.parse(fs.readFileSync(path.join(schemasDir, `${type}.schema.json`), 'utf8'));
+ validators[type] = ajv.compile(schema);
+}
+
+function formatErrors(errors) {
+ return errors.map((e) => {
+ const where = e.instancePath || '/';
+ const detail = e.params && Object.keys(e.params).length
+ ? ' ' + JSON.stringify(e.params)
+ : '';
+ return ` ${where} ${e.message}${detail}`;
+ }).join('\n');
+}
+
+export function validateSchema(diagramType, data) {
+ const validate = validators[diagramType];
+ if (!validate) {
+ throw new Error(`validateSchema: unknown diagram type "${diagramType}"`);
+ }
+ if (!validate(data)) {
+ throw new Error(
+ `${diagramType} schema validation failed:\n${formatErrors(validate.errors)}`
+ );
+ }
+}
diff --git a/archify/renderers/workflow/render-workflow.mjs b/archify/renderers/workflow/render-workflow.mjs
index c41a9f28..f85f6377 100644
--- a/archify/renderers/workflow/render-workflow.mjs
+++ b/archify/renderers/workflow/render-workflow.mjs
@@ -2,12 +2,14 @@ import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
+import { validateSchema } from '../shared/validator.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
const repoRoot = path.resolve(skillRoot, '..');
const inputPath = path.resolve(process.argv[2] || path.join(skillRoot, 'examples/agent-tool-call.workflow.json'));
const workflow = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+validateSchema('workflow', workflow);
const templatePath = path.join(skillRoot, 'assets/template.html');
const template = fs.readFileSync(templatePath, 'utf8');