Toon Spec 3.0

[ghost1face]

Linked Issue

Closes #17 #9 #7 #8

Description

This PR implements full compliance with TOON Specification v3.0, including critical bug fixes, test improvements, and comprehensive documentation updates. The implementation now passes all 521 tests (100% pass rate, 0 skipped) with complete specification coverage and is production-ready for .NET 8.0, 9.0 and 10.0

This incorporates changes from #17 while cleaning up code to ensure proper compilation and test validation

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test coverage improvement

Changes Made

This pull request introduces major improvements to the project's documentation, brings the codebase into full alignment with the TOON Specification v3.0, and enhances decoding logic for strict spec compliance and usability. The README now provides comprehensive usage instructions, API documentation, and feature details, reflecting the project's production-ready status. Additionally, the decoding internals have been refactored to better support quoted keys and array decoding per spec requirements, and obsolete float converters have been removed.

Documentation and Project Status Updates:

• Overhauled the README.md to include detailed usage examples, API documentation, installation instructions, type conversion tables, delimiter/key folding/path expansion options, and explicit project status. The documentation now reflects full TOON v3.0 spec compliance and production readiness. [1] [2]
• Updated script files (specgen.ps1, specgen.sh) to generate tests against TOON Specification v3.0 and output to a new GeneratedTests directory, ensuring alignment with the latest spec. [1] [2]

Core Library Improvements:

• Added detailed XML documentation to the Constants class and introduced the ToonPathExpansion enum for improved path expansion control in decoding. [1] [2]
• Refactored decoding logic in Decoders.cs to:
  • Track and handle quoted keys at the root level.
  • Adjust array and object decoding to match TOON v3.0 requirements, including correct handling of arrays as the first field in list items.
  • Improve internal method signatures for extensibility and clarity. [1] [2] [3] [4] [5] [6] [7]

Codebase Simplification:

• Removed obsolete internal converters for float/double normalization (DoubleNamedFloatToNullConverter.cs, SingleNamedFloatToNullConverter.cs) as this logic is now handled elsewhere or is no longer needed. [1] [2]

SPEC Compliance

• This PR implements/fixes spec compliance
• Spec section(s) affected: Section 2 (normalization), Section 10 (list items), Section 13.4 (path expansion)
• Spec version: v3.0 (2025-11-24)

Conformance Checklist Status (Section 13.1 & Section 13.2)

Encoder Compliance:

• UTF-8 output with LF line endings (Section 5)
• Consistent indentation (Section 12)
• String escaping (Section 7.1)
• Array length markers (Section 6, Section 9)
• Key order preservation (Section 2)
• Number normalization without scientific notation (Section 2)
• -0 → 0 conversion (Section 2)
• NaN/±Infinity → null (Section 3)
• No trailing spaces/newlines (Section 12)
• Objects as list items indentation (Section 10) ← FIXED
• Key folding when enabled (Section 13.4)

Decoder Compliance:

• Array header parsing (Section 6)
• Delimiter splitting (Section 11)
• String unescaping (Section 7.1)
• Type inference (Section 4)
• Strict mode enforcement (Section 14)
• Order preservation (Section 2)
• Path expansion (Section 13.4) ← NEW
• Conflict detection in strict mode
• LWW conflict resolution
• Objects as list items parsing (Section 10) ← VERIFIED

Testing

• All existing tests pass
• Added new tests for changes
• Tests cover edge cases and spec compliance

Pre-submission Checklist

• My code follows the project's coding standards
• I have run code formatting/linting tools
• I have added tests that prove my fix/feature works
• New and existing tests pass locally
• I have updated documentation if needed
• I have reviewed the TOON specification for relevant sections

Breaking Changes

• No breaking changes
• Breaking changes (describe migration path below)

Additional Context

[239573049]

I'm expected to be available for revisions on Friday.

[ghost1face]

I'm expected to be available for revisions on Friday.

No problem, I figured this downtime I had would be a great time to get this library up to spec and resolve the conflicts we had

[Copilot]

Pull request overview

This PR implements full compliance with TOON Specification v3.0, introducing critical bug fixes for encoding/decoding Section 10 list items with tabular arrays, comprehensive path expansion functionality (Section 13.4), improved number formatting to eliminate scientific notation, and updated project-wide namespace standardization from ToonFormat to Toon.Format. The implementation now passes 521 tests with 100% spec coverage.

Key Changes:

• Fixed Section 10 encoding/decoding for objects with arrays as first fields in list items (depth adjustments from +1 to +2)
• Added path expansion support with ToonPathExpansion enum and ToonPathExpansionException for dotted key handling
• Improved number formatting to output canonical decimal form without scientific notation per SPEC v3.0 §2

Reviewed changes

Copilot reviewed 72 out of 72 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Comprehensive documentation overhaul with API examples, type conversion tables, and feature descriptions
src/ToonFormat/Constants.cs	Added XML documentation and ToonPathExpansion enum for path expansion control
src/ToonFormat/ToonPathExpansionException.cs	New exception type for path expansion conflicts with detailed error context
src/ToonFormat/Internal/Encode/Encoders.cs	Fixed Section 10 compliance: tabular rows and array contents now appear at depth +2 on hyphen lines
src/ToonFormat/Internal/Decode/Decoders.cs	Fixed Section 10 decoding: arrays as first field decode at effective depth +2, added quoted key tracking
src/ToonFormat/Internal/Decode/PathExpansion.cs	New path expansion logic for dotted keys with conflict detection and LWW resolution
src/ToonFormat/Internal/Encode/Primitives.cs	Added FormatNumber method to eliminate scientific notation in number output
src/ToonFormat/Internal/Shared/NumericUtils.cs	New utility for converting doubles to canonical decimal form
tests/ToonFormat.Tests/**/*.cs	Updated namespaces from ToonFormat.Tests to Toon.Format.Tests
tests/ToonFormat.SpecGenerator/**/*.cs	Updated namespaces, improved error handling in GitTool, added test cleanup logic
specgen.sh, specgen.ps1	Updated to generate against TOON v3.0.0 spec and output to GeneratedTests directory

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[johannschopplich]

LGTM, thanks for the effort!

[239573049]

It seems to me that this branch can now be merged?

[ghost1face]

It seems to me that this branch can now be merged?

Yes sir.

[ghost1face]

Happy holidays and welcome back @toon-format/dotnet-maintainers ! Let's start the new year with being 3.0 compliant! LGTM!