sphinx-jsonschema

This package contains sphinx-jsonschema, an extension to Sphinx to allow authors to display a JSON Schema in their documentation.

A dockerized version can be found at: Extended Sphinx.

It arose out of a personal itch and implements what I needed. Some features of JSON Schema are (not yet) implemented. Also I can imagine that other display layouts are desired.

Let me know in comments and perhaps pull requests.

Features

Near complete support for all features of JSON Schema Draft 4, and support for the keywords of the later drafts up to Draft 2020-12 (see docs/schemaversions.rst for the list of keywords and the draft that introduced them).
Supports inline schemas as well as external schemas loaded from a file or URL.
Supports JSON Pointer notation on external resources to select a subschema.
Supports cross references between schemas.
Allows reStructuredText markup in title and description fields.
Allows JSON Schema definitions in both JSON and YAML format.
Supports the examples keyword from Draft 6.

Installation

Install the package using pip:

pip install sphinx-jsonschema

and add it to the extensions list in your conf.py:

extensions = [
    'sphinx-jsonschema'
]

Usage

The extension adds a single directive to Sphinx: jsonschema. You provide it with either an http URL to a schema or you may embed the schema inline.

Example

Display a schema fetched from a website:

.. jsonschema:: http://some.domain/with/a/path/spec.json

Display a schema located in a file with an absolute path:

.. jsonschema:: /home/leo/src/jsonschema/sample.json

A path relative to the referencing document:

.. jsonschema:: jsonschema/sample.json

Or a schema defined in a Python object:

.. jsonschema:: mod.pkg.SCHEMA

With all three of the above you may add JSON Pointer notation to display a subschema:

.. jsonschema:: http://some.domain/with/a/path/spec.json#/path/to/schema
.. jsonschema:: /home/leo/src/jsonschema/sample.json#/path/to/schema
.. jsonschema:: jsonschema/sample.json#/path/to/schema
.. jsonschema:: mod.pkg.SCHEMA#/path/to/schema

Alternatively you can embed the schema:

.. jsonschema::

    {
        "$schema": "This field is ignored for now. Perhaps use it to indicate schema version in display?",
        "title": "Test data set 1: **Simple type**",
        "id": "http://this.better.be.a.regular.domain",
        "description": "These data sets exercise `JSON Schema <http://json-schema.org>`_ constructions and show how they are rendered.\n\nNote that it is possible to embed reStructuredText elements in strings.",
        "type": "string",
        "minLength": 10,
        "maxLength": 100,
        "pattern": "^[A-Z]+$"
    }

This notation does not support JSON Pointer.

JSON Schema extension

$$target

sphinx-jsonschema extends JSON Schema with the $$target key.

This key is only recognized at the outermost object of the schema.

JSON Schema uses the $ref key in combination with the $id key to cross-reference between schemas.

Sphinx-jsonschema shows the $id of the outermost schema as the first row of the table but does not use it to resolve references. It uses the value of $ref to create a reStructuredText :ref: role.

For this to work you need to mark the target schema with the $$target key, the value of which must be identical to the value of the corresponding $ref key.

So a schema:

{
    "title": "Schema 1",
    "$ref": "#/definitions/schema2"
}

will have its $ref replaced by a link pointing to:

{
    "title": "Schema 2",
    "$$target": "#/definitions/schema2"
    ...
}

Occasionally a schema will be addressed from several other schemas using different $ref values. In that case the value of $$target should be a list enumerating all different references to the schema.

$$description: sphinx-jsonschema extends JSON Schema with the $$description key.

This key serves the same purpose as the description key and can be used in the same way. It differs from description in that it allows an array of strings as value instead of a single string.

This allows you to write:

{
   ...
   "description": "+------------+------------+-----------+ \n| Header 1   | Header 2   | Header 3  | \n+============+============+===========+ \n| body row 1 | column 2   | column 3  | \n+------------+------------+-----------+ \n| body row 2 | Cells may span columns.| \n+------------+------------+-----------+ \n| body row 3 | Cells may  | - Cells   | \n+------------+ span rows. | - contain | \n| body row 4 |            | - blocks. | \n+------------+------------+-----------+",
   ...
}

as:

