json schema spec

The JSON Schema specification

3956

280

JavaScript

Welcome to JSON Schema

JSON Schema is a vocabulary that allows you to validate, annotate, and
manipulate JSON documents.

This repository contains the sources for the work in progress of the next
set of JSON Schema IETF Internet Draft (I-D) documents. For the latest released
I-Ds, please see the
Specification page on the website.

Call for contributions and feedback

Reviews, comments and suggestions are most welcome!
Please read our guidelines for contributing.

Status

For the current status of issues and pull requests, please see the following
labels

Labels are assigned based on
Sensible Github Labels.

Authoring and Building

Specification

To build all the spec files to HTML from the Markdown sources, run npm run build -- specs. You can also build each individually with npm run build -- specs/filename.md (Example: npm run build -- specs/jsonschema-core.md). You
can also use wildcards to build multiple specs at the same time: npm run build -- specs/jsonschema-*.md. The HTML files will be available in the web folder.

The spec is built using Remark, a markdown engine with
good support for plugins and lots of existing plugins we can use. Remark also
has a language server and
a VSCode extension we can use to
get linting an link checking while developing the spec.

Plugins

The following is a not-necessarily-complete list of configured plugins and the
features they make available to you.

remark-lint – Enforce markdown
styles guide.
remark-validate-links –
Check for broken links.
remark-gfm – Adds support for
Github Flavored Markdown specific markdown features such as autolink literals,
footnotes, strikethrough, tables, and tasklists.
remark-heading-id – Adds
support for {#my-anchor} syntax to add an id to an element so it can be
referenced using URI fragment syntax.
remark-headings
– A collection of enhancements for headings.
- Adds hierarchical section numbers to headings.
  - Use the %appendix% prefix on headings that should be numbered as an
    appendix.
- Adds id anchors to headers that don’t have one
  - Example: #section-2-13
  - Example: #appendix-a
- Makes the heading a link utilizing its anchor

remark-reference-links
– Adds new syntax for referencing a section of the spec using the section
number as the link text.

Example:

## Foo {#foo}
## Bar
This is covered in {{foo}} // --> Renders to "This is covered in [Section 2.3](#foo)"
- Link text will use "Section" or "Appendix" as needed

remark-table-of-contents
– Adds a table of contents in a section with a header called “Table of
Contents”.
remark-code-titles
– Add titles to code blocks
- Example:
```
\`\`\`jsonschema "My Fun Title"
{ "type": "string" }
\`\`\`
```
- The languages jsonschema and json have special styling
- The title will be parsed as a JSON string, but you have to double escape
  escaped characters. So, to get My "quoted" title, you would need to be
  "My \\\\"quoted\\\\" title".
remark-torchlight –
Syntax highlighting and more using https://torchlight.dev. Features include
line numbers and line highlighting.
remark-flexible-containers
– Add a callout box using the following syntax. Supported container types are
warning, note, and experimental.
```
::: {type} {title}
{content}
:::
```

Internet-Drafts

To build components that are being maintained as IETF Internet-Drafts, run
make. The Makefile will create the necessary Python venv for you as part of
the regular make target.

make clean will remove all output including the venv. To clean just the spec
output and keep the venv, use make spec-clean.

If you want to run xml2rfc manually after running make for the first time, you
will need to activate the virtual environment: source .venv/bin/activate.

The version of “xml2rfc” that this project uses is updated by modifying
requirements.in and running pip-compile requirements.in.

Descriptions of the xml2rfc, I-D documents, and RFC processes: