@archsmith/schema

@archsmith/schema

The IR schema and governed registries for ArchSmith — the structural contract a diagram intermediate representation (IR) must satisfy, and the catalog of colors/sub-layer types it's allowed to reference.

See the root README for what ArchSmith is and how the pieces fit together; this package is the schema layer only, consumed by @archsmith/renderer for validation.

Files

• diagram-schema.json — JSON Schema (draft 2020-12) for the IR: the document a human or agent produces describing a layered architecture, and that @archsmith/renderer validates and renders to SVG. Fixed shape: 5 columns, Core Platform sub-layers stacked in order, systems-of-record as a sibling section below the "deployed on" wrapper.
• registries/sub-layers.json — the governed, extensible list of Core Platform sub-layer types (Discovery and Governance, Execution and Capability Layer, Entity Layer, Systems of Record and Knowledge).
• registries/colors.json — the governed color catalog. The standard family is fully populated; accessible (a colorblind/contrast-safe palette) has the right structure but no values yet — tracked here.
• registries/icons.json — placeholder only. Categories that will need icons are listed; no actual icon tokens are defined yet, deliberately, to avoid inventing bespoke icon shapes ad hoc — tracked here. Items without an icon render as a plain colored dot.

Usage

import { getDiagramSchema, getRegistry, listRegistryNames } from "@archsmith/schema";

const schema = getDiagramSchema(); // the parsed diagram-schema.json
const colors = getRegistry("colors"); // one governed registry, parsed
listRegistryNames(); // ["sub-layers", "colors", "icons"]

In practice you'll rarely call this package directly — @archsmith/renderer's validate()/render() already do, and @archsmith/mcp-server exposes the schema and each registry as MCP resources for an agent to read live.

Governance model

Changing diagram-schema.json's structure, or adding an entry to any registry, is a deliberate change-request event — never a decision made by a generation step or an end user mid-diagram. This is what keeps the format a consistent house style rather than free-form per-diagram layout. Bump schemaVersion/registryVersion on any such change.

What stays free per diagram (no change request needed): which already-approved sub-layers/colors/icons a given diagram uses, how many rows of boxes a layer has, whether a notes callout is included, which color family is active.

License

Apache-2.0