Elysia Tools
Navigation
Workflow Playbook
Convert structured data between binary serialization formats, text transport encodings, and escaped representations, then verify fields and bytes through a controlled round trip.
Hubs
The most common binary-message mistake is treating a text wrapper as the data format. Start by recording the source, message boundaries, and intended consumer: structured values are serialized into bytes, and those bytes may then be represented as Base64, ASCII85, Base91, or escaped hexadecimal text. Preserve each layer independently, and do not edit visible text as though it were JSON or UTF-8 while the inner format is still unconfirmed.
Build a repeatable reference fixture with plain and non-ASCII text, decimals, nulls, zero bytes, nested objects, and arrays. Record the original length and a few control hexadecimal fragments. These facts make it possible to separate a serialization defect from a delivery defect later.
When the protocol names the outer representation, use the matching converter to recover bytes. If the origin is ambiguous, retain evidence and test candidate representations for completeness instead of inferring a format from the visible alphabet. Successfully decoding Base64 does not prove the content is JSON: it may contain Protobuf, CBOR, or an application-specific binary frame.
Choose Avro, BSON, CBOR, Ion, MessagePack, Protobuf, Smile, or UBJSON only after reviewing the bytes, sender documentation, content type, schema, or receiver code. For schema-aware formats, the schema version, field numbers, and defaults are part of the payload contract, not optional notes.
Convert the reference fixture to the target format and restore it to an inspectable representation. First compare business semantics: field presence, types, numeric precision, Unicode, nulls, array order, and nesting. Then inspect boundaries: message length, zero bytes, binary fields, and control fragments. If a format permits more than one equivalent byte encoding, define a canonical comparison instead of requiring byte-for-byte equality where it is not meaningful.
Next apply the wrapper required by the delivery channel and immediately decode the deliverable. This final check separates a wrong serializer choice from a transport-encoding mistake and creates a reproducible diagnostic trail.
No converter error is not sufficient acceptance. The target consumer or a compatible decoder must read the result; retain the fixture, schema version, format, wrapper, length, and comparison result. Common failures include treating Base64 as the inner format, losing Protobuf field numbers, re-encoding binary fields as text, and adding a second transport wrapper that the channel never requested.
If the receiver rejects the payload, return to the last validated layer: check wrapper completeness, schema compatibility, and actual format support, then reduce the input to a minimal reproducible fixture. Clear records for all three layers are more reliable than repeatedly trying unrelated converters.
Workflow playbook
Use the converter supported by the source protocol or the fixture evidence to recover original bytes; document uncertainty instead of guessing the format.
Encode or decode in a binary format the receiver actually supports; retain the schema, field numbers, and version alongside Avro or Protobuf fixtures.
Restore the fixture from the new format and compare fields, numeric precision, Unicode, nulls, nested collections, length, and critical bytes before delivery.
Apply a text wrapper only when the channel requires it, then immediately decode the output to confirm it carries the already validated inner bytes.
Base64, ASCII85, Base91, and hexadecimal escapes move bytes through text channels; Avro, CBOR, and Protobuf define how the payload represents data.
Choose a compatible format when the receiver requires schemas, field numbers, or evolution rules; a Base64-looking string alone does not identify its inner serialization.