Skip to the content.

Json Schema Static Docs

npm version CircleCI

This library generates human friendly static markdown documents based on a set of JSON schema documents.

Features

See this post describing how this library is used by the DVLA.

Examples

HTML documentation JSON Schema
Person person.yml
Name name.yml
Enum Value Documentation enums.yml
One-of oneof.yml
Draft 2019-09 - Array draft-2019-09/array.yml
Draft 07 - User draft-07/user.yml
Draft 06 - Animal draft-06/animal.yml

See the examples page for more info.

Support for JSON schema specification versions

Currently supports schema specified using the following specification versions: draft-06, draft-07 and draft-2019-09.

Examples for each specification version can be found below.

You can view a detailed description of supported keywords.

Installation

npm install json-schema-static-docs

Usage

const JsonSchemaStaticDocs = require("json-schema-static-docs");

(async () => {
  let jsonSchemaStaticDocs = new JsonSchemaStaticDocs({
    inputPath: "./schema",
    outputPath: "./docs",
    ajvOptions: {
      allowUnionTypes: true,
    },
  });
  await jsonSchemaStaticDocs.generate();
  console.log("Documents generated.");
})();

Options

Parameter Description Default
inputPath Directory containing your schema “schema”
inputFileGlob Glob used to look for schema files ”*/.{yml,json}”
outputPath Where to write documentation files “docs”
templatePath Where to find templates “templates”
ajvOptions Options to pass to AJV {}
enableMetaEnum Allow documentation of enum values false
addFrontMatter Add front matter to generated documentation false
displaySchema Display schema JSON in output true

Markdown Front Matter

If you want to include markdown front matter (for Jekyll, Hugo etc) use the addFrontMatter options.

let jsonSchemaStaticDocs = new JsonSchemaStaticDocs({
  inputPath: "./schema",
  outputPath: "./docs",
  addFrontMatter: true,
});
await jsonSchemaStaticDocs.generate();

This will prepend generated markdown documents with the schema title or it.

---
title: The schema title or $id
---
# documentation starts here

Describing Enums

Json-schema allows a set of enumeration values to be defined for a string property but does not allow descriptions to be defined for each value. Descriptions within documentation can be very useful.

This library supports the meta:enum convention (inspired by adobe/jsonschema2md to allow descriptions to be defined for enums.

You will need to enable this feature using the enableMetaEnum option:

let jsonSchemaStaticDocs = new JsonSchemaStaticDocs({
  inputPath: "./schema",
  outputPath: "./docs",
  enableMetaEnum: true,
});
await jsonSchemaStaticDocs.generate();

This allows the meta:enum keyword to be used when applying strict validation.

And then define the meta:enum descriptions adjacent to your enum e.g.

property1:
  title: "Property 1"
  type: "string"
  enum: ["foo", 42]
  meta:enum:
    foo: Description for foo
    42: Description for 42

Custom Templates

Templates are authored in handlebars.js.

The default template is templates/markdown/schema.hbs.

You can provide your own custom templates using the templatePath option.

In the example below you will be expected to provide `./your-templates/schema.hbs’.

const JsonSchemaStaticDocs = require("json-schema-static-docs");

(async () => {
  let jsonSchemaStaticDocs = new JsonSchemaStaticDocs({
    inputPath: "./schema",
    outputPath: "./docs",
    templatePath: "./your-templates/",
  });
  await jsonSchemaStaticDocs.generate();
  console.log("Documents generated.");
})();

There are currently limitations when using custom templates. Some elements are rendered through handlebars helpers outside the templates.