This guide is for you if all of the following is true:
- You maintain a JSON specification
- Other people need to write JSON documents that adhere to your specification (by hand or by code) and thus need to understand your specification
- You haven't already spent sufficient effort documenting your specification
Note that you can adapt this guide to YAML with a small amount of effort.
Consider a hypothetical application which accepts information about animals and stuff. A single instance of the input JSON could look something like:
{
"$schema": "example.schema.json",
"animals": [
{
"type": "Dog",
"name": "Frederiek",
"nicknames": [
"Fred",
"Freddie",
"The Decimator"
],
"age": 5,
"speed": 40.89
},
{
"type": "Cat",
"name": "Mabel",
"nicknames": null,
"age": 2,
"speed": 30.71
}
],
"happyHourStart": 16,
"happyHourEnd": 18
}Someone who has an example JSON document to use as reference is a lot better off than someone who has nothing, but they would still have lots of important unanswered questions like:
- What fields are mandatory vs optional?
- What are the units of these numbers?
- What values are valid?
This is where the "$schema": "example.schema.json" line comes in. It is a reference to a schema document which answers these kinds of questions. This is typically a URL to a schema file hosted online, but it can be a reference to a file on the local machine as well. Code editors such as Visual Studio Code will automatically read the contents of the referenced schema and apply in-editor warnings if the schema is being violated. It can also provide tool-tip when hovering the mouse over property names and provide auto-complete suggestions for values defined in the schema.
A JSON schema is a document that defines all possible JSON documents for a specific application. Somewhat confusingly, it is also a JSON document whose specification is defined by another JSON schema. This "meta-schema" is often called a "draft" and you can think of it as the "version number" which the schema file implements.
Here is what the JSON schema for our hypothetical application would look like. This gives the code editor, the developer, the client application etc. the context they might need to validate and author JSON documents for the hypothetical application.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Animal Happy Hour",
"description": "An example schema for example purposes.",
"type": "object",
"properties": {
"$schema": {
"description": "The URL of the JSON schema.",
"type": "string"
},
"animals": {
"description": "List of animals.",
"type": [
"array"
],
"items": {
"type": "object",
"properties": {
"type": {
"description": "The species of the animal.",
"type": "string",
"enum": [
"Cat",
"Dog",
"Monkey"
]
},
"name": {
"description": "The animal's name.",
"type": "string"
},
"nicknames": {
"description": "An array of nicknames for the animal.",
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"age": {
"description": "The age of the animal in years.",
"type": "integer",
"minimum": 0
},
"speed": {
"description": "The top speed of the animal in feet/sec",
"type": "number",
"exclusiveMinimum": 0.0
}
},
"required": [
"type",
"name",
"age",
"speed"
],
"additionalProperties": false
}
},
"happyHourStart": {
"description": "The start time of the happy hour in hours (24-hour format).",
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 24,
"default": 12
},
"happyHourEnd": {
"description": "The end time of the happy hour in hours (24-hour format).",
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 24,
"default": 15
}
},
"required": [
"animals"
],
"additionalProperties": false
}You can put this file in the same directory as the example document shown previously, and visual studio code will start validating the contents automatically.
For more information on how to write schemas, visit https://json-schema.org/learn/. You can also ask ChatGPT to help, but it will inevitably get tripped up on mismatched schema draft revisions.
A nice consequence of taking the time to write a JSON Schema for your application's JSON specification is that you can use one of several tools for creating human-friendly documentation to document information that is already contained in your schema. I recommend JSON Schema for Humans and will be using it for this example.
Continuing with our example, create a file called config.json. This file will describe how we want our generated documentation to look. JSON Schema For Human's config file format is (somewhat confusingly) documented with itself
{
"$schema": "https://raw.githubusercontent.com/coveooss/json-schema-for-humans/main/config_schema.json",
"show_breadcrumbs": false,
"collapse_long_descriptions": false,
"collapse_long_examples": false,
"footer_show_time": false
}Then it's just a matter of downloading and running the doc generator like so (windows):
py -m pip install --upgrade pip
py -m pip install json-schema-for-humans
generate-schema-doc --config-file .\config.json .\example.schema.json .\build\example.schema.htmlThe resulting HTML file looks something like the following:
