jsonschema2md: turning JSON Schema files into reference Markdown

Written for Adobe's own schema documentation problem

Documenting a complicated JSON Schema by hand is unpleasant work, and jsonschema2md exists to remove most of it. The project description is blunt about the audience: the tools were introduced by Adobe to document Adobe's Experience Data Models, and they can be used for other JSON Schema documents too.

That origin explains the shape of the output. The generated Markdown is described as ready for consumption on GitHub, or for processing with Jekyll or other static site generators. These are documentation pages, not a validator UI and not a live API explorer. There is no server, no browser component and no schema hosting service in the package. What you get is a command line program that reads a directory of schema files and writes a directory of Markdown files, and a Node API if you want to call the same conversion from your own code.

The licence is Apache-2.0 and the copyright line reads Adobe Systems Incorporated, so using it outside Adobe carries no special obligation beyond the licence terms themselves. The repository is not archived and the last push was on 2026-10-19, so the code is moving, though the pace of published releases is slower than the commit activity.

The pipeline runs on remark, mdast and a translation layer

The dependency list in package.json shows how the conversion is assembled. The Markdown side is built on the unified stack: remark-parse, remark-stringify and remark-gfm handle the document, mdast-builder constructs the tree that gets serialised, and mdast-util-to-string pulls plain text back out of nodes. github-slugger is there to generate the heading anchors, which is what makes the pages linkable from a table of contents.

Two dependencies are more unusual. es2015-i18n-tag and ferrum together implement the internationalisation layer, which is why the tool can emit German output without a second implementation of the templates. The other is js-yaml, which is what backs the YAML example formatting described below.

The schema side comes from the json-schema package, and the input walk uses readdirp with fs-extra for file handling. The command line is parsed with yargs, and the entry point is cli.js with the binary registered in package.json as jsonschema2md, pointing at that file. The package is an ES module, with main set to lib/index.js and typings pointing at a types directory, so the Node API is typed.

The important detail for a user is that the output is Markdown built programmatically, not templates that you edit. That is why the flags are limited to what you can influence from the outside, and it is also why the coverage and translation story has to live in the package itself.

Installing the CLI and generating a first batch of pages

The requirements are modest: npm version 3.10.8 or up, and node v18 or v20 or up. The installation and first run is a global install followed by a conversion of a directory:

$ npm install -g @adobe/jsonschema2md

# show usage information
$ jsonschema2md

# run task
$ jsonschema2md -d examples/schemas -o examples/docs
# generated output for whole folder is written to ./examples/docs

The two flags that matter are the directory of schemas and the output directory. Running jsonschema2md with no arguments prints usage information, which is the quickest way to see the full option list before you commit to a command in a script.

By default the tool looks for files whose names end in *.schema.json. If your schemas are named differently, the extension is changeable with the --schema-extension flag, or its short form -e. That single detail is what decides whether the tool sees your files at all, so it is worth checking the first time a conversion produces an empty output directory.

Custom attributes, missing headers and YAML examples

Three flags shape the content of the generated pages. The first adds attributes that JSON Schema itself does not define. The documentation states that jsonschema2md displays only the attributes of a property which are defined by the JSON Schema standard, and that extra attributes can be surfaced with the --properties parameter, short form -p:

# include both the `version` and the `test` attribute
$ jsonschema2md -d examples/schemas -o examples/docs -p version -p test

This matters for teams whose schemas carry vendor extensions. Without the flag, those fields are dropped silently, which produces pages that look thinner than the schema they came from.

The second flag removes the header. In some cases you do not need a header because it does not provide any useful information, and the --header parameter, short form -h, disables its inclusion. The example in the documentation combines it with a draft selector:

# run against JSON Schema Draft 06
$ jsonschema2md -d examples/schemas -o examples/docs -v 06 -h false

The third option changes the format of the examples. If you use JSON Schema to validate YAML documents, for instance configuration files, the example values can be emitted as YAML rather than JSON with the -f yaml or --example-format yaml option. The repository keeps both output styles as examples, with a docs directory and a docsWithoutHeader directory under examples, so you can see what the two modes produce side by side.

