JSON Schema for Humans configuration file

Type: object

Choose how to generate JSON Schema for Humans documentation file.

Configuration parameters can be provided in several ways:

root minify
Type: boolean Default: true

Minify the output HTML document.

root description_is_markdown
Type: boolean Default: true

Whether to consider the description as markdown and render it accordingly.

root expand_buttons
Type: boolean Default: false

Add an Expand all and a Collapse all button at the top of the generated documentation.

root show_breadcrumbs
Type: boolean Default: true

For each property, show the relative place of that property in the schema.

root collapse_long_descriptions
Type: boolean Default: true

If a description is considered big, show only the beginning and add a Read more button.

root collapse_long_examples
Type: boolean Default: true

If an example is considered big, collapse it, it can be displayed with a Show option.

root recursive_detection_depth
Type: integer Default: 25

Advanced option
If link_to_reused_ref is false and a $ref in the schema refers to a parent of itself, we would get a RecursionError trying to render the documentation. To avoid this, each reference is checked for circular references.

This option determines the number of times to recursively follow definitions looking for a circular reference.

In other words, if a schema has a deeply nested element that refers to itself, this option may need to be increased.

root deprecated_from_description
Type: boolean Default: false

Mark a property as deprecated (with a big red badge) if the description contains the string [Deprecated.

root default_from_description
Type: boolean Default: false

Extract the default value of a property from the description like this: [Default `the_default_value`].

The default value from the "default" attribute will be used in priority.

root copy_css
Type: boolean Default: true

Copy schema_doc.css to the same directory as RESULT_FILE after generation.

root copy_js
Type: boolean Default: true

Copy schema_doc.min.js to the same directory as RESULT_FILE after generation.

This file contains the logic for the anchor links.

root templates_directory
Type: string

[Deprecated]

root template_name
Type: enum (of string) Default: "js"

The name of the built-in template to use to render the documentation.

js is the default and uses javascript for anchor links, collapsible sections and tabs.

js_offline is identical to js except that all CSS, fonts and JavaScript are bundled for offline use.

flat uses no javascript, but has no interactivity.

md is the markdown template.

md_nested is the markdown template with collapsible nested sections.

Must be one of:

  • "flat"
  • "js"
  • "js_offline"
  • "md"
  • "md_nested"

root custom_template_path
Type: string Default: null

Path to a custom Jinja2 template file.

There can be multiple files to split the template, but this path should be the entry point.

If no output file is specified, the extension of the template file will be used to determine the output documentation extension. i.e. if the template is in ./custom_template/content.html, the resulting documentation will have the html extension.

root show_toc
Type: boolean Default: true

Whether to render table of contents.

root examples_as_yaml
Type: boolean Default: false

Whether to display examples as YAML instead of JSON

root markdown_options
Type: object Default: {"fenced-code-blocks": {"break-on-newline": true, "cssclass": "highlight jumbotron", "tables": null}, "tables": null}

Markdown 2 options for the descriptions. description_is_markdown must be true for this to have any effect.

WARNING
Adding an extra, even if the value is false, will activate it. For example {"break-on-newline": false} will activate the break-on-newline extra.


Example:

{
    "fenced-code-blocks": {
        "cssclass": "highlight jumbotron"
    },
    "tables": null,
    "break-on-newline": true,
    "cuddled-lists": true
}

root template_md_options
Type: object

specific options to md template

root template_md_options badge_as_image
Type: boolean Default: false

if true generate badges(eg: optional, required) using embedded image (https://img.shields.io).

if false, use text instead

root template_md_options show_heading_numbers
Type: boolean Default: true

if true generate heading numbers to correspond to table of contents.

if false, do not generate heading numbers

root template_md_options show_array_restrictions
Type: boolean Default: true

if true generate array restrictions section.

if false, do not generate

root template_md_options properties_table_columns
Type: array of enum (of string)

array of column names to display in the properties table.

if empty, the default is ['Property','Pattern','Type','Deprecated','Definition','Title/Description']

 No Additional Items

Each item of this array must be:

root template_md_options properties_table_columns properties_table_columns items
Type: enum (of string)

Must be one of:

  • "Property"
  • "Pattern"
  • "Type"
  • "Deprecated"
  • "Definition"
  • "Title/Description"