GitHubrustdocLatest Version

Serde

Serde is a framework forserializing anddeserializing Rust datastructures efficiently and generically.

The Serde ecosystem consists of data structures that know how to serialize anddeserialize themselves along with data formats that know how to serialize anddeserialize other things. Serde provides the layer by which these two groupsinteract with each other, allowing any supported data structure to be serializedand deserialized using any supported data format.

Design

Where many other languages rely on runtime reflection for serializing data,Serde is instead built on Rust's powerful trait system. A data structure thatknows how to serialize and deserialize itself is one that implements Serde'sSerialize andDeserialize traits (or uses Serde's derive attribute toautomatically generate implementations at compile time). This avoids anyoverhead of reflection or runtime type information. In fact in many situationsthe interaction between data structure and data format can be completelyoptimized away by the Rust compiler, leaving Serde serialization to performthe same speed as a handwritten serializer for the specific selection of datastructure and data format.

Data formats

The following is a partial list of data formats that have been implemented forSerde by the community.

  • JSON, the ubiquitous JavaScript Object Notation used by many HTTP APIs.
  • Postcard, a no_std and embedded-systems friendly compact binary format.
  • CBOR, a Concise Binary Object Representation designed for small message sizewithout the need for version negotiation.
  • YAML, a self-proclaimed human-friendly configuration language that ain'tmarkup language.
  • MessagePack, an efficient binary format that resembles a compact JSON.
  • TOML, a minimal configuration format used byCargo.
  • Pickle, a format common in the Python world.
  • RON, a Rusty Object Notation.
  • BSON, the data storage and network transfer format used by MongoDB.
  • Avro, a binary format used within Apache Hadoop, with support for schemadefinition.
  • JSON5, a superset of JSON including some productions from ES5.
  • URL query strings, in the x-www-form-urlencoded format.
  • Starlark, the format used for describing build targets by the Bazel and Buckbuild systems.(serialization only)
  • Envy, a way to deserialize environment variables into Rust structs.(deserialization only)
  • Envy Store, a way to deserializeAWS Parameter Store parameters into Ruststructs.(deserialization only)
  • S-expressions, the textual representation of code and data used by the Lisplanguage family.
  • D-Bus's binary wire format.
  • FlexBuffers, the schemaless cousin of Google's FlatBuffers zero-copyserialization format.
  • Bencode, a simple binary format used in the BitTorrent protocol.
  • Token streams, for processing Rust procedural macro input.(deserializationonly)
  • DynamoDB Items, the format used byrusoto_dynamodb to transfer data toand from DynamoDB.
  • Hjson, a syntax extension to JSON designed around human reading and editing.(deserialization only)
  • CSV, Comma-separated values is a tabular text file format.

Data structures

Out of the box, Serde is able to serialize and deserialize common Rust datatypes in any of the above formats. For exampleString,&str,usize,Vec<T>,HashMap<K,V> are all supported. In addition, Serde provides a derivemacro to generate serialization implementations for structs in your own program.Using the derive macro goes like this:

use serde::{Serialize, Deserialize};#[derive(Serialize, Deserialize, Debug)]structPoint {    x:i32,    y:i32,}fnmain() {let point = Point { x:1, y:2 };// Convert the Point to a JSON string.let serialized = serde_json::to_string(&point).unwrap();// Prints serialized = {"x":1,"y":2}println!("serialized = {}", serialized);// Convert the JSON string back to a Point.let deserialized: Point = serde_json::from_str(&serialized).unwrap();// Prints deserialized = Point { x: 1, y: 2 }println!("deserialized = {:?}", deserialized);}