JSON Schema for Humans configuration file
February 17, 2026 · View on GitHub
- 1. Property
JSON Schema for Humans configuration file > description_is_markdown - 2. Property
JSON Schema for Humans configuration file > description_safe_mode - 3. Property
JSON Schema for Humans configuration file > expand_buttons - 4. Property
JSON Schema for Humans configuration file > show_breadcrumbs - 5. Property
JSON Schema for Humans configuration file > collapse_long_descriptions - 6. Property
JSON Schema for Humans configuration file > collapse_long_examples - 7. Property
JSON Schema for Humans configuration file > link_to_reused_ref - 8. Property
JSON Schema for Humans configuration file > recursive_detection_depth - 9. Property
JSON Schema for Humans configuration file > deprecated_from_description - 10. Property
JSON Schema for Humans configuration file > default_from_description - 11. Property
JSON Schema for Humans configuration file > copy_css - 12. Property
JSON Schema for Humans configuration file > copy_js - 13. Property
JSON Schema for Humans configuration file > template_name - 14. Property
JSON Schema for Humans configuration file > custom_template_path - 15. Property
JSON Schema for Humans configuration file > show_toc - 16. Property
JSON Schema for Humans configuration file > examples_as_yaml - 17. Property
JSON Schema for Humans configuration file > old_anchor_links - 18. Property
JSON Schema for Humans configuration file > markdown_options - 19. Property
JSON Schema for Humans configuration file > template_md_options- 19.1. Property
JSON Schema for Humans configuration file > template_md_options > badge_as_image - 19.2. Property
JSON Schema for Humans configuration file > template_md_options > show_heading_numbers - 19.3. Property
JSON Schema for Humans configuration file > template_md_options > show_array_restrictions - 19.4. Property
JSON Schema for Humans configuration file > template_md_options > properties_table_columns
- 19.1. Property
- 20. Property
JSON Schema for Humans configuration file > with_footer - 21. Property
JSON Schema for Humans configuration file > footer_show_time - 22.
PropertyJSON Schema for Humans configuration file > allow_html_description - 23.
PropertyJSON Schema for Humans configuration file > minify - 24.
PropertyJSON Schema for Humans configuration file > templates_directory
Title: JSON Schema for Humans configuration file
| Type | object |
| Required | No |
| Additional properties | Any type allowed |
Description: Choose how to generate JSON Schema for Humans documentation file.
Configuration parameters can be provided in several ways:
- On the CLI using
--config parameter_name=value(example:--config template_name=flat) - On the CLI using a config file
--config-file config.json - From code, by providing a GenerationConfiguration object to the called generation method.
| Property | Pattern | Type | Deprecated | Definition | Title/Description |
|---|---|---|---|---|---|
| - description_is_markdown | No | boolean | No | - | (HTML outputs only) Whether to consider the description as Markdown and render it accordingly. |
| - description_safe_mode | No | enum (of null or string) | No | - | (HTML outputs only) (Only used with `description_is_markdown`) How are HTML tags in descriptions handled. Correspond to the `safe_mode` option of the markdown2 library. - "escape": Escape all HTML tags in descriptions - "replace": Replace HTML tags with `[HTML_REMOVED]` - null: Allow HTML in descriptions |
| - expand_buttons | No | boolean | No | - | Add an `Expand all` and a `Collapse all` button at the top of the generated documentation. |
| - show_breadcrumbs | No | boolean | No | - | For each property, show the relative place of that property in the schema. |
| - collapse_long_descriptions | No | boolean | No | - | If a description is considered big, show only the beginning and add a `Read more` button. |
| - collapse_long_examples | No | boolean | No | - | If an example is considered big, collapse it, it can be displayed with a `Show` option. |
| - link_to_reused_ref | No | boolean | No | - | If several `$ref` points to the same definition, only render the documentation for this definition the first time. All other occurrences are replaced by an anchor link to the first occurrence. The first occurrence is the one that is the least nested from the top of the schema and appears first in that nesting level. Note: If this option is off and the schema contains recursive definitions, the generation will crash! |
| - recursive_detection_depth | No | integer | No | - | 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. |
| - deprecated_from_description | No | boolean | No | - | Mark a property as deprecated (with a big red badge) if the description contains the string `[Deprecated`. |
| - default_from_description | No | boolean | No | - | 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. |
| - copy_css | No | boolean | No | - | Copy `schema_doc.css` to the same directory as `RESULT_FILE` after generation. |
| - copy_js | No | boolean | No | - | Copy `schema_doc.min.js` to the same directory as `RESULT_FILE` after generation. This file contains the logic for the anchor links. |
| - template_name | No | enum (of string) | No | - | 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. `techdocs` is optimized for TechDocs/MkDocs Material with collapsible admonitions. |
| - custom_template_path | No | string | No | - | 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. |
| - show_toc | No | boolean | No | - | Whether to render table of contents. |
| - examples_as_yaml | No | boolean | No | - | Whether to display examples as YAML instead of JSON |
| - old_anchor_links | No | boolean | No | - | Generate HTML ids for anchor links without special characters (keep only letters, digits, `_`, and `-`). This is the old behaviour and is only needed for browsers that do not support HTML 5. |
| - markdown_options | No | object | No | - | (Only used with `description_is_markdown`) Markdown 2 options for the descriptions. |
| - template_md_options | No | object | No | - | specific options to md template |
| - with_footer | No | boolean | No | - | Whether to show the footer linking to the library repo and with the generation datetime |
| - footer_show_time | No | boolean | No | - | Whether the footer should display the generation time |
| - allow_html_description | No | boolean | Deprecated | - | [Deprecated] |
| - minify | No | boolean | Deprecated | - | [Deprecated] |
| - templates_directory | No | string | Deprecated | - | [Deprecated] |
1. Property JSON Schema for Humans configuration file > description_is_markdown
| Type | boolean |
| Required | No |
| Default | true |
Description: (HTML outputs only) Whether to consider the description as Markdown and render it accordingly.
2. Property JSON Schema for Humans configuration file > description_safe_mode
| Type | enum (of null or string) |
| Required | No |
| Default | "escape" |
Description: (HTML outputs only)
(Only used with description_is_markdown)
How are HTML tags in descriptions handled. Correspond to the safe_mode option of the markdown2 library.
- "escape": Escape all HTML tags in descriptions
- "replace": Replace HTML tags with
[HTML_REMOVED] - null: Allow HTML in descriptions
Must be one of:
- null
- "escape"
- "replace"
3. Property JSON Schema for Humans configuration file > expand_buttons
| Type | boolean |
| Required | No |
| Default | false |
Description: Add an Expand all and a Collapse all button at the top of the generated documentation.
4. Property JSON Schema for Humans configuration file > show_breadcrumbs
| Type | boolean |
| Required | No |
| Default | true |
Description: For each property, show the relative place of that property in the schema.
5. Property JSON Schema for Humans configuration file > collapse_long_descriptions
| Type | boolean |
| Required | No |
| Default | true |
Description: If a description is considered big, show only the beginning and add a Read more button.
6. Property JSON Schema for Humans configuration file > collapse_long_examples
| Type | boolean |
| Required | No |
| Default | true |
Description: If an example is considered big, collapse it, it can be displayed with a Show option.
7. Property JSON Schema for Humans configuration file > link_to_reused_ref
| Type | boolean |
| Required | No |
| Default | true |
Description: If several $ref points to the same definition, only render the documentation for this definition the first time. All other occurrences are replaced by an anchor link to the first occurrence. The first occurrence is the one that is the least nested from the top of the schema and appears first in that nesting level.
Note: If this option is off and the schema contains recursive definitions, the generation will crash!
8. Property JSON Schema for Humans configuration file > recursive_detection_depth
| Type | integer |
| Required | No |
| Default | 25 |
Description: 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.
9. Property JSON Schema for Humans configuration file > deprecated_from_description
| Type | boolean |
| Required | No |
| Default | false |
Description: Mark a property as deprecated (with a big red badge) if the description contains the string [Deprecated.
10. Property JSON Schema for Humans configuration file > default_from_description
| Type | boolean |
| Required | No |
| Default | false |
Description: 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.
11. Property JSON Schema for Humans configuration file > copy_css
| Type | boolean |
| Required | No |
| Default | true |
Description: Copy schema_doc.css to the same directory as RESULT_FILE after generation.
12. Property JSON Schema for Humans configuration file > copy_js
| Type | boolean |
| Required | No |
| Default | true |
Description: Copy schema_doc.min.js to the same directory as RESULT_FILE after generation.
This file contains the logic for the anchor links.
13. Property JSON Schema for Humans configuration file > template_name
| Type | enum (of string) |
| Required | No |
| Default | "js" |
Description: 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.
techdocs is optimized for TechDocs/MkDocs Material with collapsible admonitions.
Must be one of:
- "flat"
- "js"
- "js_offline"
- "md"
- "md_nested"
- "techdocs"
14. Property JSON Schema for Humans configuration file > custom_template_path
| Type | string |
| Required | No |
| Default | null |
Description: 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.
15. Property JSON Schema for Humans configuration file > show_toc
| Type | boolean |
| Required | No |
| Default | true |
Description: Whether to render table of contents.
16. Property JSON Schema for Humans configuration file > examples_as_yaml
| Type | boolean |
| Required | No |
| Default | false |
Description: Whether to display examples as YAML instead of JSON
17. Property JSON Schema for Humans configuration file > old_anchor_links
| Type | boolean |
| Required | No |
| Default | false |
Description: Generate HTML ids for anchor links without special characters (keep only letters, digits, _, and -).
This is the old behaviour and is only needed for browsers that do not support HTML 5.
18. Property JSON Schema for Humans configuration file > markdown_options
| Type | object |
| Required | No |
| Additional properties | Any type allowed |
| Default | {"fenced-code-blocks": {"cssclass": "highlight jumbotron"}, "tables": null, "breaks": {"on_newline": true, "on_backslash": true}} |
Description: (Only used with description_is_markdown)
Markdown 2 options for the descriptions.
Example:
{
"fenced-code-blocks": {
"cssclass": "highlight jumbotron"
},
"tables": null,
"break-on-newline": true,
"cuddled-lists": true
}
19. Property JSON Schema for Humans configuration file > template_md_options
| Type | object |
| Required | No |
| Additional properties | Any type allowed |
Description: specific options to md template
| Property | Pattern | Type | Deprecated | Definition | Title/Description |
|---|---|---|---|---|---|
| - badge_as_image | No | boolean | No | - | if true generate badges(eg: optional, required) using embedded image (https://img.shields.io). if false, use text instead |
| - show_heading_numbers | No | boolean | No | - | if true generate heading numbers to correspond to table of contents. if false, do not generate heading numbers |
| - show_array_restrictions | No | boolean | No | - | if true generate array restrictions section. if false, do not generate |
| - properties_table_columns | No | array of enum (of string) | No | - | array of column names to display in the properties table. if empty, the default is ['Property','Pattern','Type','Deprecated','Definition','Title/Description'] |
19.1. Property JSON Schema for Humans configuration file > template_md_options > badge_as_image
| Type | boolean |
| Required | No |
| Default | false |
Description: if true generate badges(eg: optional, required) using embedded image (https://img.shields.io).
if false, use text instead
19.2. Property JSON Schema for Humans configuration file > template_md_options > show_heading_numbers
| Type | boolean |
| Required | No |
| Default | true |
Description: if true generate heading numbers to correspond to table of contents.
if false, do not generate heading numbers
19.3. Property JSON Schema for Humans configuration file > template_md_options > show_array_restrictions
| Type | boolean |
| Required | No |
| Default | true |
Description: if true generate array restrictions section.
if false, do not generate
19.4. Property JSON Schema for Humans configuration file > template_md_options > properties_table_columns
| Type | array of enum (of string) |
| Required | No |
Description: array of column names to display in the properties table.
if empty, the default is ['Property','Pattern','Type','Deprecated','Definition','Title/Description']
| Array restrictions | |
|---|---|
| Min items | N/A |
| Max items | N/A |
| Items unicity | False |
| Additional items | False |
| Tuple validation | See below |
| Each item of this array must be | Description |
|---|---|
| properties_table_columns items | - |
19.4.1. JSON Schema for Humans configuration file > template_md_options > properties_table_columns > properties_table_columns items
| Type | enum (of string) |
| Required | No |
Must be one of:
- "Property"
- "Pattern"
- "Type"
- "Deprecated"
- "Definition"
- "Title/Description"
20. Property JSON Schema for Humans configuration file > with_footer
| Type | boolean |
| Required | No |
| Default | true |
Description: Whether to show the footer linking to the library repo and with the generation datetime
21. Property JSON Schema for Humans configuration file > footer_show_time
| Type | boolean |
| Required | No |
| Default | true |
Description: Whether the footer should display the generation time
22. Property JSON Schema for Humans configuration file > allow_html_description
JSON Schema for Humans configuration file > allow_html_description| Type | boolean |
| Required | No |
| Deprecated | |
| Default | false |
Description: [Deprecated]
23. Property JSON Schema for Humans configuration file > minify
JSON Schema for Humans configuration file > minify| Type | boolean |
| Required | No |
| Deprecated | |
| Default | true |
Description: [Deprecated]
24. Property JSON Schema for Humans configuration file > templates_directory
JSON Schema for Humans configuration file > templates_directory| Type | string |
| Required | No |
| Deprecated |
Description: [Deprecated]
Generated using json-schema-for-humans