Skip to content

1.10: add JSONCanonicalWriter (RFC 8785 JCS) - #95

Merged
ThorFuchs merged 2 commits into
mainfrom
feature/1.10-jcs
Nov 12, 2026
Merged

ThorFuchs merged 2 commits into
mainfrom
feature/1.10-jcs

Conversation

@ThorFuchs

Copy link
Copy Markdown
Owner

First piece of the 1.10.0 "exact interchange" wave (roadmap: #94).

Design note (for API review)

public struct JSONCanonicalWriter: Sendable {
    public enum NumberPolicy: Sendable { case preserving, rounding }
    public init(limits: JSONLimits = .balanced, numberPolicy: NumberPolicy = .preserving)
    public func write(_ value: JSON) throws -> Data
    public func writeWithReport(_ value: JSON) throws -> JSONOperationReport<Data>
}
  • Output: RFC 8785 bytes. Compact output; keys ordered by UTF-16 code units (§3.2.3); strings with \b \t \n \f \r \" \\, \u00xx for other controls, everything else literal UTF-8; numbers in the ECMAScript Number::toString spelling of their binary64 value (§3.2.2.3).
  • Numbers: JSONNumber is an exact decimal, but JCS works on binary64.
    • .preserving (default) refuses, with .conversion/.inexactConversion, any number whose canonical spelling would denote a different exact decimal. 0.1 and 1E30 pass; 9007199254740993, 0.10000000000000001 and 1e-400 are refused. So canonical bytes never silently change a value.
    • .rounding follows RFC 8785 and rounds to the nearest binary64.
    • Values outside the finite binary64 range fail under both policies.
  • Implementation: one strict writer cursor with an added package-only canonical mode, and one invocation-owned .writing meter (admission, sort, numbers, output). Shortest digits come from Swift's round-trip Double.description (bounded at 32 bytes, checkpointed); the ECMAScript layout is rebuilt natively.
  • Out of scope: no hashing or signing, and no exported cryptography API (the internal SHA-256 stays private). The versioned envelope comes in a later 1.10 PR.
  • Unchanged: the existing writer, its .scalar key order and all other output. The one internal change is that binary conversion scratch text on the canonical path is not charged as outputBytes; existing callers keep the old charge.

Tests

Tests/JSONTests/CanonicalizationTests.swift, 8 functions:

  • the RFC 8785 Appendix B number vectors, each via a round-trip decimal (.preserving) and via the exact binary expansion (.rounding);
  • the §3.2.2 sample document (.rounding; .preserving refuses 333333333.33333329);
  • the §3.2.3 key-sorting example, including where it differs from scalar order;
  • the short escapes;
  • policy acceptance and refusal;
  • equal values giving equal bytes, with the output re-parsing to an equal value;
  • output and depth limits, the statistics report, and cancellation.

TestDiscovery.json: JSONTests 190 → 198 (native, portable, WASI). CLI identity regenerated.

Local evidence

Swift 6.4.2 via swiftly, Xcode 27.2 SDK, at 0618e61's tree:

  • python3 Scripts/ci.py --lane docs: exit 0, 4/4 commands.
  • python3 Scripts/ci.py --lane native: exit 0, 62/62 commands. The first run failed only on the discovery count (190 vs 198), which is now updated.
  • Linux and WASI have not been run locally; CI covers them.

Not merged, tagged or released. The maintainer decides.

🤖 Generated with Claude Code

ThorFuchs and others added 2 commits November 12, 2026 17:26
JSONCanonicalWriter writes JSON Canonicalization Scheme bytes: compact
output, keys ordered by UTF-16 code units, short string escapes and the
ECMAScript spelling of binary64 numbers. It shares the strict writer cursor
and the invocation-owned work meter. NumberPolicy.preserving (default)
refuses a number whose binary64 spelling would denote a different exact
decimal; .rounding rounds to the nearest binary64 as RFC 8785 specifies.
Scratch binary conversion text is no longer charged as output bytes on this
path; existing writers are unchanged.

Tests cover the RFC 8785 Appendix B vectors, the section 3.2.2 sample and the
section 3.2.3 key-order example, plus policy, limits and cancellation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ThorFuchs
ThorFuchs merged commit b9040c2 into main Nov 12, 2026
21 checks passed
@ThorFuchs
ThorFuchs deleted the feature/1.10-jcs branch November 12, 2026 19:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant