[RFC]: Make TOON Format JSON Schema compatible

[woutervancgi]

Type of Change

• Breaking change (incompatible with current spec)
• Backward-compatible addition
• Clarification or editorial improvement
• New optional feature
• Changes to conformance requirements

Summary

As JSON (JavasScript Object Notation) is widely in use and mature as Object Notation format, using all the lessons learned form JSON in TOON (Token-Oriented Object Notation) can help maturing it quickly.
So to help in this transition and the implementation process I have converted JSON Schema Draft 2020-12 into TOON with the help of Claude Sonnet 4.5.

Updated SPEC.md SPEC-updated.md

Motivation

Problem

TOON does not yet support all features of the most popular and mature Object Notation language JSON.
This can result is larger TOON files and source files, while the intent is to have equal sized or smaller TOON files with increased predectability.

Pattern	TOON vs YAML	Reason
Reused schemas	🔴 20-30x larger	No anchors/aliases - must inline everything
allOf with base schemas	🔴 2-3x larger	Base schema copied multiple times
Error responses	🔴 30x larger	Same error schema repeated ~30 times
Nested object properties	🔴 2-5x larger	Cannot use references
Deeply nested structures	🔴 3-4x larger	All nesting must be explicit
Primitive enums	✅ ~10% smaller	Inline format wins
Tabular arrays	✅ 40-60% smaller	(But only if no nested objects!)

Use Case

Support repeatable data and data structures.
Support validation of data
Support 1:1 transformation from any JSON object
Support generating TOON output based on a well-defined schema.

Benefits

When TOON would fully implement JSON Schema we can make TOON DRY; repeating items can be implemented once and used as reference, this makes TOON even more compact.

Adopting best practices of the mature and well supported JavaScript Object Notation standard, matures TOON quickly.

Adopting JSON Schema compatibility makes it easy to adopt exiting JSON /YAML parsers to support TOON as well and transform between JSON, YAML and TOON becomes a 1:1 mapping (excluding comments in YAML).

OpenAPI / REST / MCP / A2A

