@spec0/schema-graph

Parse an OpenAPI document and explore its schemas as a graph.

Give it a spec (YAML or JSON, string or object); it produces a deterministic graph model — schema nodes with field summaries, operation nodes, and the edges a reader wants drawn: schema→schema $ref relationships and operation→schema usage. Cycle-safe (recursive shapes are flagged, not followed forever).

import { buildSchemaGraph } from "@spec0/schema-graph";

const graph = buildSchemaGraph(specYamlOrJson);
// graph.schemas  → [{ name, description, fields, references, referencedBy, cyclic, raw }]
// graph.operations → [{ method, path, uses }]
// graph.edges    → [{ from, to, kind: "references" | "uses" }]

Everything is derived from the document alone — no network calls, no services, no framework dependencies. Rendering (React Flow canvas with progressive disclosure) ships as a separate entry point in this package.

Theming

The React canvas reads CSS custom properties, each falling back to its previous hardcoded value — so an embedder that sets nothing looks exactly as before, and one with a design system gets a canvas that matches it. Set them on any ancestor:

| Property | What it colours | |---|---| | --sg-canvas | Canvas background | | --sg-node-bg | Schema nodes | | --sg-op-bg | Operation nodes | | --sg-border | Node and container borders | | --sg-text | Node titles | | --sg-muted | Secondary text and uses edges | | --sg-accent | Selection and $ref edges | | --sg-accent-ring | Selection ring (needs its own value — alpha can't be composited from a token) | | --sg-panel-bg | Detail panel and toggle chips |

Structureless schemas

A schema with no fields and no outgoing references — a named primitive (EventId: {type: string}), an enum, or an empty marker object — is flagged simple and not drawn by default. As a node it is a box containing a scalar: nothing to reveal, nothing to expand into.

It matters more than it sounds. In hand-written specs this is routinely half of components/schemas (12 of 22 in Redocly's Museum API); Stripe has 97 empty marker objects among its 1440. They remain in the model and in any list the embedder renders — only the box is gone. A showSimple option, surfaced as a toggle in the canvas, draws them; a schema focused explicitly is always drawn regardless.

Roadmap

• React canvas component (schema-centric, operations toggle, click-to-expand)
• Standalone static HTML bundle mode (schema-graph bundle openapi.yaml -o graph.html)