JSON Schema for Humans (coveooss/json-schema-for-humans)

JSON Schema for Humans

https://github.com/coveooss/json-schema-for-humans
Admin
JSON Schema for Humans generates beautiful static HTML or Markdown documentation from JSON schemas...

Tokens:105,443
Snippets:620
Trust Score:8.2
Update:5 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# JSON Schema for Humans

JSON Schema for Humans is a Python library and command-line tool that converts JSON Schema documents into beautiful, human-readable HTML or Markdown documentation. The tool supports JSON Schema Draft-07 and provides multiple customizable templates for rendering documentation. It handles complex schema features including circular references, nested definitions, pattern properties, and conditional subschemas, making it ideal for API documentation and schema visualization.

The library generates static documentation that can be easily hosted without requiring a server, making it faster to load and simpler to deploy. It supports both JSON and YAML schema formats as input and offers extensive configuration options for customizing the output appearance and behavior. The tool can process single schema files, entire directories, or glob patterns, making it flexible for projects of any size.

## CLI Command: generate-schema-doc

Command-line interface for generating schema documentation from JSON/YAML files.

```bash
# Generate HTML documentation from a single schema
generate-schema-doc schema.json output.html

# Generate documentation from all schemas in a directory
generate-schema-doc schemas/ output_docs/

# Use a specific template
generate-schema-doc schema.json output.html --config template_name=js

# Use a configuration file
generate-schema-doc schema.json output.html --config-file config.yaml

# Multiple inline configuration options
generate-schema-doc schema.json output.html \
  --config expand_buttons=true \
  --config description_is_markdown=true \
  --config template_name=md

# Process multiple schemas with glob pattern
generate-schema-doc "schemas/**/*.json" output_docs/

# Markdown output with badges
generate-schema-doc api-schema.json api-docs.md --config template_name=md
```

## Function: generate_from_filename

Generates schema documentation from a file path and writes to an output file.

```python
from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration

# Basic usage with default settings
generate_from_filename("my_schema.json", "schema_doc.html")

# Custom configuration
config = GenerationConfiguration(
    copy_css=False,
    expand_buttons=True,
    description_is_markdown=True,
    template_name="js"
)
generate_from_filename("my_schema.json", "schema_doc.html", config=config)

# Generate markdown documentation
config_md = GenerationConfiguration(template_name="md")
generate_from_filename("api_schema.json", "api_docs.md", config=config_md)

# Multiple schemas with configuration
import glob
from pathlib import Path

config = GenerationConfiguration(
    expand_buttons=True,
    show_breadcrumbs=True,
    link_to_reused_ref=True
)

output_dir = Path("docs")
output_dir.mkdir(exist_ok=True)

for schema_file in glob.glob("schemas/*.json"):
    output_file = output_dir / f"{Path(schema_file).stem}.html"
    generate_from_filename(schema_file, str(output_file), config=config)
```

## Function: generate_from_schema

Returns rendered schema documentation as a string without writing to disk.

```python
from json_schema_for_humans.generate import generate_from_schema
from json_schema_for_humans.generation_configuration import GenerationConfiguration

# Basic usage - returns HTML string
html_output = generate_from_schema("my_schema.json")
print(html_output)

# With custom configuration
config = GenerationConfiguration(
    template_name="md",
    description_is_markdown=True,
    collapse_long_descriptions=False
)
markdown_output = generate_from_schema("api_schema.json", config=config)

# Use in a web framework
from flask import Flask, render_template_string

app = Flask(__name__)

@app.route('/schema-docs')
def schema_docs():
    config = GenerationConfiguration(template_name="js")
    doc_html = generate_from_schema("schemas/api.json", config=config)
    return doc_html

# Pre-load schemas for performance
import json

with open("my_schema.json") as f:
    loaded_schema = json.load(f)

loaded_schemas = {
    "/path/to/my_schema.json": loaded_schema
}

html_output = generate_from_schema(
    "my_schema.json",
    loaded_schemas=loaded_schemas,
    config=GenerationConfiguration(link_to_reused_ref=True)
)
```

## Function: generate_from_file_object

Generates documentation from open file objects for both input and output.

