data-serialization-principles

name	data-serialization-principles
description	Serialization best practices: schema validation, encoding, versioning, backward compat, safe deserialization. JSON, YAML, Protobuf, MessagePack.
user-invocable	false

Data Serialization Principles

Validate at Boundaries

All incoming data validated: API requests, file uploads, MQ messages. Type, format, range, required fields. Fail fast on invalid. Clear errors to client.

Encoding

Default UTF-8 everywhere. Specify explicitly when reading/writing. Handle errors gracefully.

Format Selection

Format	Good For	Limitations
JSON	APIs, config, web (human-readable, universal)	No binary, larger size
Protobuf	Internal microservices, high-throughput (compact, schema evolution)	Not readable, requires schema
MessagePack	Internal APIs needing speed over JSON	Less widely supported
XML	Enterprise, SOAP, RSS (legacy)	Verbose, XXE attacks
YAML	Config, IaC (K8s, CI/CD) (human-friendly)	Complex parsing, security risks

Security

• Validate before deserialization (prevent arbitrary code execution)
• Size limits on payloads (prevent OOM)
• Whitelist allowed types/classes
• XML: disable external entities (XXE)
• YAML: disable unsafe constructors
• Python pickle: NEVER deserialize untrusted data

Related

• Error Handling @.gemini/rules/error-handling-principles.md
• Security Mandate @.gemini/rules/security-mandate.md
• Security Principles @.gemini/rules/security-principles.md
• API Design @.gemini/skills/api-design-principles/SKILL.md