sphinx-jsonschema

What it is and what it does

sphinx-jsonschema is a Sphinx documentation extension that lets you embed and render JSON Schema definitions directly in your documentation. You can reference schemas from URLs, local files, or Python objects, and use JSON Pointer notation to display subschemas. The extension supports inline reStructuredText markup in schema titles and descriptions, and includes custom extensions like $$target for cross-references and $$description for multi-line descriptions.

The package has been in development since 2017-01-29 and implements most JSON Schema Draft 4 features plus the examples keyword from Draft 7. It has no runtime dependencies beyond Sphinx itself, but the repository is now archived and marked abandoned, meaning maintenance and compatibility updates are no longer active.

Use it for:

• Embed API specification schemas in REST API documentation for developers to understand request/response structures
• Display configuration file schema definitions in project documentation to guide users on valid settings
• Reference shared schema definitions across multiple documentation pages using JSON Pointer and cross-references
• Render complex nested schemas with formatted descriptions and tables using reStructuredText markup
• Load schemas from external URLs or files to keep documentation in sync with canonical schema definitions

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that renders JSON Schema definitions inline or from external files directly into documentation, with support for JSON Pointer notation, cross-references, and reStructuredText markup.

Yes, with conditions. The extension is stable and feature-complete for JSON Schema Draft 4 documentation, with no known vulnerabilities. However, the abandoned maintenance status and archived repository mean no future bug fixes or Sphinx compatibility updates are guaranteed. Install only if your Sphinx version is compatible with 1.19.2 and you do not expect ongoing support.

Install

sphinx-jsonschema on PyPI

pip install sphinx-jsonschema

uv add sphinx-jsonschema

poetry add sphinx-jsonschema

Installing sphinx-jsonschema

Before you install

High install friction: the package has no runtime dependencies but is marked abandoned with an archived repository. The last commit is recent (2025-12-01), but the maintenance status is abandoned, meaning bug fixes and compatibility updates are unlikely.

License in practice

Licensed under GPLv3 (copyleft). Any project that distributes documentation built with this extension must comply with GPLv3 terms, including source disclosure if the extension is modified or bundled.

Quickstart

pip install sphinx-jsonschema

In conf.py:
extensions = ['sphinx-jsonschema']

In your .rst file:
.. jsonschema:: http://some.domain/spec.json

Or inline:
.. jsonschema::

    {"type": "string", "minLength": 10}

Requires Sphinx to be installed and a working Sphinx documentation project; the extension must be added to the extensions list in conf.py to function.

Verify before relying

• Compatibility with Sphinx 9.0 and later versions beyond the reported fix in 1.19.2
• Whether the abandoned status affects long-term stability or if the package is feature-complete and stable enough for production use
• Support for JSON Schema Draft 7 and later versions beyond the stated 'examples' keyword support

Package facts

Evidence: sphinx_jsonschema-1.19.2.tar.gz

Keywords: sphinx, json, schema

Tags

More Sphinx packages