Enables using TOON eventually for other purposes, like OpenAPI v3.2 REST interfaces (I have already created the specs as well, when this is proposal is reviewed an approved I'll adjust it to the potential improvements and share and make it public as well.

And thus enable TOON compatibility for standards for data exchange between AI-agents like MCP and A2A, as drop in replacement for JSON.

Training

As TOON becomes JSON Schema compliant, training LLM on TOON instead of JSON stored data can be a drop-in replacement. Thus needing potential less data/memory/storage/compute for training.

Created on request

#17 (comment)

Detailed Design

json-schema-toon-spec.toon.txt
json-schema-toon-spec.md

I have run multiple tests, please review it as well.
Let me know if you endorse this approach and like to move this way forward.

Examples

petstore-openapi-3.2.toon.txt

json-schema-toon-spec.html

Drawbacks

• existing implementations need change when wanting to support all features.

Alternatives Considered

Alternative 1: Copy data multiple times

Rejected because it increases tokens.

Alternative 2: Use YAML instead of TOON

Rejected because it decreases model output accuracy

Alternative 3: Use JSON instead of TOON

Rejected because it increases tokens and decreases model output accuracy

Alternative 4: Let TOON mature separate from the lessons learned from JSON Schema

Rejected because the time of our community is valuable, so building upon existing lessons learned reduces load and we want to use TOON in production for as many applicable cases as soon as possible.

Impact on Implementations

Attached are reference implementations (please review)

(same links as above)
json-schema-toon-spec.toon.txt
json-schema-toon-spec.md

Migration Strategy

No response

Test Cases

• 30/30 Objects - All OpenAPI v3.2.0 objects documented
• All Required Fields - Marked with badges/indicators
• All Optional Fields - Clearly documented
• All Enumerations - Parameter locations, HTTP methods, security types, OAuth flows, style values all covered

Accuracy Check:

• Field Names - Match OpenAPI specification exactly
• Field Types - Correctly specified (string, boolean, arrays, objects, maps)
• Requirements - REQUIRED vs Optional correctly identified
• Mutual Exclusivity - Documented where applicable (e.g., License identifier vs url)
• Conditional Requirements - Noted (e.g., parameter required if in=path)

TOON Syntax Check:

• Tabular Arrays - Correctly formatted: [N]{fields}: values
• Indentation - Consistent throughout
• Field Declarations - Explicit and clear
• Minimal Quoting - Only where necessary
• Nested Structures - Properly indented

Affected Specification Sections

1. Normative References

• Added [JSON-SCHEMA] reference to JSON Schema Core Draft 2020-12
• Added [JSON-SCHEMA-VALIDATION] reference to JSON Schema Validation Draft 2020-12

2. Section 17.4: JSON Schema Interoperability (NEW)

Added comprehensive subsection covering:

• Compatibility statement: TOON encodes JSON data model → fully compatible with JSON Schema
• Core vocabulary support: All keywords ($schema, $id, $ref, $defs, etc.)
• Validation vocabulary support: Complete coverage (type, numeric, string, array, object constraints)
• Applicator vocabulary support: Logical (allOf/anyOf/oneOf), conditional (if/then/else), array/object applicators
• Format vocabulary support: All 21 standard format attributes
• Annotation vocabularies: Meta-data, content, unevaluated
• Efficiency guidance: Best practices using $ref to avoid schema repetition (6.5x size reduction)
• Round-trip compatibility: Demonstrates lossless JSON Schema ↔ TOON conversion
• Practical examples: Product schema in both JSON and TOON formats

3. Appendix H: JSON Schema Compatibility (NEW - Informative)

Added complete reference appendix with 14 subsections:

H.1 Compatibility Statement

• Mathematical proof: TOON(JSON data model) + JSON Schema(validates JSON) = 100% compatible
• All vocabularies and keywords supported with identical semantics

H.2 Core Vocabulary Examples

• Schema identification ($schema, $id, $comment)
• References and definitions ($ref, $defs)
• Complete working examples in both formats

H.3 Validation Vocabulary Examples

• Type validation with multiple types and enums
• Numeric constraints (multipleOf, minimum, maximum, exclusiveMinimum/Maximum)
• String constraints (minLength, maxLength, pattern)
• Array constraints (minItems, maxItems, uniqueItems)
• Object constraints (properties, required, min/maxProperties)

H.4 Applicator Vocabulary Examples

• Logical applicators (allOf, anyOf, oneOf, not)
• Conditional schemas (if/then/else with country/postal code example)
• Array items schemas (prefixItems, items)

H.5 Format and Content Vocabularies

• All 21 format attributes in tabular TOON format (40% more compact)
• Content schemas with encoding and media type examples

H.6 Metadata Vocabulary

• Complete example with title, description, default, examples, deprecated, readOnly, writeOnly

H.7 Boolean Schemas

• Support for true (always valid) and false (always invalid) schemas

H.8 Complex Schema Example

• Complete product catalog schema demonstrating:
  • Multiple vocabularies in one schema
  • Nested objects and arrays
  • Reference usage ($ref to $defs)
  • Required fields and validation constraints

H.9 Efficiency Comparison

• Side-by-side comparison of inline vs. $ref-based schemas
• Demonstrates 6.5x size reduction with proper $ref usage
• Shows TOON achieves YAML-like efficiency when references preserved

H.10 Validation Behavior

• Normative requirements for TOON decoders
• Keyword evaluation order preservation
• Annotation collection and propagation
• Reference resolution requirements

H.11 Best Practices

Eight concrete recommendations:

1. Use $defs liberally for reusable schemas
2. Preserve $ref references (don't inline)
3. Use tabular format for uniform vocabularies
4. Leverage format attributes for semantic validation
5. Use allOf for schema composition
6. Document with title/description
7. Provide examples for valid instances
8. Prefer specific types for precise validation

H.12 Tool Support

Requirements for TOON implementations:

• JSON Schema validation
• Schema generation from TOON documents
• Format conversion (JSON/YAML/TOON)
• Reference resolution ($ref, $dynamicRef)
• Full vocabulary support (all 2020-12 vocabularies)

H.13 Interoperability Testing

• Guidelines for using JSON Schema Test Suite
• Four-step validation process
• Ensures identical validation behavior

H.14 References

Links to official JSON Schema documentation and test resources

Key Benefits

1. Complete coverage: All JSON Schema Draft 2020-12 vocabularies documented
2. Practical guidance: 25+ complete examples showing JSON vs. TOON
3. Efficiency optimization: Shows how $ref reduces schema-heavy documents by 6.5x
4. Implementation support: Clear requirements for tool developers
5. Standards compliance: Enables TOON for OpenAPI, AsyncAPI, and other schema-based specs

Backward Compatibility

This change is fully backward compatible:

• No breaking changes to existing TOON syntax
• Purely additive documentation
• Informative appendix (non-normative implementation guidance)
• Existing TOON documents remain valid

Related Use Cases

This enhancement enables TOON for:

• OpenAPI specifications: Efficient API documentation (as demonstrated in neobank-api example)
• AsyncAPI specifications: Event-driven API schemas
• Configuration validation: Application and service configs
• Data contracts: Schema-first data pipelines
• API testing: Schema-based validation in test frameworks

Files Modified

• SPEC-updated.md: Added Section 17.4 and Appendix H
• Table of Contents updated with new appendix

Specification Version

This change maintains specification version 2.0 (no breaking changes).
Future consideration: Could increment to 2.1 when finalized as formal schema interoperability feature.

Unresolved Questions

multi-level nesting becomes more YAML like

Checklist

• I have read the RFC process in CONTRIBUTING.md
• I have searched for similar proposals
• I have considered backward compatibility
• I understand this may require community discussion before acceptance

[BrickDesignerNL]

Additionally I was thinking: do we need a closing marker?
So that it's detectable that all data has been received?
For example --- (three ASCII hyphens).

I am aware this would be a breaking change.