Skip to main content
Thanks for taking the time to contribute to JSON Schema!

​
Overview

JSON Schema is an evolving language, and the specification repository contains both the specification text and Pull Requests with suggested improvements and contributions.

​
Types of Contributions

​
Editorial Contributions

Contributions that do not change the interpretation of the spec are encouraged and often merged quickly:
  • Improving legibility
  • Fixing editorial errors
  • Clearing up ambiguity
  • Improving examples
Editorial contributions can be merged by a spec editor with minimal process.

​
Specification Changes

Contributions that meaningfully change the interpretation of the spec must follow the Specification Development Process.
Changes affecting implementation behavior should typically be opened as an issue first, not directly as a pull request.

​
Submitting Issues

Issues should identify:
  • A problem, enhancement, or use case
  • A proposed course of action for the draft

​
Support Channels

For questions and support (rather than issues), see the SUPPORT.md file.

​
Creating Pull Requests

​
General Guidelines

1

Target the correct branch

Pull requests should generally be made to the main branch.Exception: During a patch phase, target the patch branch (e.g., 2020-12-patch) instead.
2

Reference related issues

If the pull request would solve a particular issue, reference the issue in the PR description.
3

Wait for review

Most PRs, including all PRs that impact implementation behavior, will be left open for a minimum of 14 days.
Minor wording fixes may be merged more quickly once approved by a project member.

​
What to Contribute

Editorial Suggestions

Improvements to clarity, grammar, and examples that don’t change behavior

Issue Resolutions

Pull requests that resolve open issues in the repository

​
Milestones

Milestones help organize the specification development work:
  • Each milestone estimates work for the next draft
  • Named after the meta-schema draft number
  • The open milestone with the lowest draft number is the current active project

​
Milestone Management

Issues may be removed from a milestone due to:
  • Lack of consensus
  • Lack of expertise to create a PR
  • Deferral to publish a draft sooner
The draft-future milestone is for issues that should be addressed but have no specific timeline.
Numbered milestones other than the lowest-numbered one tentatively organize future work but may be reorganized when work begins.

​
Community Guidelines

​
Code of Conduct

All official channels follow the Code of Conduct, including:
  • Mailing list
  • GitHub organization
  • Slack server

​
Communication Channels

You can interact with the community through:

Slack Workspace

Join the #specification channel at json-schema.org/slack to:
  • Interact with community members
  • Share new ideas
  • Ask questions about specification development

GitHub Issues

Use the issues tracker for:
  • Reporting problems
  • Proposing enhancements
  • Discussing specification changes

​
Architectural Decision Records (ADRs)

JSON Schema uses ADRs to document architectural decisions. When contributing features that require architectural decisions:
  • Use the ADR template from the adr/template.md file
  • Follow the MADR format (More information at adr.github.io/madr)
  • Include context, considered options, and decision rationale
ADRs are stored in the adr/ directory and become part of the permanent record when features become stable.

​
Getting Help

If you have questions about contributing:
  1. Check the Specification Development Process documentation
  2. Review existing proposals for examples
  3. Ask in the #specification Slack channel
  4. Reference the SUPPORT.md for additional resources