Directive

The extension adds a single directive to Sphinx: jsonschema. You provide it with either a file name, an HTTP(S) URL to a schema or you may embed the schema inline.

The schemas are read by a YAML parser. This means that you can write the schemas in either json or yaml notation and they will be processed identically.

Usage

To display a schema fetched from a website:

.. jsonschema:: http://example.com/project/schema.json

To display a schema in a file referenced by an absolute path use:

.. jsonschema:: /var/www/project/schema.json

or with a path relative to the current document:

.. jsonschema:: schemas/sample.json

this assumes that next to the .rst file containing the above statement there is a subdirectory schemas containing sample.json.

With any of the above references you can use JSON Pointer notation to display a subschema:

.. jsonschema:: http://example.com/project/schema.json#/definitions/sample

.. jsonschema:: /var/www/project/schema.json#/definitions/sample

.. jsonschema:: schemas/sample.json#/definitions/sample

Alternatively you can embed the schema directly into your documentation:

.. jsonschema::

    {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "An example",
        "id": "http://example.com/schemas/example.json",
        "description": "This is just a tiny example of a schema rendered by `sphinx-jsonschema <http://github.com/lnoor/sphinx-jsonschema>`_.\n\nYes that's right you can use *reStructuredText* in a description.",
        "type": "string",
        "minLength": 10,
        "maxLength": 100,
        "pattern": "^[A-Z]+$"
    }

which should render as:

An example

http://example.com/schemas/example.json

This is just a tiny example of a schema rendered by sphinx-jsonschema.

Yes that’s right you can use reStructuredText in a description.

type string
maxLength 100
minLength 10
pattern ^[A-Z]+$

It is also possible to render just a part of an embedded schema using a json pointer (per request Issue 17:

.. jsonschema:: #/date

    {
        "title" : "supertitle1",
        "type": "object",
        "properties": {
            "startdate": {"$ref": "#/date"},
            "enddate": {"$ref": "#/date"},
            "manualdate_to1": {"$ref" : "#/manualdate"},
            "definitions1": {"$ref" : "#/definitions/bind"},
            "definitions3": {"$ref" : "#/locbind"}
        },
        "date": {
            "title": "Date",
            "$$target": ["#/date"],
            "description": "YYYY-MM-DD",
            "type": "string"
        }
    }

which renders:

Date

YYYY-MM-DD
type string

Options

There a couple of options implemented in sphinx-jsonschema that control the way a schema is rendered or processed. These options are:

lift_title (default: True)
Uses the title to create a new section in your document and creates an anchor you can refer to using jsonschema’s $ref or ReStructuredText’s :ref: notation. When False the title becomes part of the table rendered from the schema, the table cannot be referenced and the option :lift_description: is ignored.
lift_description (default: False)
Places the description between the title and the table rendering the schema. This option is ignored when :lift_title: is False.
lift_definitions (default: False)
Removed the items under the definitions key and renders each of them separately as if they are top-level schemas.
auto_target (default: False)
Automatically generate values for the $$target key. Especially useful in combination with :lift_definitions:.
auto_reference (default: False)
Automatically resolves references when possible. Works well with :auto_target: and :lift_definitions:.
encoding (default: None)
Allows you to define the encoding used by the file containing the json schema.

Lift Title

By default the schema’s top level title is displayed above the table containing the remainder of the schema. This title becomes a section that can be included in the table of contents and the index. It is also used to resolve references to the schema from either other schemas of from elsewhere in the documentation.

This option mainly exists to suppress this behaviour. One place where this is desirable is when using jsonschema to validate and document function parameters. See issue 48 for an example.

Lift Description

Lifts the description from the table and places it between the title and the table. You will need to have a title defined and the flag :lift_description: otherwise it will be included into the table:

which renders:

Example Separate Description

This is just a tiny example of a schema rendered by sphinx-jsonschema.

Whereby the description can shown as text outside the table, and you can still use reStructuredText in a description.

http://example.com/schemas/example.json
type string
maxLength 100
minLength 10
pattern ^[A-Z]+$

Lift Definitions

To separate the definitions from the table you will need to have the flag :lift_definitions: included. For each item inside the definitions it will make a new section with title and a table of the items inside. It’s advised to also use the :auto_reference: flag to auto link $ref to a local definitions title.

.. jsonschema::
    :lift_definitions:

    {
        "title": "Example with definitions",
        "definitions": {
            "football_player": {
                "type": "object",
                "required": ["first_name", "last_name", "age"],
                "properties": {
                    "first_name": {"type": "string"},
                    "last_name": {"type": "string"},
                    "age": {"type": "integer"}
                }
            },
            "football_team": {
                "type": "object",
                "required": ["team", "league"],
                "properties": {
                    "team": {"type": "string"},
                    "league": {"type": "string"},
                    "year_founded": {"type": "integer"}
                }
            }
        }
    }

which renders:

Example with definitions

football_player
type object
properties
  • first_name
type string
  • last_name
type string
  • age
type integer
football_team
type object
properties
  • team
type string
  • league
type string
  • year_founded
type integer

Auto Target and Reference

With the :auto_target: flag there will be a target created with filename and optional pointer. When you would include auto target on multiple JSON schemas with identical file names it will cause a conflict within your build only the last build target will be used by the references. This also applies if you would embed the schema directly into your documentation; in that case the document name is used as the file name.

With the :auto_reference: flag there will be more logic applied to reduce the amount of undefined label warnings. It will check if it is referencing to itself and if there would be a title to link to, when there are titles in the same page that have an identical name it will cause linking issues. If you didn’t separate definitions from the schema the $ref will become a text field without a linked reference. If the $ref would point to an other schema from the path it will extract the filename it expected to be included into your documentation with :auto_target:.

Mainly the :auto_reference: flag influences behavior of the existing $$target method and could potentially break links.

See below the schema whereby both options are included. For each section it will create a target in this example filename of the document as the schema is added as context and it’s pointer if there would be one.
Example of Target & Reference this link as raw text using reStructuredText format would be: :ref:`directive.rst`.
And for the definition person the raw text would be: :ref:`directive.rst#/definitions/person`.
.. jsonschema::
    :lift_definitions:
    :auto_reference:
    :auto_target:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title":  "Example of Target & Reference",
    "type": "object",
    "properties": {
        "person": { "$ref": "#/definitions/person" }
    },
    "definitions": {
        "person": {
            "type": "object",
            "properties": {
                "name": { "type": "string" },
                "children": {
                    "type": "array",
                    "items": { "$ref": "#/definitions/person" },
                    "default": []
                }
            }
        }
    }
}

which renders:

Example of Target & Reference

type object
properties
  • person
person
person
type object
properties
  • name
type string
  • children
type array
default  
items person

Setting default values

When you want to use the options :lift_definitions: :lift_description, :auto_target and :auto_reference in most schema renderings it is more convenient to set them once for your whole project.

The conf.py option jsonschema_options lets you do so. It takes a dict as value the boolean valued keys of which have the same name as the options.

So, in conf.py you can state: .. code-block:: py

jsonschema_options = {
‘lift_description’: True, ‘aut_reference’: True

}

By default all four options are False.

Overruling defaults

The default values for the options can be overruled by setting the directive options. They accept an optional argument which can be one of the words On, Off, True or False. The default value for the argument is True.

Declare file encoding

The :encoding: option allows you to define the encoding used by the file containing the json schema. When the operating system default encoding does not produce correct results then this option allows you to specify the encoding to use. When omitted the operating system default is used as it always has been. But it is now possible to explicitly declare the expected encoding using :encoding: utf8. You can use any encoding defined by Python’s codecs for your platform.