Sphinx JSON Schema

Common errors

• WARNING: extension 'sphinx-jsonschema' not found

  cause The `sphinx-jsonschema` extension has not been added to the `extensions` list in your Sphinx project's `conf.py` file, or there's a typo in the name.
  fix Open your `conf.py` file and ensure `'sphinx-jsonschema'` is present in the `extensions` list: `extensions = ['sphinx-jsonschema']`.

• Sphinx does not understand JSON Pointer syntax.

  cause This error occurs if you are trying to use JSON Pointer syntax in a context where Sphinx itself (not the `jsonschema` directive) is trying to interpret a file path, or if the `jsonschema` directive's JSON Pointer is malformed.
  fix Ensure you are using JSON Pointer notation correctly *within* the `jsonschema` directive, for example: `.. jsonschema:: my_schema.json#/definitions/MyType`. Sphinx's core `include` directive does not understand JSON Pointers.

• FileNotFoundError: [Errno 2] No such file or directory: 'your_schema.json'

  cause The path provided to the `jsonschema` directive for a local file is incorrect or the file does not exist at that location relative to the `.rst` document or absolute path provided.
  fix Verify the file path. For relative paths, ensure the schema file is accessible from the `.rst` document's location. For absolute paths, double-check the full path. Ensure file permissions allow reading.

• ValueError: Invalid JSON schema: <some-json-parse-error>

  cause The schema file (JSON or YAML) provided to the `jsonschema` directive contains syntax errors, preventing it from being parsed correctly.
  fix Carefully review your JSON or YAML schema file for syntax errors (e.g., missing commas, unclosed brackets, invalid YAML indentation). Use a linter or validator for the respective format to identify and fix issues.

Warnings

• gotcha sphinx-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.
  Fix: Be 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.
• gotcha The 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.
  Fix: Ensure 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.
• gotcha While 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.
  Fix: Test 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.
• gotcha Strings 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.
  Fix: Use 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`.

Install

• pip install sphinx-jsonschema Install from PyPI
• # In your Sphinx project's conf.py file: extensions = [ 'sphinx.ext.autodoc', 'sphinx-jsonschema' ] Enable in Sphinx conf.py

Imports

• '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.

Quickstart

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
   }