Structs and JSON

20 min read

In TypeScript you reach for JSON.parse / JSON.stringify and trust that the bytes match your interface. In Rust, you map JSON onto strongly typed structs and enums with Serde, and the compiler — plus the deserializer — guarantees the shape really matches before you ever touch a field.

Quick Overview

This page is about mapping JSON documents onto Rust structs and enums: nested objects, arrays (Vec<T>), dynamically keyed objects (HashMap<K, V>), optional/null fields (Option<T>), and the four ways Serde can represent an enum (tagged unions) in JSON. You will use serde_json to turn typed values into JSON and back, with the same #[derive(Serialize, Deserialize)] you met in serde-basics.md and derive-serialize.md. The big shift from TypeScript: the structure is checked at deserialization time, not merely asserted at compile time and then ignored at runtime.

Note: The current stable toolchain is Rust 1.96.0 on the 2024 edition; cargo new selects the newest edition automatically. The examples here use serde 1.x (with the derive feature) and serde_json 1.x.

TypeScript/JavaScript Example

1
// TypeScript: an interface describes the shape, JSON.* moves bytes <-> objects.
2
interface Address {
3
  street: string;
4
  city: string;
5
  zip: string;
6
}
7

8
interface User {
9
  id: number;
10
  name: string;
11
  email: string;
12
  address: Address; // nested object
13
  roles: string[]; // JSON array
14
  settings: Record<string, boolean>; // object with dynamic keys
15
  nickname: string | null; // may be absent or null
16
}
17

18
const user: User = {
19
  id: 7,
20
  name: "Ada Lovelace",
21
  email: "ada@example.com",
22
  address: { street: "12 Analytical Ave", city: "London", zip: "EC1A" },
23
  roles: ["admin", "author"],
24
  settings: { dark_mode: true },
25
  nickname: null,
26
};
27

28
const json = JSON.stringify(user);
29
const parsed = JSON.parse(json) as User; // <- a cast, NOT a check
30
console.log(parsed.address.city); // "London"

The catch: JSON.parse(json) as User is a lie the compiler believes. TypeScript types are erased at runtime, so if the server sends { "id": "7" } or omits address, parsed still has type User and you crash later, far from the parse site. The as cast performs zero validation.

Rust Equivalent

1
use serde::{Deserialize, Serialize};
2
use std::collections::HashMap;
3

4
#[derive(Debug, Serialize, Deserialize)]
5
struct Address {
6
    street: String,
7
    city: String,
8
    zip: String,
9
}
10

11
#[derive(Debug, Serialize, Deserialize)]
12
struct User {
13
    id: u32,
14
    name: String,
15
    email: String,
16
    address: Address,                // nested struct
17
    roles: Vec<String>,              // JSON array
18
    settings: HashMap<String, bool>, // JSON object with dynamic keys
19
    nickname: Option<String>,        // may be absent / null
20
}
21

22
fn main() {
23
    let mut settings = HashMap::new();
24
    settings.insert("dark_mode".to_string(), true);
25

26
    let user = User {
27
        id: 7,
28
        name: "Ada Lovelace".to_string(),
29
        email: "ada@example.com".to_string(),
30
        address: Address {
31
            street: "12 Analytical Ave".to_string(),
32
            city: "London".to_string(),
33
            zip: "EC1A".to_string(),
34
        },
35
        roles: vec!["admin".to_string(), "author".to_string()],
36
        settings,
37
        nickname: None,
38
    };
39

40
    // Serialize to a compact JSON string.
41
    let json = serde_json::to_string(&user).unwrap();
42
    println!("compact: {json}");
43

44
    // Pretty-printed (two-space indent).
45
    let pretty = serde_json::to_string_pretty(&user).unwrap();
46
    println!("pretty:\n{pretty}");
47

48
    // Round-trip: parse it back into a typed value. This VALIDATES the shape.
49
    let parsed: User = serde_json::from_str(&json).unwrap();
50
    println!("parsed city: {}", parsed.address.city);
51
    println!("nickname is none: {}", parsed.nickname.is_none());
52
}

Real output:

