JSON Schema for Humans: turning a schema file into static documentation

Static documentation pages instead of a schema browser

json-schema-for-humans exists to turn a JSON Schema into a page a human can read. The README describes it as quickly generating a beautiful static HTML or Markdown page documenting a JSON schema. The static choice is the defining decision. Because the result is a file rather than an application, the README argues it is easier to host and faster to load, and in practice it means the documentation can be committed next to the schema, served from the same static site as the rest of your docs, or read on GitHub as a Markdown file. The feature list is short and specific: support for JSON Schema Draft-07, static output, HTML and Markdown output, several templates to choose from, anchor links that send a user to a specific section of the documentation, and support for references, including circular ones. That last item is the one that saves real work, since a schema with a self-referencing tree structure breaks most quick-and-dirty doc generators.

One CLI that accepts a file, a directory, a glob or a list

Installing the package is a single pip command, and it puts a generate-schema-doc executable on your path.

pip install json-schema-for-humans

The command line interface is the main entry point, with the usage line showing a schema argument and an optional result argument.

generate-schema-doc [OPTIONS] SCHEMA_FILES_OR_DIR [RESULT_FILE_OR_DIR]

The schema argument is flexible in a way that suits real repositories. It can be a path to a single schema file, a path to a directory in which case all files with the json, yaml or yml extensions are used, a glob pattern starting from the current working directory, or a comma-separated list of those. The README gives the accepted forms as my_schema.json, my_folder, a comma-separated pair of a yaml and a json file, and a glob pattern that starts with two asterisks. The result argument is optional and its default depends on the input: the current working directory if more than one schema was provided, schema_doc.html for a single schema rendered as HTML, and schema_doc.md for a single schema rendered as Markdown. When several schemas are passed in, the result must be a directory, and each output file takes the name of its input schema with the html or md extension. All schemas provided must be valid JSON Schema in JSON or YAML format.

Templates are picked with a config flag, and the config has its own schema

Choosing a template is a config parameter, and the README gives the exact flag syntax. On the command line, the option is --config template_name=[TEMPLATE_NAME], with the examples --config template_name=js for the HTML version and --config template_name=md for the Markdown version. The parameters are documented in the JSON schema config_schema.json at the root of the repository, and the README links the generated documentation of the configuration itself in both HTML and Markdown forms, so the tool documents its own options. Every parameter follows the format --config parameter_name=parameter_value, and the value must be valid JSON. Flags are a special case: you can omit the value for true, or prefix the name with no_ for false, so --config expand_buttons and --config no_expand_buttons both work. The example given for a boolean is --config expand_buttons=true, and the same parameter appears in the config file example, which sets description_is_markdown, expand_buttons and copy_js.

A YAML config file keeps the same options out of your shell history

The same options can live in a file, which is what you want in a CI job or a repository with a shared documentation setup. The flag is --config-file, and the path points to a JSON or YAML file that respects the config_schema.json schema. The README example is a file named jsfh-conf.yaml in the current directory.

description_is_markdown: false
expand_buttons: true
copy_js: false

Three options are the whole example, and they cover the questions that come up first. Whether a schema description is treated as Markdown, whether the generated page gets expand and collapse buttons, and whether the JavaScript file is copied alongside the page. The config file route is worth preferring over a long command line because it can be version controlled, which keeps documentation output consistent across a team.

Three Python entry points, and only one of them returns a string

The library exposes its generation methods from json_schema_for_humans.generate, and the README tabulates how the schema input and output differ between them. generate_from_schema takes a schema_file as a str or pathlib.Path and returns the rendered doc as a str, with no CSS or JavaScript copied. generate_from_filename takes a schema_file_name and writes the rendered doc to the file at result_file_name, copying the CSS and JavaScript. generate_from_file_object takes an open file object in read mode and writes to an open file object in write mode, again copying the assets. When file objects are used, the README notes that the files are assumed to be opened with utf-8 encoding, and that the CSS and JavaScript are copied to the current working directory as schema_doc.css and schema_doc.min.js if necessary. In other words, the string-returning method is the one to pick when you want to post-process the output yourself.

GenerationConfiguration keeps the parameter list from growing

Passing a dozen options through several function calls gets ugly, which is why the project introduces a configuration object. The README describes GenerationConfiguration as a way to reduce the number of parameters to pass from function to function, and the usage example shows it carrying copy_css and expand_buttons.

from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration

config = GenerationConfiguration(copy_css=False, expand_buttons=True)

generate_from_filename("my_schema.json", "schema_doc.html", config=config)

The comments in the README explain the result: the doc lands in schema_doc.html, schema_doc.min.js is copied next to it but schema_doc.css is not because copy_css was false, and the page contains an Expand all and a Collapse all button at the top. One more method detail is documented for people with large schemas. generate_from_schema takes a loaded_schemas parameter, a dict keyed by the real path of the schema file whose values are the already-loaded schema, and the README says explicitly that this should not be necessary in normal scenarios. It is there for people who have already parsed the schemas and would rather not pay for it twice.

Draft-07 support and a list of what actually gets checked

The supported features are listed plainly in the README, and it is worth reading them as a boundary rather than a promise. Supported are types, regular expressions, string length, string format, numeric types with multiples and range, constant and enumerated values, and required properties. The README points readers to the Understanding JSON Schema site to understand what those checks mean. Anything outside that list is not documented as handled, and since the project targets Draft-07 specifically, a schema using a newer draft keyword is outside the supported envelope. The package targets Python 3.10 and newer, and the classifiers list 3.10 through 3.14, so on the Python side there is little to negotiate.

Apache-2.0 in the metadata, a custom file GitHub cannot classify

There is a licensing wrinkle worth checking for yourself. The pyproject file declares license = Apache-2.0 and the classifier list includes the Apache Software License, and the package metadata names the authors as Denis Blanchette and AbdulRahman Al Hamali at Coveo. GitHub, however, reports the repository license as a custom licence it cannot classify, which points at the LICENSE.md file at the root of the repository. Read that file directly before you ship the tool in a product, since the packaging metadata and the repository classifier disagree. The project itself is busy: version 2.1.0 was released on 2026-10-07, after a 2.0.0 on 2026-04-14, the repository is not archived, and the last push was on 2026-10-19. Releases are automated with semantic-release, and the version number in pyproject.toml is a placeholder that semantic-release overwrites at publish time, so the file is not a reliable place to read the current version.

Editorial conclusion

json-schema-for-humans fits teams that keep a JSON Schema for a config file or an API payload and want browsable reference documentation committed alongside the schema, with Markdown output for repositories that do not publish HTML. It does not fit projects that need an interactive schema explorer or live validation feedback in the browser, since the output is static and generated ahead of time. Verify first that your schema sticks to Draft-07 features, decide between the HTML and Markdown templates before you generate a large batch, and check the LICENSE.md file directly, because the repository license does not match what GitHub classifies it as.

Frequently asked questions

Official sources

1. coveooss/json-schema-for-humans on GitHub
2. Issues
3. README
4. Releases