Repository files navigation

This package contains sphinx-jsonschema, an extension to Sphinx to allowauthors to display aJSON Schema in theirdocumentation.

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.

• Near complete support for all features of JSON Schema Draft 4.
• 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 intitle anddescription fields.
• Allows JSON Schema definitions in both JSON and YAML format.
• Supports theexamples keyword from Draft 7.

Install the package using pip:

pip install sphinx-jsonschema

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

extensions = [    'sphinx-jsonschema']

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

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.

$$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 ignores$id but 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 beidentical 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 theschema.

$$description

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

This key serves the same purpose as thedescription key and can be used in the same way.It differs fromdescription in that it allows an array of strings as value instead of asingle 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.

Copyright Leo Noordergraaf, All rights reserved.

This software is made available under the GPL v3.

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

Expanding on the work ofPavel Odvody with JSON Pointerthe: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>

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

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

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

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

Bugfix.

Jens Nielsen improved rendering of string values.

Bugfix version.

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

Fixed a bug in rendering theitems attribute of thearray type reported by nijel (https://github.com/nijel).

Fixed bugs rendering thedefault andexamples keywords.

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

WouterTuinstra reimplemented support fordependencies 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 theif,then andelse keywords.

Add support for thedependencies key.

Solved several minor bugs.

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

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

Tom Walter contributed theexample support.

Chris Holdgraf contributed Python3 and yaml support.

Add unicode support.

Improved formatting.

Implemented schema cross referencing.

Initial release of a functioning plugin.