Skip to main content

Convert JSON Schema to human-readable Markdown documentation

Project description

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)

pre-commit hook

You can use the pre-commit hook with:

repos:
  - repo: https://github.com/sbrunner/jsonschema2md
    rev: <version> # Use the ref you want to point at
    hooks:
      - id: jsonschema2md
        files: schema.json
        args:
          - --pre-commit
          - schema.json
          - schema.md

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.

Install the pre-commit hooks:

pip install pre-commit
pre-commit install --allow-missing-config

Changelog

See Changelog.md.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonschema2md2-1.3.0.tar.gz (9.8 kB view details)

Uploaded Source

Built Distribution

jsonschema2md2-1.3.0-py3-none-any.whl (10.3 kB view details)

Uploaded Python 3

File details

Details for the file jsonschema2md2-1.3.0.tar.gz.

File metadata

  • Download URL: jsonschema2md2-1.3.0.tar.gz
  • Upload date:
  • Size: 9.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for jsonschema2md2-1.3.0.tar.gz
Algorithm Hash digest
SHA256 bef70345aab7cc084de208d3642a6a94e07d294796e2ca325283e566f3b36805
MD5 e2d700e4f4d6f7a2f2834c8733b32dde
BLAKE2b-256 3e7b838d832b3a13b7e6514489b16dd7fa62389fccdcc68feaa765ffe38e01c8

See more details on using hashes here.

File details

Details for the file jsonschema2md2-1.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for jsonschema2md2-1.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 abe817c90bb37d1b06159267b6a0a3da055050ebb82e158d89b9d21c9229687a
MD5 10d74f0dfd31bff132ff402fdacb330e
BLAKE2b-256 d917a3768133b0b51980b935988f6d7a364f3ddf22a149005a82bb044564b593

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page