sphinxcontrib-opendataservices-jsonschema¶

A JSON Schema widget for Sphinx.

This takes a JSON Schema file and displays it as a human readable table.

Installation¶

Make sure this Python package is installed via Pypi or another mechanism.

Add it as an extension to the Sphinx site - so in the conf.py file, add:

extensions = ['sphinxcontrib.jsonschema']

It should now be ready to use.

Use¶

This provides a single directive, jsonschema:

.. jsonschema:: ../_build_schema/components.json

Required: Path to the JSON Schema file¶

You must pass the path to the JSON Schema file to the widget.

.. jsonschema:: ../_build_schema/components.json

Option: include¶

You can pass the optional setting include.

.. jsonschema:: example_schema.json
   :include: id,name,age/actual

Only the keys listed will be shown.

Option: collapse¶

You can pass the optional setting collapse.

.. jsonschema:: example_schema.json
   :collapse: age

If passed, then any schema below the passed key will not be shown.

Option: pointer¶

You can pass the optional setting pointer.

.. jsonschema:: example_schema.json
   :pointer: /properties/address

You can use this to only show a section of the JSON Schema - in this case, only the section underneath /properties/address will be shown.

Note the key here is the key is the key in the JSON Schema not the key in the JSON data. This means you can pass keys like /definitions/Address.

Option: nocrossref¶

You can pass the optional flag nocrossref.

.. jsonschema:: example_schema.json
   :nocrossref:

By default, if an item has a $ref property then some text will be added to the Description with a link to a HTML anchor.

If you don’t want this, pass this flag to disable this.

Option: externallinks¶

You can pass a dictionary of dictionaries to this.

.. jsonschema:: example_schema.json
   :externallinks: {"formalname":{"url":"https://en.wikipedia.org/wiki/Butler","text":"A guide on how to use formal names"}}

For every property included, a extra link will be included with the URL and text specified in the description section.

Option: allowexternalrefs¶

You can pass the optional flag allowexternalrefs.

.. jsonschema:: example_schema_with_external_refs.json
   :allowexternalrefs:

If passed, you can use $ref to load remote files and they will be loaded.

If not passed, any remote references will silently be ignored.

Examples¶

Schema files for these examples¶

You can see the schema files used for these examples:

Basic Example¶

.. jsonschema:: example_schema.json

Title	Description	Type
`id`		string
Identifier
`name`		string
Name	A casual name for this person
`formalname`		string
Formal Name	A formal name for this person
`age`		object
The person’s age
`age/actual`		number
Actual Age
`age/admitted`		number
Admitted Age
`address`		object
Address	Where this person lives See Address

With include option¶

.. jsonschema:: example_schema.json
   :include: id,name,age/actual

Title	Description	Type
`id`		string
Identifier
`name`		string
Name	A casual name for this person
`age/actual`		number
Actual Age

With collapse option¶

.. jsonschema:: example_schema.json
   :collapse: age

Title	Description	Type
`id`		string
Identifier
`name`		string
Name	A casual name for this person
`formalname`		string
Formal Name	A formal name for this person
`age`		object
The person’s age
`address`		object
Address	Where this person lives See Address

With pointer option¶

.. jsonschema:: example_schema.json
   :pointer: /definitions/Address

Title	Description	Type	Format	Required
`address`		string
Address Details
`postcode`		string
Postcode
`country`		string
Country

With nocrossref flag¶

.. jsonschema:: example_schema.json
   :nocrossref:

Title	Description	Type
`id`		string
Identifier
`name`		string
Name	A casual name for this person
`formalname`		string
Formal Name	A formal name for this person
`age`		object
The person’s age
`age/actual`		number
Actual Age
`age/admitted`		number
Admitted Age
`address`		object
Address	Where this person lives

With externallinks option¶

.. jsonschema:: example_schema.json
   :include: formalname
   :externallinks: {"formalname":{"url":"https://en.wikipedia.org/wiki/Butler","text":"A guide on how to use formal names"}}

Title

Description

Type

Format

Required

formalname

string

Formal Name

A formal name for this person

See A guide on how to use formal names

With allowexternalrefs option¶

.. jsonschema:: example_schema_with_external_refs.json
   :allowexternalrefs:

Title	Description	Type
`id`		string
Identifier
`name`		string
Name	The name for this person
`address`		object
Address	Where this person lives See Address
`address/address`		string
Address Details
`address/postcode`		string
Postcode
`address/country`		string
Country

Developers¶

The documentation for this widget directly includes use of this extension in the example pages!

To build these locally, create a new virtual environment then run:

pip install -r requirements_dev.txt
python -m sphinx docs/ docs/_out/

As well as providing documentation for others (always good!) this also provides a nice development environment for when you are working on bugs or new features. Set up an example that should show your work; build the docs; see if your code worked!

To make these docs build on Read The Docs, you need to:

Set requirements_dev.txt as a Requirements file
Disable Enable PDF build
Disable Enable EPUB build