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
Index of documents n/a
Person person.yml
Name name.yml
Enum Value Documentation enums.yml
Examples Title and Documentation examples-with-meta.yml
One-of oneof.yml
All-of allof.yml
Any-of anyof.yml
Root level property root-level-property.yml
Draft 2020-12 - Prefix Items draft-2020-12/prefix-items.yml
Draft 2019-09 - Array draft-2019-09/array.yml
Draft 2019-09 - Deprecated draft-2019-09/deprecated.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.");
})();

Using JSON schema draft-2020-12

By defualt the library supports schema using draft-06, draft-07 and draft-2019-09.

To use schema based on draft-2020-12 set options.jsonSchemaVersion to https://json-schema.org/draft/2020-12/schema. All schema documents must use must use draft-2020-12, you can not combine this with earlier versions such as draft-07.

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

(async () => {
  let jsonSchemaStaticDocs = new JsonSchemaStaticDocs({
    inputPath: "schema",
    outputPath: "docs",
    jsonSchemaVersion: "https://json-schema.org/draft/2020-12/schema",
    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”
createIndex Create an index of documents true
indexPath Index file path (relative to outputPath) “index.md”
indexTitle Title of the generated index page “Index”
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

Index Creation

By default a root level index will be created in the specified outputPath.

You can see an example of the here;

Customising the index

You can specify a path and title for the index.

let jsonSchemaStaticDocs = new JsonSchemaStaticDocs({
  inputPath: "schema",
  outputPath: "docs",
  indexPath: "schema-index.md",
  indexTitle: "List of schema with custom title",
});

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

Describing examples with title and description

You can add an optional title or description to each example in a schema using meta:title and meta:description. For example:

{
  "$id": "examples-with-meta.yml",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Person",
  "description": "JSON schema example for a person entity",
  "type": "object",
  "examples": [
    {
      "meta:title": "Title for the example",
      "meta:description": "Description for the example",
      "name": "Rhys"
    },
    {
      "meta:title": "Title for the second example",
      "name": "Sarah"
    },
    {
      "name": "Charlie"
    }
  ],
  "properties": {
    "name": {
      "title": "Name",
      "description": "The name of a person",
      "type": "string",
      "examples": ["David"]
    }
  },
  "additionalProperties": false,
  "required": ["name"]
}

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.