Contributing to TOON Specification

Thanks for your interest in contributing! This guide shows how to propose changes to the specification.

Quick Reference: What Process Do I Need?

Change Type	Examples	Process
Fixes	Typos, grammar, broken links, clarifying wording	Direct PR
Test Fixtures	New test cases, edge case tests, validation tests	Direct PR (see tests/README.md)
Minor Changes	Spec clarifications that may affect implementations	Issue first → PR
Major Changes	New syntax, encoding rules, breaking changes	RFC process (see below)

Does My Change Need an RFC?

Yes – RFC Required

Changes that affect compatibility or core behavior need community discussion:

Adding new delimiter types (beyond comma/tab/pipe)
  Example: Supporting semicolon as delimiter

Changing quoting or escape rules
  Example: Adding new short-form escapes (e.g., \v, \f)
  Example: Changing when colons require quotes

Modifying tabular detection logic
  Example: Allowing non-uniform objects in tabular form

New data type normalization rules
  Example: Handling Map or Set differently

Changing array header syntax
  Example: Making field lists mandatory for all arrays

No – Direct PR or Issue First

Typos, additional examples, clarifications of existing wording, extra test coverage, and documenting existing edge cases can be filed as a direct PR (or an issue if you want to discuss first).

RFC Process

For major changes requiring RFC:

1. Create RFC Issue using the Feature Request/RFC template
2. Discussion Period (minimum 1-2 weeks for community feedback)
3. Decision (maintainers accept, reject, or request revisions)
4. Implementation (create PR referencing RFC issue)

Contributing Test Fixtures

Test fixtures validate TOON implementations across languages. Add your test to tests/fixtures/encode/ or tests/fixtures/decode/, validate against tests/fixtures.schema.json, and submit a PR.

See tests/README.md for fixture structure and guidelines.

Pull Request Guidelines

1. Fork the repository and create a feature branch
2. Make changes following SPEC.md style (RFC 2119 keywords, examples, precision)
3. Update CHANGELOG.md with your changes
4. Submit PR using the template and link related issues

Review process:

• Maintainers review and may request changes
• Breaking changes held until next major version
• Approved changes merged with version number assigned

Specification Principles

See the Introduction in SPEC.md for TOON's purpose, applicability, and non-goals. Proposals should align with the priorities stated there: token efficiency, deterministic JSON round-trip, unambiguous human-readable structure, and strict validation.

Style Guidelines

Follow SPEC.md conventions:

• RFC 2119 keywords: Use MUST/SHOULD/MAY correctly (see SPEC.md §1.1)
• Terminology: Use the canonical names in CONTEXT.md
• Examples over prose: Show concrete input/output for complex rules
• Precision: Zero ambiguity – multiple implementations must agree
• Structure: Number sections, cross-reference related rules
• Line length: 80-120 characters for readability

Maintainer

@johannschopplich. For major architectural decisions, please open a discussion issue first.

License

By contributing, you agree your contributions will be licensed under the MIT License.