Serialization — serde

struct User ──Serialize──► serde data model ──serde_json──► {"name":"Ada"}
             ◄─Deserialize──                 ◄─────────────

[dependencies]
serde = { version = "1", features = ["derive"] }   # derive: enables #[derive(Serialize, Deserialize)]
serde_json = "1"                                   # JSON format
toml = "0.8"                                       # TOML format (if needed)

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct User {
    id: u32,
    name: String,
    email: String,
    active: bool,
    roles: Vec<String>,
}

struct Connection;                        // no Serialize

// #[derive(Serialize)]
// struct State { c: Connection }         // ERROR: the trait `Serialize` is not implemented for `Connection`

let u = User {
    id: 1,
    name: "Ada".into(),
    email: "[email protected]".into(),
    active: true,
    roles: vec!["admin".into()],
};

let compact = serde_json::to_string(&u)?;          // {"id":1,"name":"Ada",...}
let pretty = serde_json::to_string_pretty(&u)?;    // indented
let bytes: Vec<u8> = serde_json::to_vec(&u)?;
serde_json::to_writer(std::io::stdout(), &u)?;     // straight into a stream, no intermediate String

let text = r#"{"id":2,"name":"Linus","email":"[email protected]","active":false,"roles":[]}"#;

// 1. Annotate the variable
let u: User = serde_json::from_str(text)?;

// 2. Turbofish
let u = serde_json::from_str::<User>(text)?;

// 3. From bytes or a reader
let u: User = serde_json::from_slice(text.as_bytes())?;
let f = std::fs::File::open("u.json")?;
let u: User = serde_json::from_reader(std::io::BufReader::new(f))?;

A missing field, an extra one (depending on the options, section 11), or one of the wrong type produces an error that gives the line and column: missing field \email` at line 1 column 30`.

use serde_json::{json, Value};

let v: Value = serde_json::from_str(r#"{"name":"Ada","languages":["rust","c"],"age":36}"#)?;

let name = v["name"].as_str();                   // Some("Ada")
let first = v["languages"][0].as_str();          // Some("rust")
let missing = &v["nonexistent"];                 // Value::Null, no panic
let age = v.get("age").and_then(Value::as_u64);  // Some(36)

let built = json!({
    "status": "ok",
    "total": 3,
    "items": [1, 2, 3],
});

let v: Value = serde_json::to_value(&u)?;          // struct -> Value
let u2: User = serde_json::from_value(v)?;         // Value -> struct

#[derive(Debug, Deserialize)]
struct Config {
    server: Server,
    database: Database,
}

#[derive(Debug, Deserialize)]
struct Server { host: String, port: u16 }

#[derive(Debug, Deserialize)]
struct Database { url: String, connections: u32 }

let text = r#"
[server]
host = "0.0.0.0"
port = 8080

[database]
url = "postgres://localhost/app"
connections = 10
"#;

let c: Config = toml::from_str(text)?;

TOML tables ([server]) correspond to nested structs. The same struct could be read from a JSON {"server": {...}, "database": {...}} without modification.

#[derive(Deserialize)]
struct Search { q: String, page: Option<u32> }

let r: Search = serde_urlencoded::from_str("q=rust+web&page=2")?;

This is the format of HTML forms and URL parameters. axum's Form<T> and Query<T> extractors use it.

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]           // all fields: created_at -> createdAt
struct Article {
    id: u32,
    created_at: String,
    #[serde(rename = "articleTitle")]        // one specific field
    title: String,
}

Values of rename_all: lowercase, UPPERCASE, camelCase, PascalCase, snake_case, SCREAMING_SNAKE_CASE, kebab-case, SCREAMING-KEBAB-CASE.

#[derive(Serialize, Deserialize)]
struct Product {
    #[serde(rename(serialize = "price", deserialize = "cost"))]
    cost: f64,
}

#[derive(Deserialize)]
struct Contact {
    #[serde(alias = "mail", alias = "e-mail")]
    email: String,
}

What it is for: renaming a field without breaking old clients or old files.

#[derive(Serialize, Deserialize)]
struct Session {
    user: String,
    #[serde(skip)]                           // neither written nor read; when reading: Default::default()
    cache: Vec<u8>,
    #[serde(skip_serializing)]               // read but never written
    password: String,
    #[serde(skip_deserializing)]             // written but never read
    computed: u32,
}

#[derive(Serialize)]
struct Response {
    data: Vec<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,                   // absent from the JSON if None, instead of "error": null
    #[serde(skip_serializing_if = "Vec::is_empty")]
    warnings: Vec<String>,
}

