## 1. Project Overview & Quickstart (json-schema-org/json-schema-spec) ## File: README.md # Welcome to JSON Schema [](https://github.com/json-schema-org/.github/blob/main/CODE_OF_CONDUCT.md) [](https://www.repostatus.org/#active) [](https://opencollective.com/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](http://json-schema.org/specification.html) on the website. ## Call for contributions and feedback Reviews, comments and suggestions are most welcome! Please read our [guidelines for contributing](CONTRIBUTING.md). ## Status For the current status of issues and pull requests, please see the following labels [](https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aopen+is%3Aissue+label%3A%22Status%3A+Available%22) [](https://github.com/json-schema-org/json-schema-spec/labels/Status:%20In%20Progress) [](https://github.com/json-schema-org/json-schema-spec/labels/Status%3A%20Review%20Needed) [![Critical](https://img.shields.io/github/issues/json-schema-org/json-schema-spec/Priority:%20Critical.svg?color=critical )](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Critical) [](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20High) [](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Medium) [](https://github.com/json-schema-org/json-schema-spec/labels/Priority%3A%20Low) Labels are assigned based on [Sensible GitHub Labels](https://github.com/Relequestual/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](https://remark.js.org/), a markdown engine with good support for plugins and lots of existing plugins we can use. Remark also has a [language server](https://github.com/remarkjs/remark-language-server) and a [VSCode extension](https://github.com/remarkjs/vscode-remark) 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](https://github.com/remarkjs/remark-lint) -- Enforce markdown style guide. - [remark-validate-links](https://github.com/remarkjs/remark-validate-links) -- Check for broken links. - [remark-gfm](https://github.com/remarkjs/remark-gfm) -- Adds support for GitHub Flavored Markdown specific markdown features such as autolink literals, footnotes, strikethrough, tables, and tasklists. - [remark-heading-id](https://github.com/imcuttle/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](./remark/remark-headings.js) -- 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](./remark/remark-reference-links.js) -- Adds new syntax for referencing a section of the spec using the section number as the link text. - Example: ```markdown ## 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](./remark/remark-table-of-contents.js) -- Adds a table of contents in a section with a header called "Table of Contents". - [remark-code-titles](./remark/remark-code-titles.js) -- Add titles to code blocks - Example: ```markdown \`\`\`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](https://github.com/rehypejs/rehype-highlight) -- Syntax highlighting. - [rehype-highlight-code-lines](https://github.com/ipikuka/rehype-highlight-code-lines) -- Adds line numbers to code blocks. Supports ranges. - [remark-flexible-containers](https://github.com/ipikuka/remark-flexible-containers) -- Add a callout box using the following syntax. Supported container types are `warning`, `note`, and `experimental`. ```markdown ::: {type} {title} {content} ::: ``` ### Internet-Drafts 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: - - - - ## Test suites Conformance tests for JSON Schema and its vocabularies may be found [in their own repository](https://github.com/json-schema-org/JSON-Schema-Test-Suite). 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 The JSON Schema web site is at The source for the website is [maintained in a separate repository](https://github.com/json-schema-org/website). ## Contributors ### Code Contributors This project exists thanks to all the people who contribute. \[[Contribute](CONTRIBUTING.md)]. [](https://github.com/json-schema-org/json-schema-spec/graphs/contributors) ### Financial Contributors Become a financial contributor and help us sustain our community. \[[Contribute](https://opencollective.com/json-schema/contribute)] #### Sponsors Here are our top sponsors. You could be next! \[[Become a sponsor](https://opencollective.com/json-schema#sponsor)] [](https://opencollective.com/json-schema/sponsor/0/website) [](https://opencollective.com/json-schema/sponsor/1/website) [](https://opencollective.com/json-schema/sponsor/2/website) [](https://opencollective.com/json-schema/sponsor/3/website) [](https://opencollective.com/json-schema/sponsor/4/website) [](https://opencollective.com/json-schema/sponsor/5/website) [](https://opencollective.com/json-schema/sponsor/6/website) [](https://opencollective.com/json-schema/sponsor/7/website) [](https://opencollective.com/json-schema/sponsor/8/website) [](https://opencollective.com/json-schema/sponsor/9/website) #### Individuals [](https://opencollective.com/json-schema) ## License The contents of this repository are [licensed under](./LICENSE) either the BSD 3-clause license *or* the Academic Free License v3.0. --- ## File: adr/README.md # Architectural Decision Log This log lists the architectural decisions for the JSON Schema specification. - [ADR-2022-04-08](2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md) \- Acknowledge ambiguity in additionalProperties behaviour and fix after patch release You can find the ADR for using ADRs in our [community repo ADR log](https://github.com/json-schema-org/community/tree/HEAD/docs/adr). For new ADRs, please use [template.md](template.md) as basis. More information on MADR is available at . General information about architectural decision records is available at . ## 2. Official Technical Reference & Guides (json-schema-org/website) [](https://json-schema.org) # 👋 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 Please refer to [INSTALLATION.md](./INSTALLATION.md) for instructions on how to set up the project for local development. ## Project structure This repository has the following structure: ```text ├── .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 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](./CONTRIBUTING.md). ### Contributors Thanks to these wonderful people who contributed to this website: Made with [contributors-img](https://contrib.rocks). ### Sponsors [](https://opencollective.com/json-schema/sponsors.svg?avatarHeight=90) ### Backers **Thank you to all our backers!** [](https://opencollective.com/json-schema/backers.svg?avatarHeight=90) ## Connect with the JSON Schema Community [](https://json-schema.org/slack) [](https://twitter.com/jsonschema) [](https://www.linkedin.com/company/jsonschema) [](https://www.youtube.com/@JSONSchemaOrgOfficial) ## Inspired by This document was inspired by [AsyncAPI website README.md](https://github.com/asyncapi/website/blob/master/README.md). ## License The contents of this repository are licensed under either the BSD 3-clause license *or* the Academic Free License v3.0. See [LICENSE](./LICENSE).