sbrunner / jsonschema2md Goto Github PK

View Code? Open in Web Editor NEW

This project forked from ralfg/jsonschema2md

15.0 2.0 7.0 442 KB

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

Home Page: https://pypi.org/project/jsonschema2md/

License: Apache License 2.0

Python 100.00%

jsonschema2md's Introduction

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.

jsonschema2md's People

Contributors

Stargazers

Watchers

Forkers

durey ajoga smoy stdedos tofay overboard brynpickering

jsonschema2md's Issues

$ref to other files

As I have multiple object loosely related to each other that are referencing common definitions, I'm exploring using $ref and referencing another file.

I'm getting weird outputs from jsonschema2md2, could this usage not be supported?

I've tried to render the schemas from this tutorial ; I named the files entry-schema.json and fstab.json. Rendered fstab.md yields:

# JSON Schema

## Pattern Properties

- **`^(/[^/]+)+$`**: Refer to *[https://example.com/entry-schema](#tps://example.com/entry-schema)*.
## Properties

- **`/`**: Refer to *[https://example.com/entry-schema](#tps://example.com/entry-schema)*.

I have two questions:

Am I trying to be overkill referencing objects across files? Is this uncommon in practice?
If this is unsupported, what would it take to be supported?

Show which object properties are required or not by default

Would not be amazing to show which object properties are required or not in the generated Markdown?

So this schema:

type: object
required:
  - colours
additionalProperties: false
properties:
  colours:
    [...]
  numbers:
    [...]

would generate a different Markdown than this schema:

type: object
required:
  - colours
  - numbers
additionalProperties: false
properties:
  colours:
    [...]
  numbers:
    [...]

Currently, additionalProperties is taken into account, but required is ignored AFAIK.

Can we add support for the const keyword from draft 6? It's useful especially for "enum" types which have different sets of properties depending on the value of the enum, which we have modeled as an anyOf over multiple different definitions, each with a source property set to a const value. It's model-able as an enum with only one value, but it's not as clean that way (makes the schema definition more verbose and it's not as obvious in the docs what is intended).

It would be nice to see min/max length if property type is String

If there is min/maxLength (Schema def.) set to property if would be nice to see those also in markup page.
For example min=0, max=100
Schema exmaple

properties": {
     "lengthLimited": {
      "description": "LengthLimited field",
      "type": "string",
      "minLength": 0,
      "maxLength": 100
       },...

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

Update dependency camptocamp/c2cciutils to v1.5.9 (0.8)
Update CI dependencies (0.9) (patch) (asottile/pyupgrade, c2cciutils, prettier-plugin-toml, pyjson5)
Update CI dependencies (master) (patch) (asottile/pyupgrade, c2cciutils, pre-commit, prettier, pyjson5)
Update dependency pytest to v8.0.1 (master)
Update CI dependencies (master) (minor) (psf/black, python-jsonschema/check-jsonschema)
Update dependency prospector-profile-duplicated to v1 (master)
Lock file maintenance (master)

Detected dependencies

Branch 0.7

github-actions

.github/workflows/backport.yaml

ubuntu 22.04

.github/workflows/changelog.yaml

actions/checkout v4

actions/cache v3

ubuntu 22.04

.github/workflows/main.yaml

actions/checkout v3

actions/setup-python v4

actions/cache v3

ubuntu 22.04

.github/workflows/pr-checks.yaml

actions/checkout v3

ubuntu 22.04

.github/workflows/pull-request-automation.yaml

actions/github-script v7

actions/github-script v6

actions/github-script v7

actions/github-script v7

actions/github-script v7

ubuntu 22.04

pep621

pyproject.toml

poetry-core >=1.0.0

poetry-dynamic-versioning >=0.19.0

pip_requirements

ci/requirements.txt

c2cciutils ==1.5.9

poetry ==1.4.2

poetry-dynamic-versioning ==0.21.5

poetry-plugin-export ==1.3.1

pre-commit ==3.3.3

setuptools >=65.5.1

requests >=2.31.0

urllib3 >=1.26.17

jinja2 >=3.1.3

poetry

pyproject.toml

python ^3.7.2

importlib_metadata 6.6.0

PyYAML 6.0.1

prospector 1.9.0

pytest 7.3.2

pytest-cov 2.12.1

pydocstyle 5.1.1

pre-commit

.pre-commit-config.yaml

pre-commit/pre-commit-hooks v4.4.0

sbrunner/hooks 0.5.0

codespell-project/codespell v2.2.6

pre-commit/mirrors-prettier v2.7.1

shellcheck-py/shellcheck-py v0.9.0.6

jumanjihouse/pre-commit-hooks 3.0.0

python-jsonschema/check-jsonschema 0.22.0

sirwart/ripsecrets v0.1.7

PyCQA/autoflake v2.1.1

asottile/pyupgrade v3.3.2

PyCQA/isort 5.12.0

psf/black 23.3.0

regex

ci/config.yaml

camptocamp/c2cciutils 1.5.9

.pre-commit-config.yaml

poetry 1.4.2

poetry 1.4.2

prettier 2.8.8

prettier-plugin-sh 0.12.8

prettier-plugin-toml 0.3.5

Branch 0.8

github-actions

.github/workflows/backport.yaml

ubuntu 22.04

.github/workflows/changelog.yaml

actions/checkout v4

actions/cache v3

ubuntu 22.04

.github/workflows/main.yaml

actions/checkout v3

actions/setup-python v4

actions/cache v3

ubuntu 22.04

.github/workflows/pr-checks.yaml

actions/checkout v3

ubuntu 22.04

.github/workflows/pull-request-automation.yaml

actions/github-script v7

actions/github-script v6

actions/github-script v7

actions/github-script v7

actions/github-script v7

ubuntu 22.04

pep621

pyproject.toml

poetry-core >=1.0.0

poetry-dynamic-versioning >=0.19.0

pip_requirements

ci/requirements.txt

c2cciutils ==1.5.9

poetry ==1.4.2

poetry-dynamic-versioning ==0.21.5

poetry-plugin-export ==1.3.1

pre-commit ==3.3.3

setuptools >=65.5.1

requests >=2.31.0

urllib3 >=1.26.17

jinja2 >=3.1.3

cryptography >=42.0.2

poetry

pyproject.toml

python ^3.7.2

importlib_metadata 6.6.0

PyYAML 6.0.1

prospector 1.9.0

pytest 6.2.5

pytest-cov 4.0.0

pydocstyle 5.1.1

pre-commit

.pre-commit-config.yaml

pre-commit/pre-commit-hooks v4.4.0

sbrunner/hooks 0.5.0

codespell-project/codespell v2.2.6

pre-commit/mirrors-prettier v2.7.1

shellcheck-py/shellcheck-py v0.9.0.6

jumanjihouse/pre-commit-hooks 3.0.0

python-jsonschema/check-jsonschema 0.22.0

sirwart/ripsecrets v0.1.7

PyCQA/autoflake v2.1.1

asottile/pyupgrade v3.3.2

PyCQA/isort 5.12.0

psf/black 23.3.0

sbrunner/jsonschema-validator 0.1.0

regex

ci/config.yaml

camptocamp/c2cciutils 1.5.8

.pre-commit-config.yaml

poetry 1.4.2

poetry 1.4.2

prettier 2.8.8

prettier-plugin-sh 0.12.8

prettier-plugin-toml 0.3.5

Branch 0.9

github-actions

.github/workflows/backport.yaml

ubuntu 22.04

.github/workflows/changelog.yaml

actions/checkout v4

actions/cache v3

ubuntu 22.04

.github/workflows/main.yaml

actions/checkout v4

actions/setup-python v4

actions/cache v3

ubuntu 22.04

.github/workflows/pr-checks.yaml

actions/checkout v4

ubuntu 22.04

.github/workflows/pull-request-automation.yaml

actions/github-script v7

actions/github-script v6

actions/github-script v7

actions/github-script v7

actions/github-script v7

ubuntu 22.04

pep621

pyproject.toml

poetry-core >=1.0.0

poetry-dynamic-versioning >=0.19.0

pip_requirements

ci/requirements.txt

c2cciutils ==1.6.15

poetry ==1.6.1

poetry-dynamic-versioning ==1.1.1

poetry-plugin-export ==1.6.0

pre-commit ==3.5.0

poetry-plugin-drop-python-upper-constraint ==0.1.0

poetry-plugin-tweak-dependencies-version ==1.5.2

poetry-dynamic-versioning ==1.1.1

certifi >=2023.7.22

setuptools >=65.5.1

jinja2 >=3.1.3

poetry

pyproject.toml

python >=3.9,<4.0

PyYAML 6.0.1

prospector 1.10.3

pytest 7.4.4

pytest-cov 4.1.0

prospector-profile-duplicated 0.3.0

pre-commit

.pre-commit-config.yaml

pre-commit/pre-commit-hooks v4.5.0

sbrunner/hooks 0.5.0

codespell-project/codespell v2.2.6

pre-commit/mirrors-prettier v3.0.3

shellcheck-py/shellcheck-py v0.9.0.6

jumanjihouse/pre-commit-hooks 3.0.0

python-jsonschema/check-jsonschema 0.27.4

sirwart/ripsecrets v0.1.7

PyCQA/autoflake v2.2.1

asottile/pyupgrade v3.15.0

PyCQA/isort 5.12.0

psf/black 23.10.1

sbrunner/jsonschema-validator 0.1.0

regex

.pre-commit-config.yaml

poetry 1.6.1

poetry 1.6.1

prettier 3.0.3

prettier-plugin-sh 0.13.1

prettier-plugin-toml 1.0.0

pyjson5 1.6.5

Branch master

github-actions

.github/workflows/audit.yaml

actions/checkout v4

andstor/file-existence-action v3

asdf-vm/actions v3

andstor/file-existence-action v3

ubuntu 22.04

.github/workflows/backport.yaml

ubuntu 22.04

.github/workflows/changelog.yaml

actions/checkout v4

actions/cache v4

ubuntu 22.04

.github/workflows/delete-old-workflows-run.yaml

MajorScruffy/delete-old-workflow-runs v0.3.0

ubuntu 22.04

.github/workflows/main.yaml

actions/checkout v4

actions/setup-python v5

actions/cache v4

ubuntu 22.04

.github/workflows/pr-checks.yaml

actions/checkout v4

ubuntu 22.04

.github/workflows/pull-request-automation.yaml

actions/github-script v7

actions/github-script v7

actions/github-script v7

actions/github-script v7

actions/github-script v7

ubuntu 22.04

pep621

pyproject.toml

poetry-core >=1.0.0

poetry-dynamic-versioning >=0.19.0

pip_requirements

ci/requirements.txt

c2cciutils ==1.6.15

poetry ==1.7.1

poetry-dynamic-versioning ==1.2.0

poetry-plugin-export ==1.6.0

pre-commit ==3.6.0

poetry-plugin-drop-python-upper-constraint ==0.1.0

poetry-plugin-tweak-dependencies-version ==1.5.2

poetry-dynamic-versioning ==1.2.0

poetry

pyproject.toml

python >=3.9,<4.0

PyYAML 6.0.1

prospector 1.10.3

pytest 8.0.0

pytest-cov 4.1.0

prospector-profile-duplicated 0.5.1

pre-commit

.pre-commit-config.yaml

pre-commit/pre-commit-hooks v4.5.0

sbrunner/hooks 0.7.0

codespell-project/codespell v2.2.6

pre-commit/mirrors-prettier v3.1.0

shellcheck-py/shellcheck-py v0.9.0.6

jumanjihouse/pre-commit-hooks 3.0.0

python-jsonschema/check-jsonschema 0.27.4

sirwart/ripsecrets v0.1.7

PyCQA/autoflake v2.2.1

asottile/pyupgrade v3.15.0

PyCQA/isort 5.13.2

psf/black 24.1.1

sbrunner/jsonschema-validator 0.1.0

regex

.pre-commit-config.yaml

poetry 1.7.1

poetry 1.7.1

prettier 3.2.4

prettier-plugin-sh 0.14.0

prettier-plugin-toml 2.0.1

pyjson5 1.6.5

Check this box to trigger a request for Renovate to run again on this repository

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.