jsonschema-diagram 0.1.0

Python API, CLI, and Sphinx integration for the JSON Schema Diagram viewer

jsonschema_diagram

A frontend-first toolkit for visualizing JSON Schema as an interactive node graph, with a polished web viewer, self-contained embed artifacts, a Python API, CLI, and Sphinx integration.

Documentation | Sphinx Demo | Python API | CLI | Schema Support

✨ Features

• Interactive schema graph: render objects, arrays, refs, enums, and combinators as connected cards instead of raw JSON blocks.
• Frontend-first architecture: parsing, graph building, ref resolution, layout, search, and interaction all live in the browser.
• Embed-ready output: generate a self-contained HTML viewer for docs portals, static pages, and Sphinx.
• Python integration: use a small Python API and CLI to serve the site, render embed HTML, and integrate with docs tooling.
• Sphinx extension included: embed diagrams from inline JSON, local schema files, or a shared default schema.
• Selection and path tooling: inspect schema paths and JSON paths, copy them in multiple formats, and follow links across the graph.
• Theme-aware viewer: support clean read-only embed mode with configurable default themes.

🚀 Quick Start

Installation

For normal usage, install the published Python package:

python3 -m pip install jsonschema-diagram

You do not need npm install just to:

• serve the viewer
• render embed HTML
• use the Python API
• use the Sphinx extension

Local Viewer

Serve the viewer and the default schema endpoint:

jsonschema-diagram serve

Self-Contained Embed

jsonschema-diagram render-embed \
  --schema-path schemas/default.json \
  --theme slate \
  --output diagram.html

30-Second Python Example

from jsonschema_diagram import load_default_schema, render_embed_html

schema = load_default_schema()
html = render_embed_html(schema, default_theme="slate")

print(html[:200])

CLI Usage

# Serve the built site plus /api/default-jsonschema
jsonschema-diagram serve --host 127.0.0.1 --port 8000

# Render a self-contained embed document
jsonschema-diagram render-embed \
  --schema-path schemas/default.json \
  --theme slate \
  --output diagram.html

# Read schema JSON from stdin
cat schemas/default.json | jsonschema-diagram render-embed --stdin --output diagram.html

Sphinx Guide

Build the embed artifact and the docs site:

python3 -m pip install jsonschema-diagram
python3 -m pip install -r docs/requirements.txt
npm run build:embed
python3 -m sphinx -E -a -b html docs docs/_build/html

Minimal conf.py:

extensions = ["jsonschema_diagram_sphinx"]

jsonschema_diagram_embed_template = "dist/embed/jsonschema-diagram.embed.jinja2.html"
jsonschema_diagram_default_schema_path = "schemas/default.json"
jsonschema_diagram_default_height = "760px"
jsonschema_diagram_default_theme = "slate"

Minimal directive:

.. jsonschema-diagram::
   :schema-file: examples/pattern-catalog.json
   :theme: mono
   :height: 720px

Frontend Development Only

You only need Node.js and npm install when you want to rebuild or work on the frontend itself:

npm install
npm run dev

🧭 Viewer Modes

site

The full application experience:

• left schema input panel
• theme preset picker
• raw schema editor
• apply/reset actions
• graph canvas, search, zoom, and selection dialog

embed

The clean viewer-only mode:

• no left editor panel
• ideal for docs and static embedding
• default schema and theme are injected through runtime config or Jinja

Runtime config shape:

<script>
window.__JSONSCHEMA_DIAGRAM_CONFIG__ = {
  mode: "embed",
  defaultTheme: "slate",
  defaultSchema: {...}
};
</script>

📦 Build Outputs

npm run build

This produces:

• dist/site/index.html: normal static site build
• dist/embed/jsonschema-diagram.embed.html: baked standalone embed file
• dist/embed/jsonschema-diagram.embed.jinja2.html: Jinja2-friendly embed template

The Jinja2 embed variant accepts:

• default_schema
• default_schema_json
• default_theme

If not provided, it falls back to the shared schema in schemas/default.json and the default embed theme.

🧩 Supported Schema Features

Current core support includes:

• type
• format
• properties
• required
• patternProperties
• items
• prefixItems
• enum
• const
• anyOf
• oneOf
• allOf
• local #/... $ref

More detail is documented in Schema Support.

🐍 Python API

Public helpers currently include:

• load_default_schema()
• load_json_schema(path)
• render_embed_html(schema, default_theme=...)
• write_embed_html(path, schema, default_theme=...)
• create_server(...)
• build_handler(...)

Example:

from jsonschema_diagram import create_server, load_json_schema, write_embed_html

schema = load_json_schema("schemas/default.json")
write_embed_html("build/diagram.html", schema, default_theme="mono")

server = create_server(host="127.0.0.1", port=8000)
server.serve_forever()

Full reference: Python API

📚 Sphinx Extension

The repository ships with jsonschema_diagram_sphinx, which embeds the viewer through an iframe using the self-contained embed artifact.

Minimal conf.py:

extensions = ["jsonschema_diagram_sphinx"]

jsonschema_diagram_embed_template = "dist/embed/jsonschema-diagram.embed.jinja2.html"
jsonschema_diagram_default_schema_path = "schemas/default.json"
jsonschema_diagram_default_height = "760px"
jsonschema_diagram_default_theme = "slate"

Minimal directive:

.. jsonschema-diagram::
   :schema-file: examples/pattern-catalog.json
   :theme: mono
   :height: 720px

More detail: Sphinx Extension

📖 Documentation

The repository includes a much more detailed Sphinx doc set than the demo page alone.

• Getting Started
• Viewer Modes
• Python API
• CLI
• Sphinx Extension
• Schema Support
• Troubleshooting
• Development
• Demo Page

Build the docs locally:

python3 -m pip install -r docs/requirements.txt
python3 -m sphinx -E -a -b html docs docs/_build/html

🛠️ Development

Common commands:

npm test
python3 -m unittest discover -s tests -v
npm run build
python3 -m sphinx -E -a -b html docs docs/_build/html

Python code quality commands:

make format
make lint
make type-check

These use the configured tooling:

• black
• isort
• flake8
• mypy

🗂️ Project Layout

• src/: React + TypeScript viewer
• schemas/default.json: shared default schema
• jsonschema_diagram/: Python API and CLI
• jsonschema_diagram_sphinx/: Sphinx extension
• backend/: compatibility HTTP server entrypoint
• docs/: Sphinx documentation source
• scripts/build-embed.mjs: embed builder

📄 License

MIT License. See LICENSE for details.