json-schema-spec Documentation

1. Project Overview & Quickstart (json-schema-org/json-schema-spec) Copy Chapter

File: README.md Copy Chapter

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 Copy Chapter

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

Status Copy Chapter

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 Copy Chapter

Specification Copy Section

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 and 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
  style 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:
    markdown Copy

    ## 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:
    markdown Copy

    \`\`\`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 write
    "My \\\\"quoted\\\\" title".
• rehype-highlight --
  Syntax highlighting.
• rehype-highlight-code-lines
  -- Adds line numbers to code blocks. Supports ranges.
• remark-flexible-containers
  -- Add a callout box using the following syntax. Supported container types are
  warning, note, and experimental.
  markdown Copy

  ::: {type} {title}
  {content}
  :::

Internet-Drafts Copy Section

To build components that are being maintained as IETF Internet-Drafts, run
npm run build-ietf.

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

• https://xml2rfc.tools.ietf.org/authoring/draft-mrose-writing-rfcs.html
• https://www.ietf.org/tao.html
• https://www.ietf.org/ietf-ftp/1id-guidelines.html
• https://www.rfc-editor.org/rfc/rfc7322.txt

Test suites Copy Chapter

Conformance tests for JSON Schema and its vocabularies may be found
in their own repository.

Tests for the meta-schema are included here. Run npm test to run the
meta-schema tests. To get a test coverage report, you can use npm run test:coverage. In addition to the CLI report, a detailed HTML report will be
generated in the coverage directory and can be viewed using something like
npx http-server coverage.

The website Copy Chapter

The JSON Schema web site is at http://json-schema.org/

The source for the website is maintained in a separate repository.

Contributors Copy Chapter

Code Contributors Copy Section

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors Copy Section

Become a financial contributor and help us sustain our community. [Contribute]

Sponsors

Here are our top sponsors. You could be next! [Become a sponsor]

Individuals

License Copy Chapter

The contents of this repository are licensed under either the BSD
3-clause license or the Academic Free License v3.0.

File: adr/README.md Copy Chapter

Architectural Decision Log

This log lists the architectural decisions for the JSON Schema specification.

• ADR-2022-04-08
  - Acknowledge ambiguity in additionalProperties behaviour and fix after patch
  release

You can find the ADR for using ADRs in our community repo ADR log.

For new ADRs, please use template.md as basis. More information
on MADR is available at https://adr.github.io/madr/. General information about
architectural decision records is available at https://adr.github.io/.

2. Official Technical Reference & Guides (json-schema-org/website) Copy Chapter

<a href="https://github.com/json-schema-org/website/graphs/contributors" alt="JSON Schema GitHub website contributors">
  
</a>
<a href="https://github.com/json-schema-org/website/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22" alt="Good First JSON Schema issue">
  
</a>
<a href="https://github.com/json-schema-org/.github/blob/main/CODE_OF_CONDUCT.md" alt="Contributor Covenant">
  
</a> 
<a href="https://www.repostatus.org/#active" alt="Repo status">
  
</a> 
<a href="https://json-schema.org/slack" alt="JSON Schema Slack">
  
</a>

👋 Welcome to the JSON Schema website

This repository contains the source code of the JSON Schema website:

• Powered by Next.js,
• Uses the Tailwind CSS framework,
• Built and deployed with Netlify.

Setting up the Project Copy Chapter

Please refer to INSTALLATION.md for instructions on how to set up the project for local development.

Project structure Copy Chapter

This repository has the following structure:

├── .github                     # Definitions of GitHub workflows, pull request, and issue templates
  ├── components                  # Various generic components such as "Button", "Figure", etc.
  ├── data                        # JSON Schema implementations
  ├── styles                      # Various CSS files
  ├── lib                         # Various JS code for preparing static data to render on pages
  ├── pages                       # Website's pages source, including raw markdown files and React page templates
  │    ├── overview               # JSON Schema initiative docs
  │    ├── blog                   # Blog posts
  │    ├── learn                  # JSON Schema docs
  │    └── implementations        # Various pages to describe tools
  ├── public                      # Data for site metadata and static assets such as images
  ├── next.config.js              # Next.js configuration file

Contribute Copy Chapter

Here are some areas where you can contribute to the website:

• Blog posts
• Case studies
• Design
• Documentation improvements
• Website enhancements
• Add a new JSON Schema implementation
• JSON Schema Landscape

To identify good first issues to work on, join our Slack workspace and visit the #contribute channel. This channel is specifically designed for onboarding and supporting new contributors.

You should also check out our Contributing guidelines.

Contributors Copy Section

Thanks to these wonderful people who contributed to this website:

_{Made with contributors-img.}

Sponsors Copy Section

Backers Copy Section

Thank you to all our backers!

Connect with the JSON Schema Community Copy Chapter

Inspired by Copy Chapter

This document was inspired by AsyncAPI website README.md.

License Copy Chapter

The contents of this repository are licensed under either the BSD 3-clause license or the Academic Free License v3.0. See LICENSE.