#[derive(Deserialize)]
struct Options {
    #[serde(default)]                        // missing -> Default::default() (0, "", false, empty vec)
    verbose: bool,
    #[serde(default = "default_port")]       // missing -> value from a function
    port: u16,
}

fn default_port() -> u16 { 8080 }

#[derive(Deserialize, Default)]
#[serde(default)]                            // on the struct: any missing field takes the Default value
struct Settings { size: u32, theme: String }

#[derive(Serialize, Deserialize)]
struct Pagination { page: u32, per_page: u32 }

#[derive(Serialize, Deserialize)]
struct ArticleList {
    articles: Vec<String>,
    #[serde(flatten)]
    pagination: Pagination,                  // {"articles":[..],"page":1,"per_page":20}
}

#[derive(Deserialize)]
struct WithExtras {
    name: String,
    #[serde(flatten)]
    others: std::collections::HashMap<String, serde_json::Value>,   // collects all unknown fields
}

#[derive(Deserialize, Debug)]
struct Profile {
    name: String,
    bio: Option<String>,
}

#[derive(Serialize, Deserialize)]
enum Event {
    Login { user: String },
    Purchase { amount: u32 },
    Logout,
}

// {"Login":{"user":"ada"}}
// {"Purchase":{"amount":30}}
// "Logout"

#[derive(Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
enum Event2 {
    Login { user: String },
    Purchase { amount: u32 },
    Logout,
}
// {"type":"login","user":"ada"}
// {"type":"logout"}

The most common form in web APIs. It does not work with tuple variants that contain a plain number or text (Purchase(u32)).

#[derive(Serialize, Deserialize)]
#[serde(tag = "type", content = "data")]
enum Message {
    Text(String),
    Number(i64),
}
// {"type":"Text","data":"hello"}

Works with all kinds of variants.

#[derive(Serialize, Deserialize, Debug)]
#[serde(untagged)]
enum Identifier {
    Number(u64),
    Name(String),
}
// 42      -> Number(42)
// "ada"   -> Name("ada")

serde tries each variant in order and keeps the first one that matches. Handy for accepting several forms, but the errors are not very informative ("data did not match any variant") and the order matters.

#[derive(Serialize, Deserialize, Debug, PartialEq)]
#[serde(rename_all = "lowercase")]
enum Status { Draft, Published, Archived }
// "draft", "published", "archived"

mod seconds {
    use serde::{Deserialize, Deserializer, Serializer};
    use std::time::Duration;

    pub fn serialize<S: Serializer>(d: &Duration, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_u64(d.as_secs())
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Duration, D::Error> {
        Ok(Duration::from_secs(u64::deserialize(d)?))
    }
}

#[derive(Serialize, Deserialize)]
struct Cache {
    #[serde(with = "seconds")]
    duration: std::time::Duration,        // {"duration": 300}
}

#[derive(Deserialize)]
struct Signup {
    #[serde(deserialize_with = "lowercase")]
    email: String,
}

fn lowercase<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    Ok(String::deserialize(d)?.trim().to_lowercase())
}

#[derive(Deserialize, Debug)]
#[serde(try_from = "String")]
struct Email(String);

impl TryFrom<String> for Email {
    type Error = String;
    fn try_from(s: String) -> Result<Self, Self::Error> {
        if s.contains('@') { Ok(Email(s)) } else { Err(format!("invalid email: {s}")) }
    }
}

#[derive(Deserialize, Debug)]
struct Account { email: Email }

let r: Result<Account, _> = serde_json::from_str(r#"{"email":"not-an-email"}"#);   // Err: invalid email

Invalid JSON can then never produce an Email: the "parse, don't validate" principle (see structures-enums) applied to serde. into = "String" does the reverse at serialization.

use serde::ser::{Serialize, SerializeStruct, Serializer};

struct Point { x: i32, y: i32 }

impl Serialize for Point {
    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        let mut st = s.serialize_struct("Point", 3)?;
        st.serialize_field("x", &self.x)?;
        st.serialize_field("y", &self.y)?;
        st.serialize_field("distance", &((self.x.pow(2) + self.y.pow(2)) as f64).sqrt())?;   // computed field
        st.end()
    }
}

Rarely needed: the attributes cover almost every case. Implementing Deserialize by hand is much longer (a visitor); keep it for truly unusual formats.

#[derive(Serialize, Deserialize, Debug)]
struct Response<T> {
    success: bool,
    data: Option<T>,
    error: Option<String>,
}

impl<T> Response<T> {
    fn ok(d: T) -> Self { Response { success: true, data: Some(d), error: None } }
    fn err(e: impl Into<String>) -> Self { Response { success: false, data: None, error: Some(e.into()) } }
}

let r = Response::ok(vec![1, 2, 3]);
let json = serde_json::to_string(&r)?;     // {"success":true,"data":[1,2,3],"error":null}

#[derive(Deserialize)]
struct Line<'a> {
    name: &'a str,                                 // points into the JSON text: no allocation
    #[serde(borrow)]
    note: std::borrow::Cow<'a, str>,               // borrows if possible, allocates if the text contains an escape
}

let source = String::from(r#"{"name":"ada","note":"good"}"#);
let l: Line = serde_json::from_str(&source)?;

A &str only works if the JSON text contains no escape sequence (\", \n); Cow handles both cases (see borrow-avance).

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct ChangePassword {
    old: String,
    new: String,
}
// {"old":"a","new":"b","role":"admin"} -> Err: unknown field `role`

By default, serde ignores extra fields. This is rarely a problem (they are stored nowhere), but deny_unknown_fields reports a client error, and documents that the payload is closed.

// Dangerous: deserializing the full entity directly from the request
// #[derive(Deserialize)] struct User { id: u32, name: String, is_admin: bool }
// let u: User = serde_json::from_str(body)?;    // the client can send "is_admin": true

// Safe: an input struct that contains ONLY what the client is allowed to set
#[derive(Deserialize)]
struct UpdateProfile {
    name: String,
    bio: Option<String>,
}

Never deserialize a request directly into a type that contains fields the client must not control (role, identifier, owner, price).

#[derive(Serialize)]
struct PublicUser<'a> {
    id: u32,
    name: &'a str,
    // no password hash, no email, no tokens
}

A dedicated output struct guarantees that a field added to the entity later (a token, an address) does not automatically appear in the API.

use runique::prelude::*;
use serde::Serialize;

#[derive(Serialize)]
struct ArticleSummary {
    id: Pk,
    title: String,
}

#[derive(Serialize)]
struct ArticleList {
    articles: Vec<ArticleSummary>,
    total: usize,
}

pub async fn list_articles(request: Request) -> AppResult<Response> {
    let articles = article::Entity::find()
        .filter(article::Column::Published.eq(true))
        .all(request.db())
        .await?;                                          // DbErr -> AppError automatically

    let articles: Vec<ArticleSummary> = articles
        .into_iter()
        .map(|a| ArticleSummary { id: a.id, title: a.title })
        .collect();
    let total = articles.len();

    Ok(Json(ArticleList { articles, total }).into_response())
}

Returning Vec<article::Model> directly would also compile (the Model is serializable), but it would expose every column, including those added later.

use serde::{Deserialize, Deserializer};

// 1. A String, converted later by hand: simple, but validation is postponed
#[derive(Deserialize)]
struct V1 { date: String }

// 2. chrono with its serde feature: NaiveDate reads "YYYY-MM-DD" directly
#[derive(Deserialize)]
struct V2 { date: chrono::NaiveDate }

// 3. deserialize_with: a custom format ("09/11/2026")
#[derive(Deserialize)]
struct V3 {
    #[serde(deserialize_with = "date_dmy")]
    date: chrono::NaiveDate,
}

fn date_dmy<'de, D: Deserializer<'de>>(d: D) -> Result<chrono::NaiveDate, D::Error> {
    let s = String::deserialize(d)?;
    chrono::NaiveDate::parse_from_str(&s, "%d/%m/%Y").map_err(serde::de::Error::custom)
}

// 4. A newtype with try_from: reusable everywhere
#[derive(Deserialize)]
#[serde(try_from = "String")]
struct DateDmy(chrono::NaiveDate);

impl TryFrom<String> for DateDmy {
    type Error = String;
    fn try_from(s: String) -> Result<Self, String> {
        chrono::NaiveDate::parse_from_str(&s, "%d/%m/%Y")
            .map(DateDmy)
            .map_err(|e| format!("invalid date \"{s}\": {e}"))
    }
}

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]        #[serde(deny_unknown_fields)]
#[serde(tag = "type")]   #[serde(tag = "t", content = "c")]   #[serde(untagged)]
#[serde(try_from = "String")]   #[serde(into = "String")]   #[serde(default)]

#[serde(rename = "x")]   #[serde(alias = "y")]   #[serde(skip)]
#[serde(skip_serializing_if = "Option::is_none")]   #[serde(default = "function")]
#[serde(flatten)]   #[serde(with = "module")]   #[serde(deserialize_with = "f")]   #[serde(borrow)]

serde_json::to_string(&v)?   to_string_pretty   to_vec   to_writer   to_value
serde_json::from_str::<T>(s)?   from_slice   from_reader   from_value
json!({ "a": 1 })   v["key"].as_str()   v.get("key")
toml::from_str::<T>(s)?   serde_urlencoded::from_str::<T>(s)?