Serialization round-trip properties

Serialization & Round-Trip Properties

Use this skill when testing JSON/binary codecs, CSV/Excel/XML import-export pipelines, DTO mappers, URL/query-string parsers, cryptographic payload signing, or database/event schema transformations.

Fundamental Round-Trip & Transformation Laws

1. Lossless Round-Trip Identity ($\text{decode}(\text{encode}(x)) \equiv x$):
   • For any valid domain value $x$, serializing/exporting $x$ and deserializing/importing the result must produce a value semantically identical to $x$.
   • When the wire format normalizes representation (e.g., canonicalizing timezone offset to Z or stripping trailing decimal zeros while preserving scale), assert equality on the canonical domain value: $\text{canonical}(\text{decode}(\text{encode}(x))) \equiv \text{canonical}(x)$.
2. Idempotency of Normalization & Sanitization ($f(f(x)) \equiv f(x)$):
   • Formatting, slugification, HTML sanitization, address normalization, and canonical JSON serialization must be idempotent: applying the normalizer a second time must never alter an already-normalized value.
3. Schema Evolution & Backward/Forward Compatibility:
   • Payloads encoded with schema version $v_1$ (missing newly added optional fields or containing deprecated fields) must decode cleanly under $v_2$ with documented defaults.
   • Unknown extra fields on incoming webhook or API payloads should be handled according to contract without corrupting known fields.
4. Parser Total Safety (No Unhandled Crashes on Arbitrary Input):
   • Feeding arbitrary/malformed strings, truncated buffers, deeply nested structures, or adversarial CSV rows into a parser or validator must either return a valid parsed object or a structured validation error—never an unhandled exception, infinite loop, or prototype pollution.

Adversarial Data Generators for Serialization

Include edge cases that commonly break codecs and importers:

• Numbers & Precision: 0, -0 (canonicalize to 0), MAX_SAFE_INTEGER, BigInt / 64-bit IDs, high-precision decimals ("19.99", "0.0001"), and currency amounts that would lose precision if parsed as IEEE-754 floats.
• Strings & Unicode: Empty strings, whitespace-only strings, multi-byte UTF-8 emojis, combining characters (NFC vs. NFD), RTL marks, quotes, commas, newlines inside CSV cells, and formula-injection prefixes (=, +, -, @).
• Nullability & Absent Keys: null vs. undefined vs. empty string "" vs. empty array [].

Checklist

• Does $\text{decode}(\text{encode}(x)) \equiv x$ hold across generated domain objects, including optional/null fields and nested collections?
• Are monetary decimals, BigInt IDs, and timestamps preserved without floating-point or timezone precision loss?
• Do Unicode strings, embedded delimiters/newlines, and CSV formula prefixes survive import/export safely?
• Are normalizers and canonicalizers verified to satisfy $f(f(x)) \equiv f(x)$?