From NovaOrdis Knowledge Base
Jump to navigation Jump to search




Serialization is a process that encodes and decodes data for storing or sending between services. The process of transforming the original data into transit data is called serialization. The inverse process of transforming transit data into the original data is called deserialization.

Serialization Formats

Serialization Best Practices

Keep your Schema Backward Compatible

Avoid changes in data schema that would break existing callers. Such changes include modification (renaming or removal) of field names and types. Adding fields is fine. Also see:

Forward and Backward Compatibility

Ensure Data Schemas are Kept in Sync between Clients and Servers

For serialization formats with explicit schema definitions such as Apache Thrift, Apache Avro and Protocol Buffers, the client and servers should be kept in sync with the latest schema versions.

Document Implicit Details

Let the callers know any implicit details related to your data schema. For example, if your API does not allow an empty value of a certain field of the structure, include this in the comments in the schema file.

Use Built-in Structures for Representing Time

Protocol Buffers and other serialization protocols provide built-in types for timestamps and durations. Use those. For Protocol Buffers, use google.protobuf.Timestamp.

Use Consistent Naming

Follow the Official Style Guide

Get familiar with the official style guid of the schema definition language and use it.