jsonschema2md

Convert JSON Schemas to simple, human-readable Markdown documentation.

For example:

{
    "$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."
      }
    }
  }

will be converted to:

Person

JSON Schema for a person object.

Properties

firstName (string): The person's first name.

lastName (string): The person's last name.

See the examples directory for more elaborate examples.

Installation

Install with pip

pip install jsonschema2md

Usage

From the CLI

jsonschema2md [OPTIONS] <input.json> <output.md>

From Python

import json
import jsonschema2md

parser = jsonschema2md.Parser(
    examples_as_yaml=False,
    show_examples="all",
)
with open("./examples/food.json", "r") as json_file:
    md_lines = parser.parse_schema(json.load(json_file))
print(''.join(md_lines))

Options

examples_as_yaml: Parse examples in YAML-format instead of JSON. (bool, default: False)
show_examples: Parse examples for only the main object, only properties, or all. (str, default all, options: object, properties, all)

Contributing

Bugs, questions or suggestions? Feel free to post an issue in the issue tracker or to make a pull request! See Contributing.md for more info.

Changelog

See Changelog.md.

ttafsir/jsonschema2md