Serialization

Serialization converts data held by a program into a representation that can be stored or transferred. Deserialization reads that representation and produces data the receiving program can work with.

APIs rely on these operations because network protocols carry bytes, not a language’s in-memory dictionaries, objects, or structs.

The Basic Flow

Suppose a Python program needs to send this dictionary:

user = {
    "name": "john",
    "roles": ["admin", "user"],
}

For a JSON API, the data moves through several forms:

Python dictionary
      │
      │ JSON serialization
      ▼
JSON text
{"name":"john","roles":["admin","user"]}
      │
      │ character encoding, usually UTF-8
      ▼
Bytes sent through HTTP
      │
      │ UTF-8 decoding
      ▼
JSON text
      │
      │ JSON deserialization
      ▼
Receiver's dictionary, map, object, or struct

HTTP client libraries often perform the text-to-bytes and bytes-to-text steps automatically, but the distinction still matters when debugging encodings and malformed payloads.

Related Operations Are Not the Same

Operation	Converts	Example
Serialization	In-memory data to a transferable or storable representation	Python dict to JSON text
Deserialization	A representation to usable in-memory data	JSON text to a Java Map
Character encoding	Text to bytes, or bytes to text	Unicode text to UTF-8 bytes
Compression	Bytes to a smaller byte sequence	HTTP body compressed with gzip
Encryption	Readable data to protected ciphertext	HTTPS protecting bytes in transit

A program may perform several of these operations for one request:

serialize → encode → compress → encrypt → transmit

The receiver reverses them in the corresponding order.

Note: Turning speech into a digital telephone signal is mainly sampling, audio encoding, and compression. It is a useful transport analogy, but it is not the same operation as serializing a structured object to JSON.

Serialization in an API

A client sending JSON typically does the following:

1. Builds data using its programming language’s types.
2. Serializes that data according to JSON syntax.
3. Sends the resulting representation with Content-Type: application/json.
4. Receives a response and checks its status and media type.
5. Deserializes the response body.
6. Validates that the resulting fields satisfy the API contract.

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
 
{"name":"john","roles":["admin","user"]}

The media type tells the receiver which parser to use. It does not prove that the body is valid or that required fields are present.

Parsing and Deserialization

The terms are often used interchangeably, but they emphasize different work:

• Parsing checks the representation’s syntax and identifies its structure.
• Deserialization converts that parsed structure into values the program can use.
• Validation checks those values against an API contract or schema.

For a simple JSON library, one function may perform the parsing and type conversion together. Business validation remains a separate step.

JSON text
   │
   ├─ parse syntax ─────── Is this valid JSON?
   │
   ├─ deserialize ─────── Create strings, numbers, lists, and maps
   │
   └─ validate ────────── Is quantity a positive integer? Is email required?

Deserialization Does Not Guarantee an Exact Copy

The receiver usually reconstructs equivalent data, not the sender’s exact object.

For example, a Python tuple serialized as a JSON array normally becomes a list when read back:

import json
 
before = ("admin", "user")
after = json.loads(json.dumps(before))
 
print(after)        # ['admin', 'user']
print(type(after))  # <class 'list'>

The representation does not include every detail about the original runtime object. Class methods, object identity, language-specific types, comments, and some numeric details may be lost unless the format and schema explicitly preserve them.

This is why independent systems agree on a contract:

field name + data type + constraints + meaning

Text and Binary Formats

Kind	Examples	Typical trade-off
Text	JSON, YAML, XML	Easy to inspect and debug; usually larger
Binary	Protocol Buffers, CBOR, MessagePack	Often smaller and faster to process; needs suitable tooling

Binary does not automatically mean encrypted. A binary payload can still expose its data to anyone who knows the format.

See API Data Formats for the structure and API role of the three text formats.

Security and Reliability

Data from an API or file is input, not trusted program state.

• Limit accepted body size and nesting depth where possible.
• Reject malformed input.
• Validate required fields, types, ranges, and allowed values after deserialization.
• Do not let a deserializer create arbitrary runtime objects from untrusted data.
• Treat the declared Content-Type and the actual body as separate things to verify.
• Avoid logging secrets contained in parsed payloads.

Python’s pickle format can recreate Python object graphs, but loading a malicious pickle can execute arbitrary code. It is unsuitable for untrusted API input.

Python Example

Python’s standard json module makes the direction visible in the function names:

import json
 
user = {"name": "john", "roles": ["admin", "user"]}
 
json_text = json.dumps(user)       # serialize to a string
restored_user = json.loads(json_text)  # deserialize from a string

The practical file workflows are covered in Data Formats in Python. The separate Python notes also explain what import does and how pip installs third-party packages.

TL;DR

• Serialization converts in-memory data to a representation suitable for storage or transfer.
• Deserialization converts that representation into data a program can use.
• Text serialization and UTF-8 encoding are separate operations.
• Parsing checks structure; validation checks whether the resulting data is acceptable.
• The receiver normally reconstructs equivalent data, not the sender’s exact runtime object.
• The API contract defines how fields and types should be interpreted.
• Deserialized input remains untrusted and must be validated.

Resources

• JSON Data Interchange Format — RFC 8259
• HTTP Semantics — RFC 9110
• Python json module
• Python pickle security warning

Note: Behaviour and documentation links were checked against current specifications and Python documentation in July 2026.