{"id":9321,"library":"sphinx-jsonschema","title":"Sphinx JSON Schema","description":"sphinx-jsonschema is a Sphinx extension that allows authors to display JSON Schema definitions directly within their documentation. It facilitates embedding schema from HTTP(S) URLs, local files, or Python objects, supporting both JSON and YAML formats. The library is actively maintained, with version 1.19.2 currently available.","status":"active","version":"1.19.2","language":"en","source_language":"en","source_url":"https://github.com/lnoor/sphinx-jsonschema","tags":["Sphinx","documentation","JSON Schema","reStructuredText","extension"],"install":[{"cmd":"pip install sphinx-jsonschema","lang":"bash","label":"Install from PyPI"},{"cmd":"# In your Sphinx project's conf.py file:\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx-jsonschema'\n]","lang":"python","label":"Enable in Sphinx conf.py"}],"dependencies":[{"reason":"Core dependency as it is a Sphinx extension.","package":"Sphinx","optional":false}],"imports":[{"note":"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.","symbol":"'sphinx-jsonschema'","correct":"extensions = ['sphinx-jsonschema'] # in conf.py"}],"quickstart":{"code":"# conf.py\n# ... (other Sphinx configurations)\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx-jsonschema'\n]\n\n# my_schema.json\n{\n  \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n  \"title\": \"Example Product\",\n  \"description\": \"A simple product schema.\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"productId\": {\n      \"type\": \"integer\",\n      \"description\": \"The unique identifier for a product\"\n    },\n    \"productName\": {\n      \"type\": \"string\",\n      \"description\": \"Name of the product\"\n    }\n  },\n  \"required\": [\"productId\", \"productName\"]\n}\n\n# index.rst (or any .rst file)\n.. jsonschema:: my_schema.json\n   :lift_title: True\n   :lift_description: True\n   :encoding: utf-8\n\nAlternatively, embed the schema directly:\n\n.. jsonschema::\n   {\n     \"title\": \"Inline Schema Example\",\n     \"type\": \"string\",\n     \"minLength\": 10\n   }","lang":"python+json+rst","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (especially with newer JSON Schema drafts)"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Open your `conf.py` file and ensure `'sphinx-jsonschema'` is present in the `extensions` list: `extensions = ['sphinx-jsonschema']`.","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.","error":"WARNING: extension 'sphinx-jsonschema' not found"},{"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.","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.","error":"Sphinx does not understand JSON Pointer syntax."},{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'your_schema.json'"},{"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.","cause":"The schema file (JSON or YAML) provided to the `jsonschema` directive contains syntax errors, preventing it from being parsed correctly.","error":"ValueError: Invalid JSON schema: <some-json-parse-error>"}]}