JSON Schema documentation style guide

Welcome to JSON Schema! This guide is intended for project contributors and provides guidelines for the text-formatting conventions of our documentation. The purpose of this style guide is to create consistency throughout our documentation, so make sure to read and follow it carefully. To learn about how to contribute to our documentation, see the Docs contributing guide

Our preferred style guide

We use the Google developer documentation style guide as our default guide. For a quick summary, see the Google style guide highlights. This document describes customizations to the Google developers style guide specific to the JSON Schema documentation.

The JSON Schema documentation uses American spelling and our preferred dictionary is the American Heritage Dictionary.

Write for your audience

The content of our documentation is written mainly for develepers, therefore, information should be clear, concise, and accurate. If you're unsure about a certain detail, please contact the appropriate people to verify it. For more information about our users personas, see Personas.

Types of documents and information architecture

To better attend to the needs of our readers, we create technical documentation according to the diataxis framework. Therefore, most of our documents can be classified as one of the following:

• Reference
• Tutorial
• How-to guides
• Explanation

Other types of documents we write are the following:

• Use cases
• Case studies
• Release notes

We organize our documentation into the following content buckets:

• Introduction: Several types of documents live in this bucket that introduce the JSON Schema initiative's purpose, how the JSON Schema is used in various industries and applications, and its key features and benefits.

• Basics: The documents of this content bucket help beginners get started with JSON Schema.

• Guides: The guides contained in this bucket help users develop practical skills for validating schemas, building complex ones, and troubleshooting issues.

• Reference: These documents explain the type of data, formats, and constraints that keywords expect. It also contains examples of how to use JSON Schema keywords.

• Specification: This section contains detailed changelogs of keyword modifications, highlights behavioral changes, and provides migration best practices.

Code blocks

To ensure that code samples are easy to search, copy and paste, and adapt, include all code as text, not as images, in the documentation.

Titles and headings

Titles should be short and communicate the main idea of the document. For explanation or reference documents, the title should start with a noun phrase, for example, Conditional subschemas. When the document is a guide that includes steps to complete a task, such as a tutorial, the title should start with a bare infinitive, for example, Structure complex schemas. To learn more about headings and titles, see Headings and titles of the Google developer documentation style guide.

Headings help readers scan the document and identify the parts that are relevant to them. Use headings, and subheadings when needed, that clearly describe the information they contain.

Notices and Markdown tags

Use the following tags to give readers relevant information that is not part of the flow of the text. To learn when to use notices, please read the Notes, cautions, warning, and other notices chapter of the Google developer documentation style guide.

Table of contents

To help readers find the information they are looking for within the document, add a table of contents at the beginning.

1<tableofcontent content= {content} depth= {depth}/>
2

Blockquote

Use the Blockquote tag for text that is quoted from another source.

1<blockquote> Message to show </blockquote>
2

Example:

According to the Google developers style guide, notices should be used sparingly:

Tabs group

Use the tabs groups to make comparisons.

1[ tabs-start "label"]
2[ tab "name"]
3message to show
4[ tabs-end ]
5

Example:

Star tag

Highlight changes introduced by drafts with the Star tag.

1<Star label="New in draft"/>
2

Example:

New in draft 2019-09

The deprecated keyword is a boolean that indicates that the instance value the keyword applies to should not be used and may be removed in the future.

Infobox tag

Use the Infobox tag for Notes. Notes provide the reader with relevant information that is not necessary, for example, an aside or a tip.

1<Infobox label="Note"> Message to show </Infobox>
2

Example:

Note

Draft-07 core and validation are backwards-compatible with draft-06.

Warning tag

Use the Warning tag for cautions. A Caution notice lets the reader know they should proceed carefully.

1<Warning label="Caution"> Message to show </Warning>
2

Example:

Caution

Using oneOf increases processing times because every sub-schema requires verification. Prefer anyOf whenever possible.

Danger tag

Use the Danger tag for Warning notices, which are stronger than Cautions.

1<Danger label="Warning"> Message to show </Danger>
2

Example:

Warning

Modifying a JSON Schema without validating the existing data against it, can cause system or application errors or compromise data integrity.

Markdown tags for blog articles

Use the following tags only when writing blog articles.

StarInline

You can use the StarInLine tag to highlight important information within your text, for example, when providing a best practice.

1<StarInline label="Best Practice"/> Message to show
2

Example:

Best Practice

Always include the $schema keyword at the root of your JSON Schema to declare which version you're using.

Summary and details

To provide readers with additional information without cluttering the main content, use the summary and details tags. The text within the summary tag is displayed initialy. The content within details is revealed after readers click on it.

1<summary> 
2Click for more details
3</summary>
4<details>
5Additional information to show
6</details>
7

Example:

1

Bigquote

Use Bigquote to emphasize key quotations or statements, for example, a user testimonial.

1<Bigquote> This is an important quote </Bigquote>
2

Example:

Regularquote

Use the Regularquote tag for shorter quotes from documentation or other sources and for highlighting key terms or concepts.

1<Regularquote>This is a short quote</Regularquote>
2

Example:

When discussing JSON Schema validation, it's important to understand the concept of keywords.

Tip

Use the Tip tag to give readers advice or additional context that enhances understanding.

1<Tip label="Tip">This is a tip or additional context.</Tip>
2

Example:

Tip

To learn more about keyword dependencies, read the Static Analysis of JSON Schema article by Greg Dennis.

We created this guide based on templates from The Good Docs Project.