1
compact: {"id":7,"name":"Ada Lovelace","email":"ada@example.com","address":{"street":"12 Analytical Ave","city":"London","zip":"EC1A"},"roles":["admin","author"],"settings":{"dark_mode":true},"nickname":null}
2
pretty:
3
{
4
  "id": 7,
5
  "name": "Ada Lovelace",
6
  "email": "ada@example.com",
7
  "address": {
8
    "street": "12 Analytical Ave",
9
    "city": "London",
10
    "zip": "EC1A"
11
  },
12
  "roles": [
13
    "admin",
14
    "author"
15
  ],
16
  "settings": {
17
    "dark_mode": true
18
  },
19
  "nickname": null
20
}
21
parsed city: London
22
nickname is none: true

Unlike TypeScript’s as User, serde_json::from_str::<User>(...) actually inspects the JSON. If id is a string, or address is missing, you get an Err, not a time bomb. We’ll see those exact error messages in Common Pitfalls.

Detailed Explanation

The two-step model: data type, then format

Serde splits the work cleanly. #[derive(Serialize, Deserialize)] teaches your type how to describe itself as a stream of generic data-model events (“a struct with field id of value 7…”). serde_json is the format crate that turns those events into JSON bytes and back. The same derived User works with TOML, YAML, MessagePack, and more (see other-formats.md) without changing the struct. This architecture is covered in serde-intro.md.

Field mapping, one line at a time

id: u32 ↔ a JSON number. Rust’s many integer types (Section 02: Basic Types) all map to JSON numbers, but they round-trip with their full range — unlike JavaScript, where every number is an IEEE-754 f64 and integers past 2^53 silently lose precision. A u64 in Rust keeps every bit.
name: String ↔ a JSON string. (String is the owned, growable string; &str borrows. See performance.md for borrowing JSON without copying.)
address: Address ↔ a nested JSON object. Serde recurses: as long as Address also derives the traits, nesting “just works” to any depth.
roles: Vec<String> ↔ a JSON array. Any Vec<T> where T is (de)serializable becomes an array; a Vec<Address> becomes an array of objects.
settings: HashMap<String, bool> ↔ a JSON object with arbitrary keys. Use a HashMap (or BTreeMap for sorted, deterministic key order) when the keys are data you don’t know at compile time. Use a struct when the keys are a fixed, known set.
nickname: Option<String> ↔ a value that may be null or absent. Some("x") serializes to "x", None serializes to null. On the way in, both null and a missing key become None.

Serializing: `to_string`, `to_string_pretty`, `to_vec`

serde_json::to_string(&value) returns a compact String. to_string_pretty adds newlines and two-space indentation for human-readable output (logs, config files, debugging). When you’re writing bytes to a socket or file, serde_json::to_vec(&value) skips the UTF-8 String step and hands you a Vec<u8> directly. All three return Result because a custom Serialize impl can fail; for plain derived structs it effectively never does, so .unwrap() is fine in examples (use ? in real code — see Section 08: The ? Operator).

Deserializing validates the shape

serde_json::from_str::<T>(s) parses the text and builds a T, returning Result<T, serde_json::Error>. Every field is checked: types must match, non-optional fields must be present. This is the single most important difference from JSON.parse(...) as T. The cost of a typo or a schema drift is paid at the boundary, as an Err you handle, rather than as an undefined that detonates three function calls later.

Top-level arrays and maps

You don’t need a wrapper struct for everything. A JSON array of objects deserializes straight into a Vec<T>:

1
use serde::{Deserialize, Serialize};
2

3
#[derive(Debug, Serialize, Deserialize)]
4
struct Point {
5
    x: i32,
6
    y: i32,
7
}
8

