jsonschema2md

1.7.0 · active · verified Mon Apr 13

jsonschema2md is a Python library designed to convert JSON Schema definitions into human-readable Markdown documentation. It is actively maintained, with frequent updates that introduce new features and improvements, currently at version 1.7.0. It simplifies the process of generating clear and structured documentation directly from your JSON Schema files.

Warnings

gotcha There is a similarly named and purposed JavaScript/Node.js package (`@adobe/jsonschema2md`). Ensure you are installing the Python `jsonschema2md` package via `pip` (from PyPI) and importing `jsonschema2md`, to avoid confusion with the Node.js ecosystem tool.
Fix: Always verify installation method (`pip`) and import statements for the Python package.
gotcha While `jsonschema2md` supports JSON Schema 2019-09, it does not implement the full vocabulary. Certain less common keywords might not be processed or rendered as expected. Always check the official documentation or test suite for a precise list of supported JSON Schema keywords.
Fix: Consult the library's GitHub repository or documentation for a list of supported JSON Schema keywords if encountering unexpected output for specific schema features.
breaking Prior to version 1.7.0, support for external references (`$ref` pointing to external files or URLs) was limited or non-existent. Schemas relying heavily on external references might not have been correctly processed.
Fix: Upgrade to version 1.7.0 or newer to ensure robust handling of external references.
gotcha By default, deprecated fields within your JSON Schema are included in the generated Markdown. If you wish to suppress these, you must explicitly pass `show_deprecated=False` to the `jsonschema2md.Parser` constructor.
Fix: Initialize the parser with `parser = jsonschema2md.Parser(show_deprecated=False, ...)` to hide deprecated fields.
gotcha Localization support for generating Markdown in languages other than English was introduced in version 1.6.0. Users requiring localized output (e.g., French or Portuguese) must use version 1.6.0 or later and specify the desired locale.
Fix: Upgrade to version 1.6.0 or newer and use the appropriate configuration for localization.

Install

pip install jsonschema2md Install with pip

Imports

Parser
```
import jsonschema2md
parser = jsonschema2md.Parser()
```
The main functionality is encapsulated within the Parser class, which is imported directly from the top-level package.

Quickstart

This quickstart demonstrates how to instantiate the Parser with basic options, load a JSON Schema, and convert it into Markdown string output. The resulting Markdown can then be written to a file or displayed.

import json
import jsonschema2md

# Example JSON Schema
schema = {
    "$id": "https://example.com/person.schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Person",
    "description": "JSON Schema for a person object.",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string",
            "description": "The person's first name."
        },
        "lastName": {
            "type": "string",
            "description": "The person's last name."
        }
    }
}

# Initialize the parser with desired options
parser = jsonschema2md.Parser(
    examples_as_yaml=False,
    show_examples="all",
    # Add other options as needed, e.g., show_deprecated=False
)

# Parse the schema and get markdown lines
md_lines = parser.parse_schema(schema)

# Join and print the markdown output
print(''.join(md_lines))

view raw JSON →