Proposals

Needs a proposal	A pull request is enough
A new field or object	A fix to wording that does not change meaning
A new numbered rule, or a change to one	A new example document
A new value in a closed vocabulary	A new tool on the Implementations page
A change to the configuration id	A fix to the checker that brings it in line with the specification
A deprecation

Needs a proposal

A pull request is enough

A new field or object

A fix to wording that does not change meaning

A new numbered rule, or a change to one

A new example document

A new value in a closed vocabulary

A new tool on the Implementations page

A change to the configuration id

A fix to the checker that brings it in line with the specification

A deprecation

The process

Open an issue

Describe the problem, not the solution: which records you cannot express today, and who would write and read the new data. Most proposals are shaped here.

Write the proposal

Open a pull request with the proposal text, using the template below. Its status is Draft.

Review

The proposal is discussed on the pull request, and moves to In review when it is complete. Maintainers look for a real producer and a real consumer of the change.

Decision

Maintainers accept or reject it, and say why in the pull request. An Accepted proposal is scheduled for a minor version.

Release

A proposal is Final when a version ships with all of its parts: the schema change, the specification text, a numbered rule and a passing and failing document for anything a checker can enforce, the check in the reference checker, a changelog entry, and a migration if older documents need one.

A proposal can also be Withdrawn by its author or Rejected.

Template

# Title

Status: Draft
Author:
Created: YYYY-MM-DD

## Summary
One paragraph.

## Motivation
What cannot be expressed today, and who needs it: which producers would write it, which consumers would read it.

## Specification
The schema change, field by field, and any numbered rules, in the specification's own terms.

## Compatibility
What existing documents and older readers do after the change, and why it keeps the versioning promise.
If anything is deprecated: the replacement, and the version it is removed in.

## Examples
A passing document, and for each rule a failing one.

## Alternatives
What else was considered, including an `ext` namespace.

## Reference implementation
A link to the checker change and, if possible, a producer that writes the new data.

Data that only one tool writes usually belongs in that tool’s ext namespace first. When several producers write the same kind of data, it is a good candidate for a proposal. See Extensions.

Get involved

Governance

The process

Template

​The process

​Template

The process

Template