oleg-lukasonokandClaude Opus 5.5
d56e784e97
VS Code extension that previews Archify diagrams from their JSON sources (live, as you type) and opens rendered Archify HTML in a viewer tab. Bundles the Archify 3.0.1 renderer and runs it on VS Code's Node runtime. Adds validation diagnostics, JSON schema help, source-link navigation, export saving, render-to-file and open-in-browser commands. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
257 lines
14 KiB
Markdown
257 lines
14 KiB
Markdown
# Archify JSON IR Schemas
|
|
|
|
Each typed renderer consumes a JSON intermediate representation (IR) validated
|
|
against one of the schemas in this folder before any layout work happens.
|
|
|
|
## Files
|
|
|
|
| Schema | Governs | Structural arrays |
|
|
|--------|---------|-------------------|
|
|
| `workflow.schema.json` | `diagram_type: "workflow"` | `lanes`, `phases`, `groups`, `mainPath`, `nodes`, `edges` |
|
|
| `sequence.schema.json` | `diagram_type: "sequence"` | `participants`, `segments`, `messages`, `activations` |
|
|
| `dataflow.schema.json` | `diagram_type: "dataflow"` | `stages`, `nodes`, `flows` |
|
|
| `lifecycle.schema.json` | `diagram_type: "lifecycle"` | `lanes`, `states`, `transitions` |
|
|
| `architecture.schema.json` | `diagram_type: "architecture"` | `components`, `boundaries`, `connections` |
|
|
| `common.schema.json` | shared `$defs` only (no top-level document) | — |
|
|
|
|
Every diagram schema requires `schema_version`, `diagram_type`, `meta` (with
|
|
`title` and a durable portable `output`), and its structural arrays — except `segments`, `activations`, and
|
|
`cards`, which are optional — and sets `additionalProperties: false` at every
|
|
level, so unknown fields are rejected rather than silently ignored.
|
|
|
|
Every `meta` object also accepts `animation: "trace"` for opt-in SVG/CSS motion
|
|
in generated HTML. Omit it, or set `"none"`, for the default static output.
|
|
It also accepts `locale`, any well-formed language tag (schema pattern
|
|
`^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$`). The field selects the fixed Viewer UI,
|
|
renderer-owned default legend and accessibility copy, document-title suffix,
|
|
and `<html lang>` value; it does not translate authored strings. `en` and
|
|
`zh-CN` are built-in catalogs; any other tag needs a matching `translations`
|
|
object (see below) or the renderer falls back to English and discloses it.
|
|
Omitting `locale` preserves legacy behavior and resolves to English.
|
|
Malformed locale tags fail schema validation instead of being guessed or
|
|
silently rewritten.
|
|
|
|
`meta.translations` supplies the Viewer message catalog for a `locale` with no
|
|
built-in catalog, as data: an object mapping canonical message keys (see
|
|
`catalogKeys()` in `renderers/shared/i18n.mjs`) to translated strings whose
|
|
`{placeholder}` tokens match the English source. A key that is missing,
|
|
unrecognized, or has mismatched placeholders falls back to English rather than
|
|
failing the render; `validate`/`render`/`deliver` report the resulting
|
|
coverage to stderr. Spanish uses the reusable `examples/locales/es.json`
|
|
catalog; dev inputs that previously used only `locale: "es"` now need this
|
|
object in `meta.translations` to retain Spanish UI.
|
|
`visual_preset` accepts `classic` (the stable default), `signal-flow` (luminous
|
|
motion-forward presentation), `blueprint` (high-contrast engineering review),
|
|
or `editorial` (warm publication-style design review and documentation).
|
|
Presets change only viewer styling; they do not alter semantic IDs or geometry.
|
|
Sequence `meta` additionally accepts `column_fit`. The default `fixed` keeps
|
|
the historical 108px column gap and 86px participant boxes, so an authored
|
|
diagram renders at the same coordinates no matter how wide its viewBox is.
|
|
`spread` derives the gap and box width from the viewBox instead, which turns a
|
|
wide canvas into column distance and label room rather than empty space on the
|
|
right. Lane order, IDs, and message semantics are unchanged either way.
|
|
|
|
`meta.views` is retired. The schemas still accept the old guided-view shape so
|
|
existing files keep validating, but renderers ignore it; do not author it.
|
|
|
|
### Legend presentation contract
|
|
|
|
Every `meta` object accepts the same optional legend shape without changing
|
|
the schema version already selected for that renderer:
|
|
|
|
```json
|
|
"legend": {
|
|
"mode": "auto",
|
|
"entries": {
|
|
"security": { "label": "restricted data", "visible": true }
|
|
}
|
|
}
|
|
```
|
|
|
|
`mode` is `auto` (the default), `all`, or `hidden`. `auto` includes only kinds
|
|
present in typed IR; `all` includes the renderer's full stable catalog;
|
|
`hidden` removes the complete legend and takes precedence over entry overrides.
|
|
Architecture documents that omit an explicit `viewBox` size that automatic
|
|
viewBox from the same measured resolved legend footprint used for final SVG
|
|
layout. Across all renderers, legacy documents that omit `meta.legend` use a
|
|
compatibility-safe implicit `auto`: if the resolved legend cannot fit an
|
|
explicit authored viewBox without overlap, Archify omits the complete legend
|
|
instead of turning a previously valid schema-v1 document into a hard failure.
|
|
Once an author adds `meta.legend` (including explicit `mode: "auto"`), the
|
|
layout is intentional and unfit labels or bands fail with a path-prefixed
|
|
diagnostic. An entry may set a non-empty, bounded `label`, boolean `visible`,
|
|
or both.
|
|
`visible: false` removes a resolved entry and `visible: true` forces a supported
|
|
but unused kind into the visual legend. Unknown kinds and properties fail
|
|
strict validation.
|
|
|
|
Supported keys are renderer-owned:
|
|
|
|
| Renderer | `meta.legend.entries` keys |
|
|
|---|---|
|
|
| Architecture | `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external` |
|
|
| Workflow | `frontend`, `backend`, `security`, `messagebus`, `database`, `cloud`, `external` |
|
|
| Sequence | `emphasis`, `return`, `security`, `dashed`, `default` |
|
|
| Dataflow | `emphasis`, `security`, `dashed`, `database`, `default` |
|
|
| Lifecycle | `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, `external` |
|
|
|
|
Labels are presentation only: they do not rename the stable kind, change
|
|
nodes/relationships, or create Semantic Lens edge facts. Sequence message and
|
|
Dataflow flow-variant entries are visual keys. Component/state entries backed
|
|
by exact compiled node facts receive the interactive Semantic Legend bridge;
|
|
this includes Dataflow `database` when a real `nodes[].type: "database"` fact
|
|
exists.
|
|
|
|
Every relationship collection (`connections`, `edges`, `messages`, `flows`, and
|
|
`transitions`) accepts an optional author-controlled `id` using the shared ID
|
|
pattern. The renderer keeps its source-order runtime key separately, while the
|
|
authored ID enables a stable `#relation=<id>` viewer link that survives array
|
|
reordering. ID-less documents remain valid and their relationship pins stay
|
|
local to the current page.
|
|
|
|
Every semantic node collection (`components`, `nodes`, `participants`, and
|
|
`states`) also accepts one optional `brand`: either a canonical string returned
|
|
by `archify brands --json`, or a digest-pinned `{ "url", "sha256" }` object
|
|
returned by `archify brands capture <url> --json`. Known IDs and known-brand
|
|
domains use the bundled vector catalogue. Unknown URLs must be captured in that
|
|
explicit command before authoring; render and validate never perform an
|
|
unpinned network capture. Unsafe, unavailable, changed, or unsupported content
|
|
fails closed with a brand diagnostic. Omitted `brand` preserves the prior
|
|
output.
|
|
|
|
## schema_version policy
|
|
|
|
Workflow supports schema versions 1 and 2. Version 1 remains the fixed-layout
|
|
compatibility contract; version 2 opts into the readable workflow compiler and
|
|
can be produced explicitly with `archify migrate workflow ... --to-schema 2`.
|
|
Lifecycle also supports versions 1 and 2 with the same fields. Version 1 keeps
|
|
the fixed three-band layout; version 2 renders one row per lane on a shared
|
|
column grid (see the [lifecycle renderer](../renderers/lifecycle/README.md)).
|
|
Lifecycle has no migration command: to adopt v2, set `schema_version: 2`,
|
|
re-place lower-lane `col` values on the shared grid (v1 column `N` sat under
|
|
main column `N + 2`), and drop coordinates authored for the v1 canvas
|
|
(`viewBox`, `via`, `channelX`, `channelY`, `labelAt`).
|
|
The other three diagram schemas keep `schema_version` pinned to `1`; they have
|
|
no schema-version migration command. For any of the five diagram types, repair
|
|
a legacy missing or nonportable `meta.output` in the source and run `validate`.
|
|
For a workflow v1-to-v2 migration specifically, `migrate workflow` also accepts
|
|
`--output reports/diagram.html` to put that portable value in the separate v2
|
|
destination without changing the legacy source.
|
|
|
|
Workflow also accepts optional `semanticChecks`. `allowedRoots` and
|
|
`allowedTerminals` close the set of intentional graph sources and sinks;
|
|
`requiredEdges` requires exact authored relationships; and `requiredPaths`
|
|
requires directed reachability while allowing intermediate nodes. The compiler
|
|
evaluates these facts before layout and returns typed `workflow/*` diagnostics.
|
|
The field is additive and geometry-neutral: omitting it preserves existing
|
|
workflow behavior and including a satisfied contract does not change SVG or
|
|
layout-receipt bytes.
|
|
|
|
A file that validates today must keep validating and rendering within its
|
|
declared version throughout the 2.x release line. The explicitly reviewed
|
|
portable-output hardening is the one exception: older v1 documents that omit
|
|
`meta.output` must add a portable POSIX-relative `.html` path (for example,
|
|
`reports/diagram.html`); ordinary explicit CLI output arguments do not replace
|
|
this durable authored value. The workflow-only v1-to-v2 migration command may
|
|
instead receive that value explicitly as `--output reports/diagram.html`; it
|
|
writes the value only to its separate validated destination. Additive viewer,
|
|
accessibility, and presentation improvements may enhance generated HTML, but
|
|
they must not reinterpret authored IR or turn a previously valid profile-less
|
|
v1 file into a new hard layout failure. Breaking IR changes require a new
|
|
version; additive, backwards-compatible fields do not.
|
|
|
|
## Shared definitions (common.schema.json)
|
|
|
|
The five diagram schemas reference `common.schema.json#/$defs/...`:
|
|
|
|
- `id` — element identifiers, pattern `^[a-zA-Z][a-zA-Z0-9_-]*$`
|
|
- `point` — an `[x, y]` pair of numbers (used by `via` and `labelAt`)
|
|
- `componentType` — `frontend`, `backend`, `database`, `cloud`, `security`,
|
|
`messagebus`, `external`
|
|
- `locale` — a well-formed renderer locale tag (`en` and `zh-CN` are built in;
|
|
any other tag needs a matching `translations` object)
|
|
- `translations` — canonical message key → translated string, for a `locale`
|
|
with no built-in catalog
|
|
- `portableOutputPath` — the portable POSIX-relative `.html` path used by
|
|
`meta.output`; see the two output-path boundaries in the
|
|
[delivery contract](../references/delivery-contract.md#output-path-contracts)
|
|
- `brandMark` — one optional built-in brand ID or explicit HTTP(S) site URL
|
|
- `variant` — `default`, `emphasis`, `security`, `dashed` (sequence messages
|
|
extend this list locally with `return`)
|
|
- `legendMode` and `legendEntry` — the shared strict mode and label/visibility
|
|
override shapes used by each renderer-owned key map
|
|
- `guidedViews` — the retired `meta.views` shape, still accepted and ignored
|
|
- `cards` — the summary-card blocks rendered below the SVG
|
|
|
|
Lifecycle state `type` is mode-specific (`start`/`active`/`waiting`/...) and
|
|
stays in `lifecycle.schema.json`.
|
|
|
|
The JSON Schema definition is the portable contract's structurally expressible
|
|
preflight. The shipped generated validator wrapper and CLI additionally enforce
|
|
byte-based component limits and the complete runtime path contract; consumers
|
|
that need the same cross-platform acceptance boundary should use that wrapper.
|
|
|
|
## Runtime validation
|
|
|
|
At development time, `scripts/generate-validators.mjs` compiles all five
|
|
schemas with ajv's draft 2020-12 standalone generator using `strict: true` and
|
|
`allErrors: true`. The generated `renderers/shared/generated-validators.mjs`
|
|
is committed and shipped with the skill, so runtime validation has no npm or
|
|
network dependency. `renderers/shared/validator.mjs` applies the matching
|
|
standalone validator before the renderer's own layout checks.
|
|
The shared loader then checks cross-collection facts that JSON Schema cannot
|
|
express cleanly here: duplicate view IDs, duplicate focus IDs, focus IDs that do
|
|
not exist in the diagram's semantic collection, and duplicate authored
|
|
relationship IDs within the mode's relationship collection.
|
|
|
|
All five modes support opt-in, revision-pinned repository evidence.
|
|
`meta.repository` names the repository URL and full commit SHA, with optional
|
|
`provider` (`github` or `gitee`) and `link_mode` (`web` or `local-only`; see the
|
|
authoring contract); a node may carry one to three `sources` with repo-relative POSIX paths, optional line
|
|
ranges, and optional labels. Sources are authored on the mode's own node
|
|
collection — Architecture `components`, Workflow and Data Flow `nodes`,
|
|
Sequence `participants`, Lifecycle `states` — and the verified payload is keyed
|
|
by node id. Shape is schema-checked, then the renderer requires
|
|
`--repo-root`: the local Git origin must match, and Git must prove the commit,
|
|
blobs, and requested lines. Verified evidence is embedded outside the canonical
|
|
SVG for the Semantic Passport and Node Finder; ordinary documents and visual
|
|
exports carry no repository evidence.
|
|
|
|
## Visual quality and engineering truth
|
|
|
|
`meta.quality_profile` and `meta.engineering_profile` answer different
|
|
questions. `quality_profile` is available in all five modes and controls how
|
|
strictly Archify judges composition. `engineering_profile` is an optional
|
|
Architecture-only semantic contract; omitting it preserves the ordinary v1
|
|
behavior.
|
|
|
|
The first engineering profile is `deployment-ownership`. Enable it only when
|
|
the user wants a fail-closed deployment review and the source facts are known.
|
|
It requires every non-external component to name an owner in `tag` and belong
|
|
to exactly one `region`; the document must contain both `region` and
|
|
`security-group` boundaries; every `database` must be inside a
|
|
`security-group`; each security group must contain members from one shared
|
|
region; and every connection whose region or security-group membership changes
|
|
must name the real crossing mechanism in `label`.
|
|
|
|
The profile validates only authored IR. It does not discover infrastructure,
|
|
infer owners, or prove that a diagram matches a live environment. If a fact is
|
|
unknown, leave the profile unset or obtain the fact instead of inventing it.
|
|
|
|
`npm test` runs the generator in check mode and fails when the committed
|
|
validators drift from their schemas.
|
|
|
|
## Error format
|
|
|
|
Schema violations exit non-zero. Each ajv error is reported on its own line as
|
|
the instance path — annotated with the nearest enclosing element's `id` or
|
|
`label` — followed by the message and parameters:
|
|
|
|
```text
|
|
workflow schema validation failed:
|
|
/nodes/3 (id/label: "router") must NOT have additional properties {"additionalProperty":"colour"}
|
|
```
|
|
|
|
Schemas catch shape errors (types, enums, ranges, unknown fields); geometry
|
|
problems such as overlaps and label collisions are the renderers' job.
|