diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 8989e95..d8639a9 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,69 +1,21 @@ name: Bug Report -description: Report an issue or inconsistency in the TOON specification +description: Report an error, contradiction, or ambiguity in the TOON specification title: '[Bug]: ' labels: [bug] body: - - type: markdown - attributes: - value: | - Thank you for reporting an issue with the TOON specification! - - Please fill out the sections below to help us understand and address the problem. - - - type: dropdown - id: bug-type - attributes: - label: Issue Type - description: What type of issue are you reporting? - options: - - Specification ambiguity or unclear language - - Contradiction in the specification - - Missing or incorrect examples - - Inconsistency between spec and test fixtures - - ABNF grammar issue - - Other specification error - validations: - required: true - - type: textarea id: description attributes: label: Description - description: A clear and concise description of the issue. - placeholder: Describe what's wrong with the specification... - validations: - required: true - - - type: textarea - id: spec-reference - attributes: - label: Specification Reference - description: Which section(s) of the specification are affected? - placeholder: | - E.g., Section 7.2, lines 320-325 - Or: SPEC.md:320-325 - validations: - required: true - - - type: textarea - id: current-behavior - attributes: - label: Current Behavior - description: What does the specification currently say? (Quote the relevant text if possible) - placeholder: | - Currently, the spec states... - render: markdown + description: What the specification says, and what it should say instead. validations: required: true - - type: textarea - id: expected-behavior + - type: input + id: section attributes: - label: Expected Behavior - description: What should the specification say instead? Or how should it be clarified? - placeholder: | - The spec should clarify that... - render: markdown + label: Section + placeholder: Β§9.3 validations: required: true @@ -71,56 +23,10 @@ body: id: example attributes: label: Example - description: Provide a concrete example that demonstrates the issue. + description: A TOON document that shows the issue. placeholder: | ```toon - items[2]{id,name}: - 1,Alice + users[2]{id,name}: + 1,Ada 2,Bob ``` - - According to Section X, this should..., but Section Y suggests... - render: markdown - - - type: textarea - id: impact - attributes: - label: Impact - description: How does this issue affect implementations or users? - placeholder: | - - Implementations may interpret this differently - - This could lead to incompatible encoders/decoders - - Edge case X is not covered - validations: - required: true - - - type: textarea - id: proposed-fix - attributes: - label: Proposed Fix - description: If you have a suggestion for how to fix this, please describe it here. - placeholder: | - I suggest updating Section 7.2 to explicitly state... - - - type: textarea - id: additional-context - attributes: - label: Additional Context - description: Any other information that might be helpful (links to related issues, implementation behavior, etc.) - placeholder: | - - Related to #123 - - The reference implementation handles this by... - - Other specifications like JSON/YAML handle this by... - - - type: checkboxes - id: checklist - attributes: - label: Checklist - description: Please confirm the following - options: - - label: I have searched for similar issues in the issue tracker - required: true - - label: I have checked the latest version of the specification - required: true - - label: This issue is about the specification itself (not implementation bugs) - required: true diff --git a/.github/ISSUE_TEMPLATE/clarification.yml b/.github/ISSUE_TEMPLATE/clarification.yml index d07e567..3f4a43b 100644 --- a/.github/ISSUE_TEMPLATE/clarification.yml +++ b/.github/ISSUE_TEMPLATE/clarification.yml @@ -1,93 +1,33 @@ name: Specification Clarification -description: Request clarification on ambiguous or unclear parts of the specification +description: Ask what a part of the specification means title: '[Clarification]: ' -labels: [question, clarification] +labels: [question] body: - - type: markdown - attributes: - value: | - Thank you for seeking clarification on the TOON specification! - - This template is for questions about what the spec means or how it should be interpreted. - If you've found an error, please use the Bug Report template instead. - - type: textarea id: question attributes: label: Question - description: What part of the specification needs clarification? - placeholder: I'm unclear about how... validations: required: true - - type: textarea - id: spec-reference + - type: input + id: section attributes: - label: Specification Section - description: Which section(s) are you asking about? - placeholder: | - E.g., Section 9.3, "Arrays of Objects – Tabular Form" - validations: - required: true - - - type: textarea - id: confusion - attributes: - label: Source of Confusion - description: What specifically is ambiguous or unclear? - placeholder: | - The specification says "X", but it's not clear if this means... - - Interpretation A: ... - - Interpretation B: ... - render: markdown + label: Section + placeholder: Β§9.3 validations: required: true - type: textarea id: example attributes: - label: Example Case - description: Provide a concrete example that demonstrates your question. + label: Example + description: A TOON document your question is about. placeholder: | - For instance, given this TOON: ```toon - items[2]{id,name}: - 1,Alice + users[2]{id,name}: + 1,Ada 2,Bob ``` - - Should this be encoded as... or ...? - render: markdown validations: required: true - - - type: textarea - id: context - attributes: - label: Use Case / Context - description: Why does this clarification matter? What are you trying to implement or understand? - placeholder: | - I'm implementing a TOON encoder and need to know... - Or: I'm writing test cases for... - - - type: textarea - id: tested-behavior - attributes: - label: Reference Implementation Behavior - description: Have you checked how the reference implementation handles this? What does it do? - placeholder: | - The reference implementation in JavaScript does X... - Or: I haven't tested this yet. - - - type: checkboxes - id: checklist - attributes: - label: Checklist - description: Please confirm the following - options: - - label: I have read the relevant specification sections - required: true - - label: I have searched for similar questions in existing issues - required: true - - label: I have checked the examples in the specification - required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 53d67ec..65c0454 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,14 +1,14 @@ blank_issues_enabled: false contact_links: - - name: πŸ’¬ GitHub Discussions + - name: GitHub Discussions url: https://github.com/toon-format/spec/discussions about: Ask questions, share ideas, or discuss the specification with the community - - name: πŸ“– Read the Specification + - name: Read the Specification url: https://github.com/toon-format/spec/blob/main/SPEC.md about: Read the complete TOON specification - - name: πŸ§ͺ Test Fixtures + - name: Test Fixtures url: https://github.com/toon-format/spec/tree/main/tests about: Browse language-agnostic test fixtures for validating implementations - - name: πŸ’» Reference Implementation + - name: Reference Implementation url: https://github.com/toon-format/toon about: TypeScript/JavaScript reference implementation with encoder, decoder, and CLI diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index c727352..1bda1a5 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,34 +1,16 @@ name: Feature Request / RFC description: Propose a new feature or change to the TOON specification title: '[RFC]: ' -labels: [enhancement, RFC] +labels: [enhancement] body: - type: markdown attributes: - value: | - Thank you for proposing an enhancement to the TOON specification! - - This template follows the RFC (Request for Comments) process outlined in CONTRIBUTING.md. - Major changes require community discussion before acceptance. - - - type: checkboxes - id: change-type - attributes: - label: Type of Change - description: What type of change are you proposing? (Check all that apply) - options: - - label: Breaking change (incompatible with current spec) - - label: Backward-compatible addition - - label: Clarification or editorial improvement - - label: New optional feature - - label: Changes to conformance requirements + value: Check [.out-of-scope](https://github.com/toon-format/spec/tree/main/.out-of-scope) first – it records proposals that were already declined. - type: textarea id: summary attributes: label: Summary - description: Brief overview of the proposed change (1-3 sentences). - placeholder: This proposal adds support for... validations: required: true @@ -36,180 +18,24 @@ body: id: motivation attributes: label: Motivation - description: Why is this change needed? What problems does it solve? - placeholder: | - ## Problem - Currently, the spec doesn't handle X, which causes... - - ## Use Case - When implementing Y, I need to... - - ## Benefits - This change would allow... - render: markdown + description: The problem this solves, and why the current specification can't. validations: required: true - type: textarea - id: detailed-design + id: example attributes: - label: Detailed Design - description: Technical specification of the proposed change. Be as precise as possible. + label: Example + description: The same data as TOON today and as TOON with your change. placeholder: | - ## Proposed Syntax - ```toon - ``` + Before: - ## Encoding Rules - - When encoding X, implementations MUST... - - The syntax SHALL be... - - ## Decoding Rules - - When decoding Y, parsers SHOULD... - - ## Grammar Changes - If ABNF changes are needed, specify them here. - render: markdown - validations: - required: true - - - type: textarea - id: examples - attributes: - label: Examples - description: Provide concrete examples showing the proposed feature in action. - placeholder: | - ### Before (current spec) ```toon ``` - ### After (proposed) - ```toon - ``` + After: - ### Use Case Example ```toon ``` - render: markdown - validations: - required: true - - - type: textarea - id: drawbacks - attributes: - label: Drawbacks - description: What are the costs and downsides of this proposal? - placeholder: | - - Increased complexity in parsers - - Breaking change requiring migration - - Potential performance impact - - Could conflict with future features - validations: - required: true - - - type: textarea - id: alternatives - attributes: - label: Alternatives Considered - description: What other designs did you consider? Why is this approach better? - placeholder: | - ### Alternative 1: ... - Rejected because... - - ### Alternative 2: ... - This approach is better because... - - ### Do Nothing - Not acceptable because... - validations: - required: true - - - type: textarea - id: impact - attributes: - label: Impact on Implementations - description: How will this affect existing implementations? - placeholder: | - - **Reference implementation:** Requires changes to... - - **Community implementations:** Need to update... - - **Backward compatibility:** Existing documents will... - - **Migration path:** Implementers should... - validations: - required: true - - - type: textarea - id: migration - attributes: - label: Migration Strategy - description: If this is a breaking change, how should implementations and users migrate? - placeholder: | - ## For Implementers - 1. Update encoder to... - 2. Update decoder to... - 3. Add validation for... - - ## For Users - Existing TOON documents can be migrated by... - - - type: textarea - id: test-cases - attributes: - label: Test Cases - description: Provide test fixtures demonstrating the proposed behavior. - placeholder: | - ```json - { - "name": "test case name", - "input": { ... }, - "expected": "...", - "note": "Tests that..." - } - ``` - render: json - - - type: textarea - id: spec-sections - attributes: - label: Affected Specification Sections - description: Which sections of SPEC.md need to be updated? - placeholder: | - - Section 9.3: Arrays of Objects - Tabular Form - - Section 6: Header Syntax - - Appendix A: Examples validations: required: true - - - type: textarea - id: unresolved - attributes: - label: Unresolved Questions - description: What parts of the design still need discussion? - placeholder: | - - Should this apply to X or only Y? - - What should happen in edge case Z? - - Is this syntax intuitive enough? - - - type: textarea - id: additional-context - attributes: - label: Additional Context - description: Any other information (links, research, similar features in other formats, etc.) - placeholder: | - - Similar to JSON's handling of... - - Related to issue #123 - - Research on token efficiency impact... - - - type: checkboxes - id: checklist - attributes: - label: Checklist - description: Please confirm the following - options: - - label: I have read the RFC process in CONTRIBUTING.md - required: true - - label: I have searched for similar proposals - required: true - - label: I have considered backward compatibility - required: true - - label: I understand this may require community discussion before acceptance - required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a302661..6a0f8f8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,72 +1,5 @@ ## Description - + -## Type of Change - - - -- [ ] πŸ“ Clarification (typo fix, grammar improvement, clarifying language) -- [ ] πŸ“š Documentation (adding examples, improving structure) -- [ ] ✨ Minor change (backward-compatible addition or clarification) -- [ ] πŸ”₯ Major change (breaking change or incompatible syntax/behavior change) -- [ ] πŸ§ͺ Test fixtures (adding or updating test cases) -- [ ] πŸ”§ Other (please describe): - -## Motivation and Context - - - - -## Changes Made - - - -- -- -- - -## Specification Sections Affected - - - -- Section X.X: [Section name] -- - -## Backward Compatibility - - - -- [ ] βœ… Fully backward-compatible (no breaking changes) -- [ ] ⚠️ Potentially breaking (requires careful review) -- [ ] πŸ’₯ Breaking change (requires major version bump) - -### Impact on Existing Implementations - - - -- -- - -## Examples - - - -### Before - -```toon -``` - -### After - -```toon -``` - -## Checklist - -- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md) -- [ ] My changes follow the specification writing style guidelines -- [ ] I have used RFC 2119 keywords (MUST, SHOULD, MAY) correctly where applicable -- [ ] I have updated CHANGELOG.md with my changes -- [ ] For breaking changes: I have provided a migration strategy -- [ ] Test fixtures added or updated (if applicable) +Closes # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4acf8d9..f4336a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,5 @@ # 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 | @@ -11,64 +9,20 @@ Thanks for your interest in contributing! This guide shows how to propose change | **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: +New syntax, quoting or escaping changes, and changes to tabular detection need an RFC – check [`.out-of-scope/`](./.out-of-scope/) first. 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/`, run `pnpm test` to validate it against `tests/fixtures.schema.json`, and submit a PR. - -See [tests/README.md](./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](./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](./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. +3. Submit PR using the template and link related issues ## Style Guidelines @@ -81,10 +35,6 @@ Follow [SPEC.md](./SPEC.md) conventions: - **Structure**: Number sections, cross-reference related rules - **Line length**: 80-120 characters for readability -## Maintainer - -[@johannschopplich](https://github.com/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. diff --git a/README.md b/README.md index 21f28a2..173c6a2 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,11 @@ This repository contains the official specification for **Token-Oriented Object Notation (TOON)**, a line-oriented, indentation-based encoding of the JSON data model. See [github.com/toon-format/toon](https://github.com/toon-format/toon) for an overview, rationale, and benchmarks. -## πŸ“‹ Specification +## Specification [β†’ Read the full specification (SPEC.md)](./SPEC.md) -- **Version:** 4.1 (2026-07-26) -- **Status:** Working Draft -- **License:** MIT - -The specification includes ABNF snippets, encoding rules, validation requirements, and conformance criteria. +Version 4.1, Working Draft. ## Serialization Example @@ -64,16 +60,13 @@ Media type `text/toon` (provisional, UTF-8), file extension `.toon`. See [Β§17 o See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to propose changes and when an RFC is required. For implementation-specific questions or bugs, use the respective implementation repository. -## Versioning - -The TOON specification uses MAJOR.MINOR versioning. See [VERSIONING.md](./VERSIONING.md) for the policy and compatibility guarantees. - ## Resources - **Glossary:** [CONTEXT.md](./CONTEXT.md) – Canonical name for every concept, and the wordings to avoid - **Examples:** [examples/](./examples/) – Working examples organized by feature - **Test Fixtures:** [tests/fixtures/](./tests/fixtures/) – Reference test fixtures - **Changelog:** [CHANGELOG.md](./CHANGELOG.md) – Version history and changes +- **Versioning:** [VERSIONING.md](./VERSIONING.md) – MAJOR.MINOR policy and compatibility guarantees - **Reference Implementation:** [github.com/toon-format/toon](https://github.com/toon-format/toon) – TypeScript/JavaScript implementation - **Implementations:** [toonformat.dev/ecosystem/implementations](https://toonformat.dev/ecosystem/implementations) – Official and community ports - **Benchmarks:** [Reference repo benchmarks/](https://github.com/toon-format/toon/tree/main/benchmarks) – Token efficiency measurements and accuracy retrieval tests diff --git a/VERSIONING.md b/VERSIONING.md index a379cf5..13cc65d 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -45,15 +45,9 @@ Breaking changes (requiring a MAJOR version bump) include: Non-breaking changes (MINOR version bump) include: -### Clarifications - -- Clarifying ambiguous language without changing behavior. -- Adding examples to illustrate existing rules. -- Improving specification wording for clarity. -- Adding informative (non-normative) sections. - ### Backward-Compatible Additions +- Adding informative (non-normative) sections. - Adding optional features that don't affect existing documents. - Adding new SHOULD or MAY recommendations. - Expanding the specification to cover previously undefined behavior (if done in a backward-compatible way). @@ -63,13 +57,6 @@ Non-breaking changes (MINOR version bump) include: - Encoder-side tightening: raising a SHOULD or MAY to MUST or MUST NOT for encoder output, or adding a new constraint on what encoders emit. This is MINOR only while every decoder rule of the previous MAJOR version survives unchanged, so output from older encoders keeps decoding as before. Retiring a form the previous version let encoders emit therefore requires keeping the decoder's obligation to accept it. - Changing the treatment of encoder-unreachable documents. A document is encoder-unreachable when no conforming encoder of the previous MAJOR version could emit it, so it can only have been hand-authored or produced by other means and no round-trip yields it. Reinterpreting such a document, or rejecting it outright, is MINOR. -### Documentation Improvements - -- Grammar and typo fixes. -- Reorganizing content for better readability. -- Adding cross-references. -- Improving examples. - ## Version Lifecycle ### Working Draft @@ -84,20 +71,11 @@ Non-breaking changes (MINOR version bump) include: - Version number is assigned when changes are merged. - Previous versions remain available for reference. -### Deprecation - -If we need to make a breaking change (MAJOR version bump): - -1. **Announcement:** We add a deprecation notice to the current spec -2. **Migration Period:** The next MINOR version includes migration guidance -3. **New Major Version:** Breaking changes are released in the next MAJOR version -4. **Support:** Previous MAJOR versions remain available – we don't break old links - ## Implementation Compatibility When in doubt, we err on the side of caution and treat potentially breaking changes as MAJOR version bumps. -Implementations should document the supported spec version (e.g., `toon-spec: 4.1`, as in SPEC.md Β§13) and may support multiple versions concurrently: default to the latest, let users target a specific version, and document version-specific behavior. A new MINOR version keeps existing conformant implementations conformant. A new MAJOR version may require updates; previous-version implementations remain valid, and its CHANGELOG.md entry carries the migration guidance. A MINOR version that renames or retires a public concept handle (for example an option name) carries a migration note in CHANGELOG.md naming the old and new spelling. +A new MINOR version keeps existing conformant implementations conformant. A new MAJOR version may require updates; previous-version implementations remain valid, and its CHANGELOG.md entry carries the migration guidance. A MINOR version that renames or retires a public concept handle (for example an option name) carries a migration note in CHANGELOG.md naming the old and new spelling. ## Version History diff --git a/tests/README.md b/tests/README.md index 6993848..039602d 100644 --- a/tests/README.md +++ b/tests/README.md @@ -2,22 +2,11 @@ This directory contains **language-agnostic JSON test fixtures** for validating TOON implementations against the specification. These fixtures cover core specification requirements; conformance is defined by SPEC.md (Β§13 and Appendix C), not by this fixture suite. -## Directory Structure - -``` -tests/ -β”œβ”€β”€ fixtures.schema.json # JSON Schema for fixture validation -β”œβ”€β”€ fixtures/ -β”‚ β”œβ”€β”€ encode/ # Encoding tests (JSON β†’ TOON) -β”‚ └── decode/ # Decoding tests (TOON β†’ JSON) -└── README.md # This file -``` - The [Test Coverage](#test-coverage) tables below index every fixture file. ## Fixture Format -All test fixtures follow a standard JSON structure defined in [`fixtures.schema.json`](./fixtures.schema.json): +Every fixture file follows [`fixtures.schema.json`](./fixtures.schema.json), which documents each field and option: ```json { @@ -37,49 +26,6 @@ All test fixtures follow a standard JSON structure defined in [`fixtures.schema. } ``` -### Field Descriptions - -| Field | Required | Description | -|-------|----------|-------------| -| `version` | Yes | Baseline TOON spec version for this file. Per-test `minSpecVersion` overrides this for individual tests that exercise newer behavior. Fixtures remain valid for all later versions. | -| `category` | Yes | Test category: `"encode"` or `"decode"` | -| `description` | Yes | Brief description of what this fixture tests | -| `tests` | Yes | Array of test cases | -| `tests[].name` | Yes | Descriptive name explaining what is validated | -| `tests[].input` | Yes | Input value (JSON for encode, TOON string for decode) | -| `tests[].expected` | Yes | Expected output (TOON string for encode, JSON for decode) | -| `tests[].shouldError` | No | If `true`, expects an error (default: `false`) | -| `tests[].options` | No | Encoder/decoder options (see below) | -| `tests[].specSection` | No | Reference to specification section (e.g., `"7.2"`, `"Β§6"`) | -| `tests[].note` | No | Optional explanation for special cases | -| `tests[].minSpecVersion` | No | Minimum spec version required (e.g., `"4.1"`) | - -### Options - -#### Encoding Options - -```json -{ - "delimiter": ",", - "indentSize": 2 -} -``` - -- `delimiter`: `","` (comma, default), `"\t"` (tab), or `"|"` (pipe). Affects encoder output; decoders parse the delimiter declared in array headers -- `indentSize`: Number of spaces per indentation level (default: `2`) - -#### Decoding Options - -```json -{ - "indentSize": 2, - "strict": true -} -``` - -- `indentSize`: Expected number of spaces per indentation level (default: `2`) -- `strict`: Enable strict validation (default: `true`) - ### Error Tests Error tests use `shouldError: true` to indicate that the test expects an error to be thrown: @@ -146,10 +92,6 @@ Load each fixture file, run every entry in its `tests` array through your encode **Coverage note:** Β§3 host-type normalization (NaN/Β±Infinity β†’ null, host Date/Set/Map/BigInt mappings) is intentionally outside these JSON fixtures, since the fixture format cannot express non-JSON encode inputs. Implementations should cover Β§3 in their language-local test suites. -## Validating Fixtures - -`pnpm test` validates every fixture against [`fixtures.schema.json`](./fixtures.schema.json) and checks that its `category` matches its directory. - ## Contributing Test Cases -Add your test to the matching fixture file, reference the spec section it exercises, verify the expected output against SPEC.md, and run `pnpm test` before submitting a PR. See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines. +Add a case to the matching fixture file with its `specSection`, check `expected` against SPEC.md, and run `pnpm test` – it validates every fixture against the schema and checks that its `category` matches its directory.