9
fn main() {
10
    let points: Vec<Point> =
11
        serde_json::from_str(r#"[{"x":1,"y":2},{"x":3,"y":4}]"#).unwrap();
12
    println!("points: {points:?}");
13
}

Output: points: [Point { x: 1, y: 2 }, Point { x: 3, y: 4 }].

Enums: tagged unions, four ways

A TypeScript discriminated union like { kind: "circle"; radius: number } | { kind: "rect"; w: number; h: number } maps onto a Rust enum. Serde offers four JSON representations, chosen with attributes. Given:

1
use serde::{Deserialize, Serialize};
2

3
#[derive(Debug, Serialize, Deserialize)]
4
enum Shape {
5
    Circle { radius: f64 },
6
    Rectangle { width: f64, height: f64 },
7
    Unit,
8
}

the default (externally tagged) form wraps each value in an object keyed by the variant name (and a bare string for a unit variant):

1
[{"Circle":{"radius":1.5}},{"Rectangle":{"width":2.0,"height":3.0}},"Unit"]

Add #[serde(tag = "type")] for the internally tagged form — the variant name lives in a field alongside the data, which is what most web APIs use:

1
#[derive(Debug, Serialize, Deserialize)]
2
#[serde(tag = "type")]
3
enum Event {
4
    Click { x: i32, y: i32 },
5
    KeyPress { key: String },
6
}

1
[{"type":"Click","x":10,"y":20},{"type":"KeyPress","key":"Enter"}]

#[serde(tag = "kind", content = "data")] gives the adjacently tagged form (tag and payload in two sibling fields):

1
#[derive(Debug, Serialize, Deserialize)]
2
#[serde(tag = "kind", content = "data")]
3
enum Message {
4
    Text(String),
5
    Ping,
6
}

1
[{"kind":"Text","data":"hi"},{"kind":"Ping"}]

Finally, #[serde(untagged)] produces untagged values that carry no discriminator at all — Serde tries each variant in order and keeps the first that fits:

1
#[derive(Debug, Serialize, Deserialize)]
2
#[serde(untagged)]
3
enum Scalar {
4
    Num(i64),
5
    Text(String),
6
}

1
[42,"abc"]

Serializing one value of each enum side by side makes the four shapes easy to compare:

1
external: [{"Circle":{"radius":1.5}},{"Rectangle":{"width":2.0,"height":3.0}},"Unit"]
2
internal: [{"type":"Click","x":10,"y":20},{"type":"KeyPress","key":"Enter"}]
3
adjacent: [{"kind":"Text","data":"hi"},{"kind":"Ping"}]
4
untagged: [42,"abc"]

Note: Adjacent and external tagging both accept a newtype variant such as Message::Text(String), because the payload lives in its own slot (the data field, or the value behind the variant key). Internal tagging is the exception: a newtype variant works with #[serde(tag = "...")] only if it wraps a struct or map, since the tag field has to be merged into the payload object. The tag/content/untagged attributes are part of the broader attribute toolkit covered in attributes.md.

Option fields: missing vs. `null`

This trips up everyone, so it’s worth a dedicated demonstration:

1
use serde::{Deserialize, Serialize};
2

3
#[derive(Debug, Serialize, Deserialize)]
4
struct Profile {
5
    name: String,
6
    bio: Option<String>,
7
}
8

9
fn main() {
10
    // Field present with a value.
11
    let a: Profile = serde_json::from_str(r#"{"name":"A","bio":"hello"}"#).unwrap();
12
    println!("with value: {:?}", a.bio);
13

14
    // Field present but null.
15
    let b: Profile = serde_json::from_str(r#"{"name":"B","bio":null}"#).unwrap();
16
    println!("explicit null: {:?}", b.bio);
17

18
    // Field entirely missing -> also None.
19
    let c: Profile = serde_json::from_str(r#"{"name":"C"}"#).unwrap();
20
    println!("missing field: {:?}", c.bio);
21

22
    // Serializing None emits null by default.
23
    let p = Profile { name: "D".into(), bio: None };
24
    println!("serialized None: {}", serde_json::to_string(&p).unwrap());
25
}

Output:

1
with value: Some("hello")
2
explicit null: None
3
missing field: None
4
serialized None: {"name":"D","bio":null}

Two takeaways: an Option<T> field makes the key optional on the way in (both null and “absent” deserialize to None), and None serializes to null on the way out. If you’d rather omit the key entirely when it’s None, add #[serde(skip_serializing_if = "Option::is_none")] — see attributes.md.

Key Differences

Concern	TypeScript (`JSON.*`)	Rust (Serde + `serde_json`)
Validation on parse	None — `as T` is an unchecked cast, types erased at runtime	Full — types and required fields checked; mismatch → `Err`
Integer precision	All numbers are `f64`; integers > 2^53 lose precision	Each integer type keeps its full range (`u64` is exact)
Optional fields	`field?: T` or `T	undefined`; runtime presence unknown
Dynamic-keyed object	`Record<string, V>`	`HashMap<String, V>` / `BTreeMap<String, V>`
Discriminated union	`{ kind: “a” }	{ kind: “b” }`
Unknown extra fields	Silently kept on the object	Silently ignored by default; opt into `deny_unknown_fields`
Where errors surface	Late, deep in your code	At the parse boundary, as a value

The mental shift: in TypeScript, JSON validation is your job (or a library like Zod’s). In Rust, the deserializer is the validator, generated from the type definition. You describe the shape once, in the struct, and get parsing, validation, and serialization for free.

Tip: Serde does not invent a runtime schema validator — it generates exact (de)serialization code per type at compile time via monomorphization, the same way Rust handles generics generally (TypeScript erases generics; Rust specializes them). There is no reflection and no per-call schema lookup.

Common Pitfalls

Pitfall 1: Assuming a missing field is harmless

A non-Option field is required. Leave it out and deserialization fails — which is usually what you want, but it surprises developers coming from JSON.parse’s permissiveness.

1
use serde::Deserialize;
2

3
#[derive(Debug, Deserialize)]
4
struct Config {
5
    host: String,
6
    port: u16,
7
}
8

9
fn main() {
10
    // "port" is missing from the JSON.
11
    let result: Result<Config, _> = serde_json::from_str(r#"{"host":"localhost"}"#);
12
    match result {
13
        Ok(c) => println!("ok: {}:{}", c.host, c.port),
14
        Err(e) => println!("error: {e}"),
15
    }
16

17
    // Wrong type: port is a string, not a number.
18
    let result2: Result<Config, _> =
19
        serde_json::from_str(r#"{"host":"localhost","port":"8080"}"#);
20
    match result2 {
21
        Ok(c) => println!("ok: {}:{}", c.host, c.port),
22
        Err(e) => println!("error: {e}"),
23
    }
24
}

Real output:

1
error: missing field `port` at line 1 column 20
2
error: invalid type: string "8080", expected u16 at line 1 column 33

The fix is intentional: make the field Option<u16>, or add #[serde(default)] to fall back to u16::default() (which is 0) when absent. Both are covered in attributes.md. The second error is the precision/type guarantee in action — "8080" (a string) is not accepted where a u16 is expected, even though JavaScript’s +"8080" would coerce.

Pitfall 2: Expecting unknown fields to be rejected

By default, Serde ignores JSON keys that don’t map to a struct field. This is forgiving (good for evolving APIs) but can hide typos in your data.

1
use serde::Deserialize;
2

3
// Unknown fields are silently ignored by default.
4
#[derive(Debug, Deserialize)]
5
struct Lenient {
6
    name: String,
7
}
8

9
// deny_unknown_fields makes extra keys an error.
10
#[derive(Debug, Deserialize)]
11
#[serde(deny_unknown_fields)]
12
struct Strict {
13
    name: String,
14
}
15

16
fn main() {
17
    let json = r#"{"name":"Grace","extra":true,"another":42}"#;
18

19
    let lenient: Lenient = serde_json::from_str(json).unwrap();
20
    println!("lenient ok: {}", lenient.name);
21

22
    let strict: Result<Strict, _> = serde_json::from_str(json);
23
    match strict {
24
        Ok(s) => println!("strict ok: {}", s.name),
25
        Err(e) => println!("strict error: {e}"),
26
    }
27
}

Real output:

1
lenient ok: Grace
2
strict error: unknown field `extra`, expected `name` at line 1 column 23

Pitfall 3: Untagged enum variant order

With #[serde(untagged)], Serde tries variants top to bottom and accepts the first that parses. Put a broad variant first and it will swallow inputs meant for a stricter one. A JSON 42 is a valid f64, so a Float-first enum never reaches Int:

1
use serde::{Deserialize, Serialize};
2

3
// WRONG order: Float matches integers too, so 42 deserializes as Float(42.0).
4
#[derive(Debug, Serialize, Deserialize)]
5
#[serde(untagged)]
6
enum NumWrong {
7
    Float(f64),
8
    Int(i64),
9
}
10

11
// RIGHT order: try the stricter Int variant first.
12
#[derive(Debug, Serialize, Deserialize)]
13
#[serde(untagged)]
14
enum NumRight {
15
    Int(i64),
16
    Float(f64),
17
}
18

19
fn main() {
20
    let w: NumWrong = serde_json::from_str("42").unwrap();
21
    println!("wrong order, input 42 -> {w:?}");
22

23
    let r: NumRight = serde_json::from_str("42").unwrap();
24
    println!("right order, input 42 -> {r:?}");
25

26
    let r2: NumRight = serde_json::from_str("3.5").unwrap();
27
    println!("right order, input 3.5 -> {r2:?}");
28
}

Real output:

1
wrong order, input 42 -> Float(42.0)
2
right order, input 42 -> Int(42)
3
right order, input 3.5 -> Float(3.5)

Warning: Untagged enums also produce vaguer error messages (“data did not match any variant…”) because Serde can only report that nothing matched, not why each variant failed. Prefer an internally or adjacently tagged enum whenever the JSON has (or can carry) a discriminator field. Reserve untagged for genuinely tagless inputs like “an ID is either a number or a string”.

Pitfall 4: Reaching for `serde_json::Value` too early

Coming from JavaScript, it’s tempting to deserialize into serde_json::Value (a dynamic JSON tree) and index it like a JS object. That throws away the type checking that is the whole point — and is slower. Use a typed struct whenever the shape is known. Value is for genuinely dynamic JSON; that’s the topic of json-manipulation.md.

Best Practices

Model the known shape as a struct/enum; reach for HashMap/Value only for genuinely dynamic data. Typed deserialization is your validation layer — lean on it.
Always derive Debug alongside Serialize/Deserialize. It costs nothing and makes {:?} printing and test assertions painless.
Use Option<T> for fields that may be absent, and combine it with #[serde(skip_serializing_if = "Option::is_none")] when you want absent-means-omitted on the way out. Use #[serde(default)] for fields that should fall back to a sensible value.
Prefer internally tagged enums (#[serde(tag = "...")]) for API payloads — they read naturally as JSON and give precise error messages. Save untagged for tagless inputs, and order its variants strictest-first.
Match JSON’s camelCase with #[serde(rename_all = "camelCase")] at the struct level instead of renaming each field; keep your Rust fields idiomatic snake_case. (Details in attributes.md.)
Use BTreeMap instead of HashMap when you need deterministic, sorted key ordering in the output (e.g. for stable snapshots or signatures).
Propagate errors with ? instead of .unwrap() outside of examples and tests. serde_json::Error implements std::error::Error, so it composes with Box<dyn Error>, anyhow, and thiserror (see Section 08: Error Handling).

Real-World Example

A paginated API response: a wrapper with pagination metadata, a Vec of nested Order objects, a HashMap of feature flags, an Option field that only appears once an order ships, and an internally tagged status enum — exactly the kind of payload a Rust service receives from another service or returns to a client.

1
use serde::{Deserialize, Serialize};
2
use std::collections::HashMap;
3

4
#[derive(Debug, Serialize, Deserialize)]
5
struct ApiResponse {
6
    page: u32,
7
    per_page: u32,
8
    total: u64,
9
    items: Vec<Order>,
10
    // Server-supplied feature flags keyed by name.
11
    flags: HashMap<String, bool>,
12
}
13

14
#[derive(Debug, Serialize, Deserialize)]
15
struct Order {
16
    id: u64,
17
    customer: Customer,
18
    lines: Vec<LineItem>,
19
    status: OrderStatus,
20
    // Present only once the order ships.
21
    tracking_number: Option<String>,
22
}
23

24
#[derive(Debug, Serialize, Deserialize)]
25
struct Customer {
26
    name: String,
27
    email: String,
28
}
29

30
#[derive(Debug, Serialize, Deserialize)]
31
struct LineItem {
32
    sku: String,
33
    quantity: u32,
34
    unit_price_cents: u64,
35
}
36

37
// An internally tagged enum models a discriminated union, just like a
38
// TypeScript `{ status: "shipped"; carrier: string } | ...`.
39
#[derive(Debug, Serialize, Deserialize)]
40
#[serde(tag = "status", rename_all = "snake_case")]
41
enum OrderStatus {
42
    Pending,
43
    Shipped { carrier: String },
44
    Cancelled { reason: String },
45
}
46

47
fn handle_payload(raw: &str) -> Result<ApiResponse, serde_json::Error> {
48
    let response: ApiResponse = serde_json::from_str(raw)?;
49
    Ok(response)
50
}
51

52
fn main() {
53
    let raw = r#"
54
    {
55
      "page": 1,
56
      "per_page": 20,
57
      "total": 137,
58
      "flags": { "new_checkout": true, "promo_banner": false },
59
      "items": [
60
        {
61
          "id": 1001,
62
          "customer": { "name": "Ada", "email": "ada@example.com" },
63
          "lines": [
64
            { "sku": "BOOK-1", "quantity": 2, "unit_price_cents": 1599 }
65
          ],
66
          "status": { "status": "shipped", "carrier": "DHL" },
67
          "tracking_number": "1Z999"
68
        },
69
        {
70
          "id": 1002,
71
          "customer": { "name": "Linus", "email": "linus@example.com" },
72
          "lines": [
73
            { "sku": "MUG-7", "quantity": 1, "unit_price_cents": 899 }
74
          ],
75
          "status": { "status": "pending" }
76
        }
77
      ]
78
    }"#;
79

80
    let response = handle_payload(raw).expect("valid payload");
81

82
    println!("page {} of {} total orders", response.page, response.total);
83
    println!("new_checkout flag = {}", response.flags["new_checkout"]);
84

85
    for order in &response.items {
86
        let total_cents: u64 = order
87
            .lines
88
            .iter()
89
            .map(|l| l.quantity as u64 * l.unit_price_cents)
90
            .sum();
91
        let summary = match &order.status {
92
            OrderStatus::Pending => "pending".to_string(),
93
            OrderStatus::Shipped { carrier } => {
94
                let tracking = order.tracking_number.as_deref().unwrap_or("n/a");
95
                format!("shipped via {carrier} (tracking {tracking})")
96
            }
97
            OrderStatus::Cancelled { reason } => format!("cancelled: {reason}"),
98
        };
99
        println!(
100
            "order {} for {} -> {} | total ${:.2}",
101
            order.id,
102
            order.customer.name,
103
            summary,
104
            total_cents as f64 / 100.0
105
        );
106
    }
107

108
    // Re-serialize one order to forward to another service.
109
    let echo = serde_json::to_string(&response.items[0]).unwrap();
110
    println!("echo: {echo}");
111
}

Real output:

1
page 1 of 137 total orders
2
new_checkout flag = true
3
order 1001 for Ada -> shipped via DHL (tracking 1Z999) | total $31.98
4
order 1002 for Linus -> pending | total $8.99
5
echo: {"id":1001,"customer":{"name":"Ada","email":"ada@example.com"},"lines":[{"sku":"BOOK-1","quantity":2,"unit_price_cents":1599}],"status":{"status":"shipped","carrier":"DHL"},"tracking_number":"1Z999"}

Notice what the type system bought you: the match on order.status is exhaustive — add a Refunded variant later and the compiler forces you to handle it everywhere. Prices are kept in integer cents (u64), sidestepping the float-rounding bugs you’d risk in JavaScript, and only formatted as a float for display. And handle_payload returns a Result, so a malformed payload is a caught error, not a thrown exception that escapes the function. When this struct backs an HTTP handler, the same derives plug straight into a web framework — see Section 16: Web APIs.

Exercises

Exercise 1: Round-trip a blog post

Difficulty: Easy

Objective: Define a struct that mixes a string, an array, and a boolean, then serialize and deserialize it.

Instructions: Create a BlogPost struct with title: String, tags: Vec<String>, and published: bool. Build one, serialize it to a JSON string with serde_json::to_string, print it, then deserialize it back and print the recovered title. Remember the derive feature and the Serialize/Deserialize derives.

1
use serde::{Deserialize, Serialize};
2

3
// TODO: derive Serialize + Deserialize (and Debug)
4
struct BlogPost {
5
    title: String,
6
    tags: Vec<String>,
7
    published: bool,
8
}
9

10
fn main() {
11
    let post = BlogPost {
12
        title: "Hello".into(),
13
        tags: vec!["rust".into(), "serde".into()],
14
        published: true,
15
    };
16
    // TODO: serialize, print, deserialize, print the title
17
}

Solution

1
use serde::{Deserialize, Serialize};
2

3
#[derive(Debug, Serialize, Deserialize)]
4
struct BlogPost {
5
    title: String,
6
    tags: Vec<String>,
7
    published: bool,
8
}
9

10
fn main() {
11
    let post = BlogPost {
12
        title: "Hello".into(),
13
        tags: vec!["rust".into(), "serde".into()],
14
        published: true,
15
    };
16

17
    let s = serde_json::to_string(&post).unwrap();
18
    println!("serialized: {s}");
19

20
    let back: BlogPost = serde_json::from_str(&s).unwrap();
21
    println!("recovered title: {}", back.title);
22
}

Output:

1
serialized: {"title":"Hello","tags":["rust","serde"],"published":true}
2
recovered title: Hello

Exercise 2: Nested structs, a map, and an optional field

Difficulty: Medium

Objective: Combine nesting, Vec<Struct>, HashMap, and Option in one type.

Instructions: Model a Team with name: String, members: Vec<Member>, and scores: HashMap<String, u32>. A Member has handle: String and an optional captain: Option<bool>. Construct a team where one member has captain: Some(true) and another has None, then serialize it. Confirm in the output that the None captain becomes null while the map and the nested array serialize correctly.

Solution

1
use serde::{Deserialize, Serialize};
2
use std::collections::HashMap;
3

4
#[derive(Debug, Serialize, Deserialize)]
5
struct Team {
6
    name: String,
7
    members: Vec<Member>,
8
    scores: HashMap<String, u32>,
9
}
10

11
#[derive(Debug, Serialize, Deserialize)]
12
struct Member {
13
    handle: String,
14
    captain: Option<bool>,
15
}
16

17
fn main() {
18
    let mut scores = HashMap::new();
19
    scores.insert("round1".to_string(), 42u32);
20

21
    let team = Team {
22
        name: "Crustaceans".into(),
23
        members: vec![
24
            Member { handle: "ferris".into(), captain: Some(true) },
25
            Member { handle: "gopher".into(), captain: None },
26
        ],
27
        scores,
28
    };
29

30
    println!("{}", serde_json::to_string(&team).unwrap());
31
}

Output:

1
{"name":"Crustaceans","members":[{"handle":"ferris","captain":true},{"handle":"gopher","captain":null}],"scores":{"round1":42}}

The None captain rendered as null. To omit it instead, you’d add #[serde(skip_serializing_if = "Option::is_none")] — see attributes.md.

Exercise 3: A tagged command protocol

Difficulty: Hard

Objective: Use an internally tagged enum to parse a JSON command stream and re-serialize it.

Instructions: Define a Command enum with variants Move { x: i32, y: i32 }, Say { text: String }, and Quit. Use #[serde(tag = "op", rename_all = "lowercase")] so the discriminator is the op field and variant names appear lowercased. Deserialize the array [{"op":"move","x":1,"y":2},{"op":"say","text":"hi"},{"op":"quit"}] into a Vec<Command>, print it with {:?}, then serialize it back and confirm the JSON matches.

Solution

1
use serde::{Deserialize, Serialize};
2

3
#[derive(Debug, Serialize, Deserialize)]
4
#[serde(tag = "op", rename_all = "lowercase")]
5
enum Command {
6
    Move { x: i32, y: i32 },
7
    Say { text: String },
8
    Quit,
9
}
10

11
fn main() {
12
    let input = r#"[{"op":"move","x":1,"y":2},{"op":"say","text":"hi"},{"op":"quit"}]"#;
13

14
    let cmds: Vec<Command> = serde_json::from_str(input).unwrap();
15
    println!("parsed: {cmds:?}");
16

17
    let json = serde_json::to_string(&cmds).unwrap();
18
    println!("reserialized: {json}");
19
}

Output:

1
parsed: [Move { x: 1, y: 2 }, Say { text: "hi" }, Quit]
2
reserialized: [{"op":"move","x":1,"y":2},{"op":"say","text":"hi"},{"op":"quit"}]

The round-trip is lossless: rename_all = "lowercase" controls the variant names, and tag = "op" places the discriminator inline. Internal tagging like this is the idiomatic way to model a JSON discriminated union in Rust.

Structs and JSON

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The two-step model: data type, then format

Field mapping, one line at a time

Serializing: to_string, to_string_pretty, to_vec

Deserializing validates the shape

Top-level arrays and maps

Enums: tagged unions, four ways

Option fields: missing vs. null

Key Differences

Common Pitfalls

Pitfall 1: Assuming a missing field is harmless

Pitfall 2: Expecting unknown fields to be rejected

Pitfall 3: Untagged enum variant order

Pitfall 4: Reaching for serde_json::Value too early

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Round-trip a blog post

Exercise 2: Nested structs, a map, and an optional field

Exercise 3: A tagged command protocol

Serializing: `to_string`, `to_string_pretty`, `to_vec`

Option fields: missing vs. `null`

Pitfall 4: Reaching for `serde_json::Value` too early