stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
fa4823f46c4bc090294580a9136fb6b0e11e50f9
git.stella-ops.org/docs/features/unchecked/attestor/rfc-8785-canonical-json-serialization.md

2.5 KiB
Raw Blame History

RFC 8785 Canonical JSON Serialization

Module

Attestor

Status

IMPLEMENTED

Description

Full RFC 8785 JSON canonicalizer with decimal point, number serialization, string normalization, and write method implementations. Verified by determinism property-based tests and canonical JSON test suite.

Implementation Details

  • RFC 8785 JSON Canonicalizer: src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs -- main canonicalizer implementing RFC 8785 (JSON Canonicalization Scheme / JCS).
  • Decimal Point Handling: Json/Rfc8785JsonCanonicalizer.DecimalPoint.cs -- handles decimal point normalization per RFC 8785 rules (no trailing zeros, no unnecessary decimal points).
  • Number Serialization: Json/Rfc8785JsonCanonicalizer.NumberSerialization.cs -- deterministic number serialization (IEEE 754 compliance, consistent exponent notation).
  • String Normalization: Json/Rfc8785JsonCanonicalizer.StringNormalization.cs -- Unicode normalization, escape sequence handling, and surrogate pair processing per RFC 8785.
  • Write Methods: Json/Rfc8785JsonCanonicalizer.WriteMethods.cs -- deterministic JSON writing (sorted object keys, no whitespace, consistent separators).
  • Schema Validation Result: Json/SchemaValidationResult.cs -- result of validating canonicalized JSON against a schema.
  • Schema Validation Error: Json/SchemaValidationError.cs -- individual validation error.
  • Content-Addressed ID Generator: Identifiers/ContentAddressedIdGenerator.cs -- uses canonicalized JSON for deterministic SHA-256 ID generation.
  • Tests: __Tests/StellaOps.Attestor.ProofChain.Tests/Rfc8785JsonCanonicalizerTests.cs, DeterminismTests.cs

E2E Test Plan

  • Canonicalize a JSON object with unsorted keys and verify output has lexicographically sorted keys
  • Canonicalize numbers with trailing zeros (e.g., 1.0000) and verify output removes unnecessary precision per RFC 8785
  • Canonicalize strings with Unicode characters and verify proper Unicode normalization and escape sequences
  • Canonicalize the same JSON object twice and verify byte-identical output
  • Canonicalize a JSON object with different whitespace formatting and verify identical canonicalized output
  • Canonicalize a number requiring scientific notation and verify consistent exponent representation
  • Generate a content-addressed ID from canonicalized JSON and verify it is deterministic across runs
  • Run the RFC 8785 test vectors (from the specification) and verify all pass