```python
from json_schema_for_humans.generate import generate_from_file_object
from json_schema_for_humans.generation_configuration import GenerationConfiguration

# Basic usage with file objects
with open("schema.json", "r", encoding="utf-8") as schema_file:
    with open("output.html", "w", encoding="utf-8") as output_file:
        generate_from_file_object(schema_file, output_file)

# With configuration
config = GenerationConfiguration(
    expand_buttons=True,
    copy_css=True,
    copy_js=True,
    template_name="js_offline"
)

with open("api_schema.json", "r", encoding="utf-8") as schema_file:
    with open("api_docs.html", "w", encoding="utf-8") as output_file:
        generate_from_file_object(schema_file, output_file, config=config)

# Process from memory or stream
from io import StringIO
import json

# Schema as string
schema_dict = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0}
    }
}

schema_str = json.dumps(schema_dict, indent=2)
schema_file = StringIO(schema_str)
output_file = StringIO()

config = GenerationConfiguration(template_name="flat")
generate_from_file_object(schema_file, output_file, config=config)

html_result = output_file.getvalue()
print(html_result)
```

## Class: GenerationConfiguration

Configuration object for customizing documentation generation behavior and appearance.

```python
from json_schema_for_humans.generation_configuration import GenerationConfiguration
from json_schema_for_humans.generate import generate_from_filename

# Full configuration example
config = GenerationConfiguration(
    # HTML minification
    minify=True,

    # Markdown support in descriptions
    description_is_markdown=True,
    allow_html_description=False,
    description_safe_mode="escape",

    # UI features
    expand_buttons=True,
    show_breadcrumbs=True,
    collapse_long_descriptions=True,
    collapse_long_examples=True,
    show_toc=True,

    # Reference handling
    link_to_reused_ref=True,
    recursive_detection_depth=25,

    # Asset copying
    copy_css=True,
    copy_js=True,

    # Template selection
    template_name="js",  # Options: "js", "js_offline", "flat", "md"

    # Footer
    with_footer=True,
    footer_show_time=True,

    # Examples format
    examples_as_yaml=False,

    # Markdown-specific options
    template_md_options={
        "badge_as_image": False,
        "show_heading_numbers": True,
        "show_array_restrictions": True,
        "properties_table_columns": [
            "Property", "Pattern", "Type", "Deprecated",
            "Definition", "Title/Description"
        ]
    }
)

generate_from_filename("schema.json", "output.html", config=config)

# Template-specific configurations

# 1. Interactive JavaScript template
js_config = GenerationConfiguration(
    template_name="js",
    expand_buttons=True,
    collapse_long_descriptions=True,
    copy_css=True,
    copy_js=True
)

# 2. Offline-ready template (bundled assets)
offline_config = GenerationConfiguration(
    template_name="js_offline",
    expand_buttons=True,
    show_breadcrumbs=True
)

# 3. Simple flat HTML (no JavaScript)
flat_config = GenerationConfiguration(
    template_name="flat",
    description_is_markdown=True,
    show_toc=True
)

# 4. Markdown output
md_config = GenerationConfiguration(
    template_name="md",
    template_md_options={
        "badge_as_image": True,
        "show_heading_numbers": True
    }
)

# Load from YAML/JSON file
import yaml

with open("jsfh-config.yaml", "r") as f:
    config_dict = yaml.safe_load(f)

config = GenerationConfiguration.from_dict(config_dict)
```

## Function: get_final_config

Merges configuration from multiple sources with CLI parameter overrides.

```python
from json_schema_for_humans.generation_configuration import get_final_config

# Load from file with CLI overrides
config = get_final_config(
    deprecated_from_description=False,
    default_from_description=False,
    expand_buttons=False,
    link_to_reused_ref=True,
    copy_css=True,
    copy_js=True,
    config="config.yaml",  # Path to config file
    config_parameters=["template_name=md", "expand_buttons=true"]
)

# Programmatic configuration with overrides
config = get_final_config(
    deprecated_from_description=True,
    default_from_description=True,
    expand_buttons=True,
    link_to_reused_ref=True,
    config_parameters=[
        "description_is_markdown=true",
        "collapse_long_descriptions=false",
        "template_name=js_offline"
    ]
)

# Configuration file example (config.yaml):
# description_is_markdown: true
# expand_buttons: true
# copy_js: false
# template_name: js
# template_md_options:
#   badge_as_image: true
#   show_heading_numbers: true
```

## Schema Processing: get_schemas_to_render

Internal function that resolves schema files and output paths for processing.

```python
from json_schema_for_humans.schema.schema_importer import get_schemas_to_render
from pathlib import Path

# Single schema file
schemas = get_schemas_to_render("my_schema.json", Path("output.html"), "html")
# Returns: [SchemaToRender(schema_file="my_schema.json", output_file=Path("output.html"), ...)]

# Directory of schemas
schemas = get_schemas_to_render("schemas/", Path("docs/"), "html")
# Processes all .json, .yaml, .yml files in directory

# Glob pattern
schemas = get_schemas_to_render("schemas/**/*.json", Path("docs/"), "html")
# Recursively finds all JSON schemas

# Multiple comma-separated paths
schemas = get_schemas_to_render(
    "schema1.json,schemas/,patterns/**/*.yaml",
    Path("output/"),
    "md"
)
```

## Example: Complete Documentation Pipeline

End-to-end workflow for documenting multiple API schemas with custom styling.

```python
from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration
from pathlib import Path
import glob

# Setup
docs_dir = Path("api-docs")
docs_dir.mkdir(exist_ok=True)

# Configuration for public API documentation
public_config = GenerationConfiguration(
    template_name="js",
    description_is_markdown=True,
    expand_buttons=True,
    show_breadcrumbs=True,
    collapse_long_descriptions=True,
    collapse_long_examples=True,
    link_to_reused_ref=True,
    with_footer=True,
    footer_show_time=True,
    copy_css=True,
    copy_js=True
)

# Configuration for internal markdown docs
internal_config = GenerationConfiguration(
    template_name="md",
    description_is_markdown=True,
    show_toc=True,
    template_md_options={
        "badge_as_image": False,
        "show_heading_numbers": True,
        "show_array_restrictions": True
    }
)

# Process API schemas
api_schemas = glob.glob("schemas/api/**/*.json", recursive=True)
for schema_path in api_schemas:
    schema_name = Path(schema_path).stem
    output_html = docs_dir / "api" / f"{schema_name}.html"
    output_html.parent.mkdir(parents=True, exist_ok=True)

    print(f"Generating: {output_html}")
    generate_from_filename(schema_path, str(output_html), config=public_config)

# Process internal schemas to markdown
internal_schemas = glob.glob("schemas/internal/**/*.json", recursive=True)
for schema_path in internal_schemas:
    schema_name = Path(schema_path).stem
    output_md = docs_dir / "internal" / f"{schema_name}.md"
    output_md.parent.mkdir(parents=True, exist_ok=True)

    print(f"Generating: {output_md}")
    generate_from_filename(schema_path, str(output_md), config=internal_config)

print(f"\nDocumentation generated in: {docs_dir}")

# Example schema structure that works well:
example_schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://example.com/api.schema.json",
    "title": "User API",
    "description": "API for user management operations",
    "type": "object",
    "required": ["id", "email"],
    "properties": {
        "id": {
            "type": "integer",
            "description": "Unique user identifier",
            "minimum": 1
        },
        "email": {
            "type": "string",
            "format": "email",
            "description": "User email address"
        },
        "roles": {
            "type": "array",
            "description": "User roles",
            "items": {
                "$ref": "#/definitions/Role"
            },
            "minItems": 1,
            "uniqueItems": True
        }
    },
    "definitions": {
        "Role": {
            "type": "string",
            "enum": ["admin", "user", "guest"],
            "description": "Available user roles"
        }
    }
}
```

## Summary

JSON Schema for Humans is primarily used for generating static documentation from JSON Schema files for API documentation, configuration file documentation, and data model visualization. The tool excels at handling complex schemas with references, recursive structures, and conditional logic, making schemas accessible to non-technical stakeholders. Its static output approach ensures fast loading times and easy integration into existing documentation workflows without requiring backend infrastructure.

The library offers multiple integration patterns: CLI for CI/CD pipelines and build processes, Python API for dynamic documentation generation in web applications, and batch processing for large-scale schema documentation projects. With support for multiple output formats (HTML with JavaScript, static HTML, and Markdown) and extensive customization options through the GenerationConfiguration class, it adapts to various documentation needs from interactive web docs to GitHub-rendered markdown files. The tool's support for circular references, pattern properties, and conditional subschemas makes it suitable for documenting even the most complex API specifications.