Registry / serialization / jsonschema2md

jsonschema2md

library1.7.0pypypi✓ verified 22d ago

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.

serialization

pip install jsonschema2md

github ↗package ↗

INSTALL

IMPORT

SIG · JSONSCHEMA2MD

jsonschema2md

serializationpythonv1.7.0

Install

9.9s avg

Import

402ms

Disk

52MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.7.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.414s · 53.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 9.9s · import 0.390s · 55MB

52MB installed

● package 52MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ import jsonschema2md parser = jsonschema2md.Parser()

The main functionality is encapsulated within the Parser class, which is imported directly from the top-level package.

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

jsonschema2md --version

Debug

Known issues

gotchaThere 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.

affects: All versions

gotchaWhile `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.

affects: All versions

breakingPrior 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.

affects: <1.7.0

gotchaBy 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.

affects: >=1.5.2

gotchaLocalization 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.

affects: <1.6.0

Errors

Common errors & fixes

TypeError: Non-object type found in properties list: 'name: obj'

This error occurs when the jsonschema2md parser expects a JSON object in a schema's 'properties' or 'definitions' section but encounters a non-object type (e.g., a string, number, or array).

fix

Ensure that all entries within the 'properties' or 'definitions' section of your JSON schema are valid JSON objects, even if they describe a simple type; they must be structured as an object with at least a 'type' key.

ValueError: 'show_examples` option should be one of `{"all", "object", "properties"}`; `{show_examples}` was passed.

This error indicates that an invalid value was provided for the 'show_examples' parameter when initializing the jsonschema2md.Parser or using the command-line interface.

fix

Set the 'show_examples' parameter to one of the allowed string values: 'all', 'object', or 'properties'.

$ref resolution issues (e.g., 'unresolved reference', 'recursive $ref not working')

The jsonschema2md parser may struggle to correctly resolve JSON $ref references, especially with relative paths, external schema files, or complex deeply nested/recursive references, leading to incomplete or incorrect markdown output.

fix

Verify that all $ref paths are correct and accessible. For external files, ensure they are in the expected directory structure or provide a base URI if necessary. Simplify complex or deeply nested schemas, and ensure there are no unresolvable circular references.

jsonschema2md hanging or getting stuck during generation

This problem typically arises with very large, complex, or highly interconnected JSON schemas that contain numerous $ref references or deep nesting, causing the generation process to consume excessive resources or enter an infinite loop.

fix

Break down large schemas into smaller, more manageable files. Review the schema for overly complex or unintended recursive definitions that could lead to performance bottlenecks or processing hangs. Ensure that circular references are properly handled or avoided where possible.

Upgrade

Version history

1.7.0latest on PyPI · released Aug 14, 2025

Audit

Dependencies

pythonrequiredRequired runtime environment

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/sbrunner/jsonschema2md ↗

packagehttps://pypi.org/project/jsonschema2md/ ↗