Adding XML Support

[metalshark]

Description

Expanded SPEC.md to version 4.0 with comprehensive XML support, including sections for namespaces, attributes, repeated elements, mixed content, CDATA, and XML encoding/decoding. Added XML-related references, examples, and conformance requirements. Updated examples/README.md to document new XML example files and their coverage. Added new XML example and test fixture files for conversions, valid, and invalid cases.

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, new syntax, conformance requirement change)
• 🧪 Test fixtures (adding or updating test cases)
• 🔧 Other (please describe):

Motivation and Context

I would like to convert XML files to TOON. Spending around a month playing about with different formats across differing models adding/removing support with a focus on the model understanding the raw data, I think I've settled on the right combination of support for XML. DTD, pre-processors, understanding attributes, etc did not seem to add any value to comprehension of the data being provided.

Changes Made

• Updated SPEC.md to include XML support, bumping it to version 4
• Added XML examples
• Added XML tests

Specification Sections Affected

New Sections Added

Section 22: XML Constructs

• 22.1 Document Structure
• 22.2 Element Representation
• 22.3 Qualified Names

Section 23: Namespaces

• 23.1 Namespace Declaration Syntax
• 23.2 Namespace Scope
• 23.3 Built-in Namespaces
• 23.4 Namespace URI Encoding
• 23.5 Default Namespace

Section 24: Attributes

• 24.1 Attribute Syntax
• 24.2 Attribute with Content
• 24.3 Elements with Attributes and Text Content
• 24.4 Qualified Attributes
• 24.5 Attribute Value Types
• 24.6 Attribute Quoting

Section 25: Repeated Elements

• 25.1 Array Syntax for Repeated Elements
• 25.2 List Form for Complex Elements
• 25.3 Tabular Form for Uniform Elements
• 25.4 Preserving Order with Interleaved Elements
• 25.5 Implicit Repeated Element Detection

Section 26: Mixed Content

• 26.1 Mixed Content Arrays
• 26.2 Elements with Text and Attributes
• 26.3 Text-Only Elements
• 26.4 Tabular Form with Text Content
• 26.5 Whitespace in Mixed Content

Section 27: CDATA and Text Content

• 27.1 Text Content Representation
• 27.2 CDATA Sections
• 27.3 Entity References
• 27.4 Whitespace Normalization

Section 28: XML Encoding and Decoding

• 28.1 XML to TOON Encoding
• 28.2 TOON to XML Decoding
• 28.3 Encoding Options
• 28.4 Decoding Options
• 28.5 Validation
• 28.6 Error Handling

Appendix H: XML Examples (Informative)

• H.1 Namespaced Document
• H.2 Repeated Elements
• H.3 Mixed Content
• H.4 XHTML Document
• H.5 RSS Feed
• H.6 Interleaved Elements

Modified Sections

Section 1: Terminology and Conventions

• Added: 1.10 XML-Related Terms

Section 2: Data Model

Restructured into subsections:

• 2.1 JSON Data Model
• 2.2 XML Data Model (new)

Section 3: Encoding Normalization (Reference Encoder)

• Added: 3.1 XML Normalization

Section 4: Decoding Interpretation (Reference Decoder)

• Added: 4.1 Extended Syntax Features

Section 6: Header Syntax (Normative)

• Updated ABNF grammar to support namespace prefixes in keys

Section 7: Strings and Keys

• Updated key encoding rules (§7.3) to support namespace prefixes

Section 13: Conformance and Options

• Added XML-related conformance requirements
• Added preserveNamespaces encoder option

Section 14: Strict Mode Errors and Diagnostics (Authoritative Checklist)

• Renamed: 14.6 Extended Syntax Errors (was "Recommended Error Messages and Validator Diagnostics")
• Added: 14.7 Recommended Error Messages and Validator Diagnostics (Informative)

Section 17: Interoperability and Mappings (Informative)

• Added: 17.4 XML Interoperability

Section 18: IANA Considerations

• Updated media type registration to include optional mode parameter

Appendix B: Parsing Helpers (Informative)

• Added: B.7 Text Content Parsing

Appendix D: Document Changelog (Informative)

• Added: v4.0 (2026-01-15) changelog entry

Appendix G: Host Type Normalization Examples (Informative)

• Added XML type normalization examples for Go, JavaScript, Python, and Rust
• Modified Subsections (Content Updates)
• Introduction: Relationship to JSON, CSV, YAML, and XML (Informative)
• Added XML comparison section

Abstract

• Updated to reflect unified JSON and XML support

Purpose and Scope

• Expanded to include XML document serialization use cases

Type Terms (§1.6)

• Updated object and array definitions to support XML constructs

Conformance Checklists (§13)

• Added XML-related requirements for encoders, decoders, and validators

Backward Compatibility

• ✅ Fully backward-compatible (no breaking changes)
• ⚠️ Potentially breaking (requires careful review)
• 💥 Breaking change (requires major version bump)

Impact on Existing Implementations

• adding new support such as namespaces namespace:key: value will no longer cause an implementation expecting an error to trigger one
• key names are no longer required (to allow for text/node intermixing in XML), if an implementation always expects one

Examples

Numerous included in the examples folder of the PR.

Test Coverage

• Existing test fixtures pass
• New test fixtures added (if applicable)
• Examples in SPEC.md updated
• Reference implementation behavior documented

Documentation

• SPEC.md updated
• CHANGELOG.md updated
• Examples updated (if applicable)
• README.md updated (if applicable)
• Test fixtures updated (if applicable)

Checklist

• I have read CONTRIBUTING.md
• I have searched for similar PRs and issues
• My changes follow the specification writing style guidelines
• I have used RFC 2119 keywords (MUST, SHOULD, MAY) correctly where applicable
• I have provided clear examples
• I have updated CHANGELOG.md with my changes
• I have considered the impact on existing implementations
• For breaking changes: I have provided a migration strategy
• All new and existing tests pass

---

For Maintainers:

• Version number assigned (if needed)
• Spec version updated (if applicable)
• Breaking change documented in VERSIONING.md (if applicable)
• Community implementations notified (if breaking change)