JSON Schema for Humans

1.6.0 · active · verified Sun Apr 12

JSON Schema for Humans is a Python library that generates beautiful, human-readable static HTML documentation from JSON schemas. It helps developers understand complex schema structures at a glance. The project is actively maintained with frequent patch and minor releases, typically on a monthly or quarterly cadence, providing new features and bug fixes.

Warnings

breaking Starting 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`.
Fix: Upgrade your Python environment to 3.9+ or pin `json-schema-for-humans` to a version older than 1.3.1.
gotcha Versions 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.
Fix: Upgrade to `json-schema-for-humans` version `1.4.1` or newer to resolve these deprecation warnings.
gotcha The 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.
Fix: For programmatic use, import functions like `generate` or `generate_from_filename`. For CLI, use `json-schema-for-humans generate <schema_path> <output_dir>`.

Install

pip install json-schema-for-humans Install stable version

Imports

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.

Quickstart

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.")

view raw JSON →