Driving the conversion from npm instead of a global install

The package is meant to be wired into a project rather than installed once on a machine. The documentation describes a conversion toolchain for a JSON Schema project that is driven entirely by npm. First the dependency is declared in the devDependencies section of package.json:

  "devDependencies": {
    "@adobe/jsonschema2md": "^6.0.0"
  }

Then a script is added to the scripts section, adapted to your own paths:

"scripts": {
  "prepare": "mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas/draft-04"
}

The documentation notes a practical detail about ordering: if you run npm install before running npm run prepare, npm will install @adobe/jsonschema2md in a node_modules/.bin path, even if you did not install the JSON Schema Markdown beforehand. In other words the binary is on the path for the script, but the version in use is whatever your package.json pins.

The same package exposes a programmatic API for Node.js:

const {jsonschema2md} = require('@adobe/jsonschema2md');
const schema = require('examples/schemas/example.schema.json');

const markdown = jsonschema2md(schema, {
  includeReadme: true,
});

This path takes a schema object rather than a directory and returns Markdown, so you can generate a single page inside a larger publishing step, or write a script that decides per schema which options to pass.

Support for the 2019-09 vocabulary is partial and tracked in a file

The clearest limitation is stated plainly in the project documentation: jsonschema2md is developed against JSON Schema 2019-09, but not the full vocabulary is supported. The supported keyword list lives in schemasupport.md, and the documentation says that this list is updated by the tests. That last clause matters. Support is defined by what the test suite exercises, so the file is a record of what has been implemented rather than a design promise about the specification.

There is a TODO section in the documentation that points at the same file, with support for missing keywords listed as remaining work. A schema that leans on keywords outside the list will produce output that is quietly missing pieces, and there is no validation pass that reports the omission. Confirming your keyword coverage is a manual step: open schemasupport.md and check the entries your schemas rely on before trusting the generated pages.

The translation story is similarly bounded. The -l parameter selects the output language, and the supported languages listed are English and German. Custom translations are handled through an external translation platform rather than in the repository, and the documentation points contributors at GitLocalize for that. The repository also carries a crowdin.yml, so the translation workflow is not fully described in one place, and translation coverage depends on what contributors have supplied.

The documentation and the package metadata disagree in places

Two contradictions are visible in the repository, and both affect how much you should trust the prose.

The first is the test runner. The documentation says the suite is a Jasmine test suite and that anything below 100% coverage counts as a test failure. The scripts section of package.json tells a different story: the test script runs c8 with a mocha runner and passes --check-coverage with thresholds of 80 for branches and 95 for statements and lines, followed by a run of the locale update script. The written coverage claim does not match the enforced thresholds, so treat 100% as a stale description rather than the actual bar.

The second is versioning. The published tags are v8.0.9, v8.0.10 and v8.0.11, with v8.0.11 dated 2026-03-23, while the version field in package.json reads 1.1.1 and the devDependencies example in the documentation shows ^6.0.0. Three different version numbers for the same package in one repository. The release process is driven by semantic-release, and the CHANGELOG.md file at the root is the place to read what actually shipped, but if you pin a version in your own package.json, check which number corresponds to the release you want rather than assuming the package.json field is the published one.

Neither problem affects the conversion itself. They do mean you should read the repository files rather than the introduction when you are deciding what to pin and what to expect from the test suite.

Editorial conclusion

jsonschema2md is a good fit for a team that already keeps JSON Schema as the source of truth and wants generated reference pages in a repository or static site, especially if it needs YAML examples or German output. It is the wrong tool for a schema set that leans on vocabulary outside the supported list, for a team that needs interactive playground or live validation UI, or for anyone who needs a trustworthy statement of which keywords are supported without reading schemasupport.md. Before adopting it, run jsonschema2md -d examples/schemas -o examples/docs against a copy of your own schemas, diff the generated pages against the hand-written ones, and check schemasupport.md for the keywords your schemas rely on, because the last push was on 2026-10-19 while the most recent published tag was v8.0.11 on 2026-03-23.

Frequently asked questions

Official sources

1. adobe/jsonschema2md on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases