Rust - Serde Json By Example

Basic struct serialization and deserialization

Serialization happens via serde_json::to_string.
serde_json::to_string_pretty can be used for enhancing the readibility if you're printing the data.

pub fn to_string<T: ?Sized>(value: &T) -> Result<String> 
where
    T: Serialize

Deserialization happens via serde_json::from_str

pub fn from_str<'a, T>(s: &'a str) -> Result<T> 
where
    T: Deserialize<'a>

Since, the return type for both is a Result<T>, the examples below end up unwrap()ing the values.

Unit structs

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct U;

fn main() {
    let u = U;

    // serialization
    let s = serde_json::to_string(&u).unwrap();
    // `s` represented as `null`
    println!("{}", s);

    // deserialization
    let d: U = serde_json::from_str("null").unwrap();
    // `d` is U
    println!("{:?}", d);
}
// Output:
// null
// U

Tuple structs

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct T(u8, f64, bool, String);

fn main() {
    // serialization
    let t = T(10u8, 3.14159, true, "Hello".to_owned());
    let s = serde_json::to_string(&t).unwrap();
    // `s` represented as `[10, 3.14159, true, "Hello"]`
    println!("{}", s);

    // deserialization
    let d: T = serde_json::from_str(r#"[10, 3.14159, true, "Hello"]"#).unwrap();
    // `d` is `T(10u8, 3.14159, true, "Hello".to_owned())`;
    println!("{:?}", d);
}
// Output:
// [10,3.14159,true,"Hello"]
// T(10, 3.14159, true, "Hello")

Haskell Newtype-like structs

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct N(i32);

fn main() {
    // serialization
    let n = N(10i32);
    let s = serde_json::to_string(&n).unwrap();
    // `s` represented as `10`
    println!("{}", s);

    // deserialization
    let d: N = serde_json::from_str("10").unwrap();
    // `d` is `N(10)`;
    println!("{:?}", d);
}
// Output:
// 10
// N(10)

C-like structs

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct C {
    a: i32,
    b: f64,
    c: bool,
    d: String,
}

fn main() {
    // serialization
    let t = C {
        a: 10,
        b: 3.14159,
        c: true,
        d: "Hello".to_owned(),
    };
    let s = serde_json::to_string(&t).unwrap();
    // `s` represented as `{"a": 10, "b": 3.14159, "c": true, "d": "Hello"}`
    println!("{}", s);

    // deserialization
    let d: C = serde_json::from_str(&s).unwrap();
    println!("{:?}", d);
}

// Output:
// {"a":10,"b":3.14159,"c":true,"d":"Hello"}
// C { a: 10, b: 3.14159, c: true, d: "Hello" }

Optional values

The examples you have come across so far had structs with required values.
null is a valid json value that is often used in cases data is missing.
Take for example the following:

#[derive(Serialize, Deserialize)]
struct C {
    a: i32,
    b: f64,
}

// serialization with missing value
let t = C {
  b: 3.14159,
};
serde_json::to_string(&t).unwrap();

The above program would fail to compile since we've missed a entirely

error[E0063]: missing field `a` in initializer of `C`

Deserialization with a null value for a would cause errors.
Its type is i32 and we can't arbitrarily choose 0 to indicate absence of data.
In such cases, it's preferred that we mark the values as Optional as shown below.

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct C {
    a: Option<i32>,
    b: f64,
}

fn main() {
    // serialization with missing value
    let t = C {
        a: None,
        b: 3.14159,
    };
    println!("{}", serde_json::to_string(&t).unwrap());
    // `{"a": null, "b": 3.14159}`

    // deserialization with missing value
    let d: C = serde_json::from_str(r#"{"a": null, "b": 3.14159}"#).unwrap();
    // `d` equals `C { a: None, b: 3.14159 }`
    println!("{:?}", d);

    println!("Hello, world!");
}

// Output:
// {"a":null,"b":3.14159}
// C { a: None, b: 3.14159 }
// Hello, world!

Default values

use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Test {
    // Use default_str_fun() as the default if "my_str" is missing
    #[serde(default = "default_str_fun")]
    my_str: String,

    // Use MyType::default if "my_type" is missing
    #[serde(default)]
    my_type: MyType,
}

fn default_str_fun() -> String {
    "hi".to_owned()
}

/// Timeout in seconds.
#[derive(Deserialize, Debug)]
struct MyType(Vec<i32>);
impl std::default::Default for MyType {
    fn default() -> Self {
        Self(vec![1, 2, 3])
    }
}

fn main() {
    let d1: Test = serde_json::from_str(r#"{"my_type": [1]}"#).unwrap();
    // `d1` equals `Test { my_str: "hi".to_owned(), my_type: MyType(vec![1]) }`
    println!("{:?}", d1);

    let d2: Test = serde_json::from_str(r#"{"my_str": "hello world"}"#).unwrap();
    // `d2` equals `Test { my_str: "hello world".to_owned(), my_type: MyType(vec![1,2,3]) }`
    println!("{:?}", d2);

    println!("Hello, world!");
}

// Output:
// Test { my_str: "hi", my_type: MyType([1]) }
// Test { my_str: "hello world", my_type: MyType([1, 2, 3]) }
// Hello, world!

Missing field vs null value

A null value isn't the same as a missing field altogether.
The following program panics on deserialization.

// ================
// BROKEN
// ================
use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Test {
    // Use default_str_fun() as the default if "my_str" is missing
    #[serde(default = "default_str_fun")]
    my_str: String,

    // Use MyType::default if "my_type" is missing
    #[serde(default)]
    my_type: MyType,
}

fn default_str_fun() -> String {
    "hi".to_owned()
}

/// Timeout in seconds.
#[derive(Deserialize, Debug)]
struct MyType(Vec<i32>);
impl std::default::Default for MyType {
    fn default() -> Self {
        Self(vec![1, 2, 3])
    }
}

fn main() {

    let d: Test = serde_json::from_str(r#"{
        "my_str": "hello world", 
        "my_type": null
    }"#).unwrap();
    println!("{:?}", d);
}

// Output:
// Running `target/debug/playground`
// thread 'main' panicked at 'called `Result::unwrap()` on an 
// `Err` value: Error("invalid type: null, expected a sequence", line: 3, column: 23)', 
// src/main.rs:32:10
// note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

json! macro

The json! macro allows one to construct serde_json::Value objects by hand.

let j: serde_json::Value = json!({
    "a": 10u8,
    "b": 3.14159,
    "c": true,
    "d": "Hello".to_owned(),
});
let s = j.to_string();
// `s` represented as `{"a": 10, "b": 3.14159, "c": true, "d": "Hello"}`

Deserializing to Map

// deserializing to Map<String, Value>
use serde_json::{Value, Map};
println!(
    "{:?}", 
    serde_json::from_str::<Map<String, Value>>(r#"
        {"gender":"male","blah":25}
        "#).unwrap());
// {"blah": Number(25), "gender": String("male")}

enums

The default enum representation has the enum variant 'externally tagging' the content.

#[derive(Serialize, Deserialize)]
enum Color {
    C { red: u8, green: u8, blue: u8 },
    T(u8, u8, u8),
    N(i32),
    D,
}
let a = Color::C { 
    red: 10,
    green: 100,
    blue: 125
}; 
// `a` represented as `{"C":{"red":10,"green":100, "blue": 125}}`

let b = Color::T(10, 100, 125); 
// `b` represented as `{"T":[10,100,125]}`

let c = Color::N(0);
// `c` represented as `{"N":0}`

let d = Color::D;
// `d` represented as `"D"`

It's also possible to delineate the tag and content separately in the object
next to each other

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
#[serde(tag = "type", content = "body")]
enum Color {
    C { red: u8, green: u8, blue: u8 },
    T(u8, u8, u8),
    N(i32),
    D,
}

fn main() {
    let a = Color::C {
        red: 10,
        green: 100,
        blue: 125,
    };
    println!("{}", serde_json::to_string(&a).unwrap());
    // {"type":"C","body":{"red":10,"green":100,"blue":125}}
}

Ommitting the content should merge the tag with the rest of the content.

// ===============
// BROKEN PROGRAM
// ===============

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
enum Color {
    C { red: u8, green: u8, blue: u8 },
    T(u8, u8, u8),
    N(i32),
    D,
}

fn main() {
    println!("Hello, world!");
    let a = Color::C {
        red: 10,
        green: 100,
        blue: 125,
    };
    println!("{}", serde_json::to_string(&a).unwrap());
}

Wait! The code fails to build. Let's look at the error message.

Compiling playground v0.0.1 (/playground)
error: #[serde(tag = "...")] cannot be used with tuple variants
 --> src/main.rs:7:5
  |
7 |     T(u8, u8, u8),
  |     ^^^^^^^^^^^^^

error[E0277]: the trait bound `Color: Serialize` is not satisfied
    --> src/main.rs:19:42
     |
19   |     println!("{}", serde_json::to_string(&a).unwrap());
     |                                          ^^ the trait `Serialize` is not implemented for `Color`
     | 
    ::: /playground/.cargo/registry/src/github.com-1ecc6299db9ec823/serde_json-1.0.61/src/ser.rs:2221:17
     |
2221 |     T: ?Sized + Serialize,
     |                 --------- required by this bound in `serde_json::to_string`

error: aborting due to 2 previous errors

For more information about this error, try `rustc --explain E0277`.
error: could not compile `playground`

To learn more, run the command again with --verbose.

Removing the tuple variant makes it work again! I haven't really spent time figuring
out what's gone wrong here.

// Using just serde `tag` and no `content`

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
enum Color {
    C { red: u8, green: u8, blue: u8 },

    // commenting out the tuple variant
    // T(u8, u8, u8),

    N(i32),
    D,
}

fn main() {
    let a = Color::C {
        red: 10,
        green: 100,
        blue: 125,
    };
    println!("{}", serde_json::to_string(&a).unwrap());
    // {"type":"C","red":10,"green":100,"blue":125}
}

If you don't want any tag information creeping in the serialized string,
choose the untagged representation. While deserializing, serde would try
each variant and returns the first one that succeeds.

// Untagged version

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
#[serde(untagged)]
enum Color {
    C { red: u8, green: u8, blue: u8 },
    T(u8, u8, u8),
    N(i32),
    D,
}

fn main() {
    let a = Color::C {
        red: 10,
        green: 100,
        blue: 125,
    };
    println!("{}", serde_json::to_string(&a).unwrap());
    // {"red":10,"green":100,"blue":125}
}

Aliasing and renaming fields

You can change the case for individual or all of the fields while serializing
to json representation.

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct Address {
    id: i64,
    street_name: String,
    zip_code: String,
    city: String,
}

let address = Address {
    id: 1,
    street_name: "ABC street".to_owned(),
    zip_code: "10101010".to_owned(),
    city: "XYZ City".to_owned(),
};
let js = serde_json::to_string(&address).unwrap();
// js represented as:
// `{"id": 1, "streetName": "ABC street", "zipCode": "10101010", "city": "XYZ City"}`

Fields can also be aliased by multiple names while deserializing the json string.
e.g. field attribute: #[serde(alias = "<Choose your field alias>")]

You can avoid serializing or deserializing a field. The attributes to consider are the following:
#[serde(skip_deserializing)], #[serde(skip_serializing)], #[serde(skip)]

#[derive(Serialize, Deserialize, Debug)]
struct XYZP {
    #[serde(alias = "gender")]
    #[serde(alias = "category")]
    sex: String,

    #[serde(rename = "blah")]
    age_years: u8,

    #[serde(skip)]
    weight_kg: u8,
}

let xyzp = XYZP {
    sex: "male".to_owned(),
    age_years: 25,
    weight_kg: 76,
};

println!("{}", serde_json::to_string(&xyzp).unwrap());
// {"sex":"male","blah":25}

println!(
    "{:?}", 
    serde_json::from_str::<XYZP>(r#"
        {"gender":"male","blah":25}
        "#
    ).unwrap());
// XYZP { sex: "male", age_years: 25, weight_kg: 0 }