Install & Compatibility
Where this runs
tested against v1.19.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 29.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.4s · import 0.000s · 30MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
'sphinx-jsonschema'
✓ extensions = ['sphinx-jsonschema'] # in conf.py
sphinx-jsonschema is a Sphinx extension; its primary 'import' is by adding its name to the `extensions` list in your Sphinx project's conf.py.
To quickly display a JSON Schema, install the package, add `'sphinx-jsonschema'` to the `extensions` list in your `conf.py`, and then use the `jsonschema` directive in your reStructuredText (`.rst`) files. You can refer to a local file (relative or absolute path), an HTTP(S) URL, a Python object, or embed the schema inline. Options like `:lift_title:` and `:lift_description:` control rendering behavior.
# conf.py
# ... (other Sphinx configurations)
extensions = [
'sphinx.ext.autodoc',
'sphinx-jsonschema'
]
# my_schema.json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Example Product",
"description": "A simple product schema.",
"type": "object",
"properties": {
"productId": {
"type": "integer",
"description": "The unique identifier for a product"
},
"productName": {
"type": "string",
"description": "Name of the product"
}
},
"required": ["productId", "productName"]
}
# index.rst (or any .rst file)
.. jsonschema:: my_schema.json
:lift_title: True
:lift_description: True
:encoding: utf-8
Alternatively, embed the schema directly:
.. jsonschema::
{
"title": "Inline Schema Example",
"type": "string",
"minLength": 10
}
Debug
Known issues
gotchasphinx-jsonschema extends standard JSON Schema with custom keywords like `$$target` and `$$description`. `$$target` is used for internal cross-referencing within Sphinx, and `$$description` allows multi-line descriptions. These are not part of the official JSON Schema specification.fixBe aware these keywords are specific to sphinx-jsonschema and will not be understood by standard JSON Schema validators or other tools. Use `$$target` to enable `ref` roles and `$$description` for complex descriptions where needed.
affects: All versions
gotchaThe library handles JSON Schema's `$ref` and `$id` keywords non-standardly. It ignores `$id` and uses `$ref` to create reStructuredText `:ref:` roles for linking between schemas. For this to work, the target schema must be marked with the `$$target` key, whose value must match the `$ref` value.fixEnsure that any schema you intend to cross-reference via `$ref` in another schema also defines the `$$target` keyword with a matching value in its outermost object. The referenced schema must also be explicitly included in your documentation.
affects: All versions
gotchaWhile capable of displaying various JSON Schema drafts, the documentation explicitly states it was 'only tested it for use with the draft 4 specification of JSON Schema'. Newer drafts (e.g., Draft 2019-09, Draft 2020-12) introduced breaking changes to the JSON Schema specification (e.g., `$recursiveRef` became `$dynamicRef`, `items` array form changed), which might lead to unexpected rendering or interpretation issues.fixTest your schemas thoroughly if they adhere to JSON Schema drafts newer than Draft 4. Consider validating your schemas externally to ensure they conform to the expected draft.
affects: All versions (especially with newer JSON Schema drafts)
gotchaStrings within schema definitions (e.g., in `description` or `title`) might undergo unintended character escaping (e.g., `_`, `*`) during Sphinx's multiple rendering passes. This can alter the appearance of reStructuredText markup.fixUse the `:pass_unmodified:` directive option with one or more JSON Pointers to specify paths within the schema where escaping should be prevented. For example, `:pass_unmodified: /description` or `:pass_unmodified: /properties/myKey/description`.
affects: All versions
Upgrade
Version history
1.19.2latest on PyPI · released Dec 1, 2025
Audit
Dependencies
SphinxrequiredCore dependency as it is a Sphinx extension.