Install & Compatibility
Where this runs
tested against v1.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.860s · 40.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.826s · 41MB
40MB installed
● package 40MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
generate_from_filename
✓ from json_schema_for_humans.generate import generate_from_filename
generate
✓ from json_schema_for_humans.generate import generate
Use this function if you have the schema as a Python dict/object rather than a file path.
This quickstart demonstrates how to programmatically generate HTML documentation from a JSON schema file. It creates a dummy schema, saves it, and then uses `generate_from_filename` to produce an HTML output directory. You can customize the output using the `config` dictionary.
import json
import os
from json_schema_for_humans.generate import generate_from_filename
# Define a simple JSON schema
schema_data = {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "User Profile",
"description": "Schema for a user profile object.",
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid", "description": "Unique user ID"},
"name": {"type": "string", "minLength": 1, "description": "Full name of the user"},
"email": {"type": "string", "format": "email", "description": "User's email address"},
"age": {"type": "integer", "minimum": 0, "maximum": 150, "description": "User's age"}
},
"required": ["id", "name", "email"]
}
# Create a directory for output and schema
os.makedirs("schema_docs_output", exist_ok=True)
schema_file_path = os.path.join("schema_docs_output", "user_profile.json")
output_dir = os.path.join("schema_docs_output", "html_docs")
# Save the schema to a file
with open(schema_file_path, "w") as f:
json.dump(schema_data, f, indent=2)
# Generate documentation
generate_from_filename(
schema_file_path,
output_dir,
config={
"show_breadcrumbs": True,
"link_to_top": True,
"minify_html": True
}
)
print(f"Documentation for '{schema_file_path}' generated successfully in '{output_dir}'.")
print("You can open index.html in that directory in your browser.")
generate-schema-doc --version
Debug
Known issues
breakingStarting from version 1.3.1, `json-schema-for-humans` requires Python 3.9 or newer. Projects running on older Python versions (e.g., 3.7 or 3.8) will need to upgrade their Python interpreter or stick to `json-schema-for-humans < 1.3.1`.fixUpgrade your Python environment to 3.9+ or pin `json-schema-for-humans` to a version older than 1.3.1.
affects: <1.3.1 to >=1.3.1
gotchaVersions prior to `1.4.1` might emit deprecation warnings from the underlying `BeautifulSoup4` library due to changes in its API. While these are warnings, they can clutter logs.fixUpgrade to `json-schema-for-humans` version `1.4.1` or newer to resolve these deprecation warnings.
affects: <1.4.1
gotchaThe library provides both a command-line interface (CLI) and a programmatic Python API. Ensure you are using the correct interface for your automation needs. The CLI is suitable for simple one-off generation, while the programmatic API offers more control and integration into build pipelines.fixFor programmatic use, import functions like `generate` or `generate_from_filename`. For CLI, use `json-schema-for-humans generate <schema_path> <output_dir>`.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsonschema.compat'
This occurs when an application or a dependency (like json-schema-for-humans) tries to import a module from `jsonschema.compat` which was removed in `jsonschema` version 4.0 and later versions.
fixDowngrade the `jsonschema` package to a version less than 4.0. For example: `pip install 'jsonschema<4.0'`
KeyError: 'some_missing_key'
This error typically arises when the Python code or the `json-schema-for-humans` library attempts to access a key within your JSON schema that does not exist or is misspelled. This can also happen if the schema's structure is not what the library expects, such as incorrect paths in `$ref`s or malformed JSON.
fixInspect your JSON schema file to ensure that all referenced keys exist and the schema adheres to the expected structure. Double-check for typos in key names and ensure proper JSON syntax. If programmatically accessing schema parts, verify the keys exist before access.
Invalid JSON Schema
This indicates that the input file provided to `json-schema-for-humans` is not a valid JSON Schema. This can be due to syntax errors (e.g., missing commas, unquoted property names, incorrect data types) or structural issues that violate the JSON Schema specification.
fixValidate your JSON schema using an online JSON Schema validator or a Python JSON parser (e.g., `json.loads(schema_content)`) to identify and correct any syntax errors or structural inconsistencies. Ensure it conforms to a supported JSON Schema draft.
RecursionError: maximum recursion depth exceeded
This error occurs when your JSON schema contains circular or deeply nested recursive `$ref` definitions, and the `link_to_reused_ref` configuration option is set to `False` (or the default `recursive_detection_depth` is insufficient). The library gets stuck in an infinite loop trying to render the recursive structure without proper linking or depth limit.
fixIt is recommended to keep `link_to_reused_ref` enabled (which is its default behavior) to handle recursive references correctly. If you must disable it, consider increasing the `recursive_detection_depth` configuration option via `--config recursive_detection_depth=<depth>` to a value appropriate for your schema's recursion level.
ModuleNotFoundError: No module named 'json_schema_for_humans'
The `json-schema-for-humans` library is not installed in your current Python environment, or the Python interpreter you are using does not have access to the installed package.
fixInstall the library using pip: `pip install json-schema-for-humans`. If you are using virtual environments, ensure your environment is activated before running the installation or your script.
Upgrade
Version history
1.5.1latest on PyPI · released Nov 21, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.