{
   ...
   "$$description": [
      "+------------+------------+-----------+",
      "| Header 1   | Header 2   | Header 3  |",
      "+============+============+===========+",
      "| body row 1 | column 2   | column 3  |",
      "+------------+------------+-----------+",
      "| body row 2 | Cells may span columns.|",
      "+------------+------------+-----------+",
      "| body row 3 | Cells may  | - Cells   |",
      "+------------+ span rows. | - contain |",
      "| body row 4 |            | - blocks. |",
      "+------------+------------+-----------+"
   ],
   ...
}

Which clearly is much more readable and maintainable.

Licence

This software is made available under the GPL v3.

Changelog

Version 1.20.0

Maintenance handed over to Volker Wegert <https://github.com/vwegert>.
Fixed and extended automated tests, split into unit and integration tests, the latter using the actual Sphinx environment (issue #56 <https://github.com/lnoor/sphinx-jsonschema/issues/56>`).
Added a demo document in the demo directory that shows the directive options and supported schema elements; build it with tox -e demo-html, tox -e demo-latex or tox -e demo-pdf.
The documentation lists the supported keywords with the draft that introduced them (docs/schemaversions.rst), and the README no longer limits the support to Draft 4.
The demo document was extended with a part “Keywords by schema version” with one example per keyword of Drafts 4 to 2020-12. (issue #89).
Boolean schemas (true / false) are now rendered wherever a schema is expected, including allOf, not, if / then / else, dependencies and definitions. Before, most of these places failed with an error.
The annotation keywords deprecated, readOnly, writeOnly, contentMediaType, contentEncoding and contentSchema (Drafts 7 and 2019-09) are rendered. Before, they were ignored.
The new option show_comments (directive option and jsonschema_options) renders the keyword $comment (Draft 7). Without it comments stay hidden, as the specification asks.
The new option show_schema (directive option and jsonschema_options) renders the $schema keyword as the first row of the table. It is only displayed, the draft a schema names does not change how it is rendered.
The array keywords contains (Draft 6), minContains and maxContains (Draft 2019-09) are rendered. Before, they were ignored.
prefixItems (Draft 2020-12) is rendered like the list form of items of the older drafts, which is unchanged. An items schema next to prefixItems describes the remaining items.
unevaluatedProperties and unevaluatedItems (Draft 2019-09) are rendered like additionalProperties and additionalItems. Before, they were ignored.
propertyNames (Draft 6) is rendered. Before, it was ignored.
dependentRequired and dependentSchemas (Draft 2019-09), the two halves of the older dependencies, are rendered like it. Before, they were ignored.
$anchor, $dynamicAnchor and $recursiveAnchor are shown as a row of the schema they belong to. $dynamicRef and $recursiveRef (Drafts 2020-12 and 2019-09) are rendered like $ref, with the keyword as label.
A type list that contains both object and array now also renders the array keywords such as items. Before, only the keywords of the object type were shown.
Fixed visible backslashes before underscores in inline literals within default and examples values (issue #96).
Targets created by auto_target or $$target get an id that is unique in the document. Before, a schema with a title could define the same id twice (LaTeX: “Label multiply defined”), or take the id of a section with the same title, which made :ref: link to the wrong place.
With lift_title: off and auto_reference a $ref: "#" links to the target auto_target creates for the schema instead of an undefined label <file># (issue #94).
* in a hide_key / hide_key_if_empty path followed by more segments now passes through exactly one level, as documented: /properties/*/description hides the description of every property (issue #100).
.. jsonschema:: without argument and content now reports that there is nothing to render instead of failing with a TypeError (issue #102).
A JSON pointer that can’t be resolved (schema.json#/nope) now gives the intended error message instead of a raw traceback of jsonpointer (issue #101).
enum values are escaped like default and pattern, so * and _ in them stay literal instead of being interpreted as reStructuredText (issue #98).
Booleans and null are rendered as true, false and null instead of Python’s True, False and None (for example in enum, exclusiveMinimum, uniqueItems and additionalItems; issue #95).
:pass_unmodified: no longer shows its internal :noesc: marker when it points at a description, title or other value that is not escaped (issue #97).
A $ref to a URL or to the schema root (#) is no longer rendered as a :ref: role, which always produced an “undefined label” warning (issue #99).
Changed behaviour: a $ref that is rendered as a reference to a label (internal pointers such as #/$defs/Item or other files) no longer produces an “undefined label” warning when the label doesn’t exist; it is shown as plain text (issue #88, issue #99). The new option warn_unresolved_refs (directive option and jsonschema_options) restores the warnings, for example to find typos in labels defined with $$target.

Version 1.19.2

Karolina Surma <https://github.com/befeleme> provided a fix allowing the software to build with Sphinx 9.0.

Version 1.19.1

Eddie Darling <https://github.com/spagh-eddie> with Michal Čihař <https://github.com/nijel> and Kim Berninger <https://github.com/kimberninger> fixed a bug addressing relative files.

Version 1.19.0

Glenn Nicholls <https://github.com/GlenNicholls> contributed code to load a schema from a Python dict or object (or actually any Python entity with a __str__ method.).

Version 1.18.0

Expanding on the work of Pavel Odvody with JSON Pointer the :pass_unmodified: option is included. This option prevents escaping the string pointed at. This extension arose from discussions with Ryan Lane <https://github.com/ryan-lane>

Version 1.17.2

Ezequiel Orbe found, reported and fixed a bug escaping backspaces.

Version 1.17.0

Pavel Odvody contributed the :hide_key: directive option. This option allows you to hide certain keys, specified by a JSON Path specification, to be excluded from rendering.

Version 1.16.11

Removed debugging code left in, pointed out by Kevin Landreth <https://github.com/CrackerJackMack>.

Version 1.16.10

iamdbychkov added the :encoding: directive option. This option allows explicit control of the encoding used to read a file instead of relying on the operating system default.

Version 1.16.9

Bugfix.

Version 1.16.8

Jens Nielsen improved rendering of string values.

Version 1.16.5-6

Bugfix version.

Version 1.16.4

Introduces the :lift_title: directive option suggested by ankostis. Ankostis also provided an example on how to extend the formatter to handle custom properties.

Fixed a bug in rendering the items attribute of the array type reported by nijel (https://github.com/nijel).

Version 1.16.1-3

Fixed bugs rendering the default and examples keywords.

Introduced the configuration entry jsonschema_options setting default values for the directive options introduced in 1.16. The options now can accept a parameter to explicitly turn the option on or off.

Version 1.16

WouterTuinstra reimplemented support for dependencies and properly this time. He also improved error handling and reporting and added a couple of options improving the handling of references.

The most important additions are the directive options :lift_description:, :lift_definitions:, :auto_target: and :auto_reference:.

In addition to all that he also implemented support for the if, then and else keywords.

Version 1.15

Add support for the dependencies key.

Versions 1.12 and 1.13 and 1.14

Solved several minor bugs.

Version 1.11

Solved a divergence of the standard reported by bbasic (https://github.com/bbasics).

Version 1.10

Ivan Vysotskyy contributed the idea to use an array with the description key resulting in the new $$description key.

Version 1.9

Tom Walter contributed the example support.

Version 1.4

Chris Holdgraf contributed Python3 and yaml support.

Version 1.3

Add unicode support.

Version 1.2

Improved formatting.

Version 1.1

Implemented schema cross referencing.

Version 1.0

Initial release of a functioning plugin.

Metadata

Release files for sphinx-jsonschema 1.20.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinx-jsonschema 1.20.0
File	Size	Uploaded
sphinx_jsonschema-1.20.0.tar.gz	36.1 kB	Oct 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sphinx-jsonschema 1.20.0
File	Interpreter	ABI	Platform	Reset
sphinx_jsonschema-1.20.0-py3-none-any.whl 31.9 kB Oct 18, 2026	Python 3	none	any	Details

Total release size: 68.0 kB

Release files / sphinx_jsonschema-1.20.0.tar.gz

Download URL	sphinx_jsonschema-1.20.0.tar.gz
Size	36.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`472631960973368790afef549325b5faeab1a9ed205f5f14b753c4c2d62045ba`
BLAKE2b-256 checksum How to use checksums	`46edb79006c9ca60ea065b92d0df1864f825578c47868533a35c70a1939d5602`
Upload date	Oct 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.7`

Release files / sphinx_jsonschema-1.20.0-py3-none-any.whl

Download URL	sphinx_jsonschema-1.20.0-py3-none-any.whl
Size	31.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`84c94d08bb0ebcff2cdc96c9eb5372153270f16f342776f48856b5b1d1f17732`
BLAKE2b-256 checksum How to use checksums	`e070c78e2e81275f0500c5c6b99eca91e20f6225ea1afbaebaf0c7c4e6ff8d52`
Upload date	Oct 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.7`