Skip to main content

​
Overview

Once a rough consensus for a feature idea has been reached during the Concept stage, a formal proposal must be written to precisely define specification changes.

​
Creating a Proposal

1

Use the Proposal Template

The proposal uses the Proposal Template and is stored in the repository’s proposals folder.
2

Create a Draft ADR

Include a draft ADR (Architecture Decision Record) using the file name of the proposal document with an -adr suffix: {proposal-file-name}-adr.md.This ADR should include additional information from the “Concept” discussion, such as:
  • Use cases
  • Alternatives considered
  • Design rationale
  • Expected complexity
3

Update Meta-schemas

Add proposed keywords to the appropriate vocabulary meta-schemas in:
  • Latest published release
  • The main branch of the repository
The subschema for the proposed keyword should contain only a $comment keyword indicating that the feature is experimental and containing a link to the proposal document.
4

Add Tests

Add tests for the proposal to the JSON Schema Test Suite.
5

Publish Initial Draft

Once the initial draft of the proposal has been completed and published, the feature moves into the Experimentation stage.

​
Proposal Requirements

A formal proposal should precisely define:
  • The specification changes required
  • The syntax of new keywords
  • The behavior and semantics
  • How it integrates with existing features
  • Validation requirements

​
Meta-schema Format

When adding a proposed keyword to meta-schemas, use this format: 
{
  "proposedKeyword": {
    "$comment": "Experimental feature. See proposal: [link to proposal document]"
  }
}
This approach allows the proposed keyword but does not validate it, as its syntax may change during the proposal/experimentation process. It also permits different implementations to support different variations of each proposal separately.

​
From Proposal to Stable

The proposal serves as the specification for the feature during the Experimentation stage. Feedback from implementers and users will result in refinements to the proposal. To advance from Experimentation to Stable, the following criteria must be met:
  • At least five (5) implementations support the feature
  • There is sufficient evidence of use
  • No changes are requested for a period of six (6) weeks

​
If a Proposal Cannot Advance

If a proposal cannot advance to the Stable stage, it may be removed:
1

Archive Proposal

Move the proposal document to an archive subfolder.
2

Remove Keywords

Remove the keyword from the meta-schemas.
3

Archive Tests

Move any tests to an archive subfolder.
The removal of a feature which has not reached the stable state is not considered a breaking change.

​
Breaking Changes in Proposals

Breaking changes to a proposed feature MAY occur, but are highly discouraged.
Since proposals are experimental, the syntax and behavior may change based on feedback. However, once implementations begin supporting a proposal, changes should be minimized to avoid disruption.

Build docs developers (and LLMs) love

Get started for freeTalk to us