serde_json Documentation

For most use cases, you should map JSON data directly into strongly typed Rust structs or enums. This provides compile-time safety, IDE autocompletion, and informative error messages if the JSON structure does not match your type.

Requirements

Your data structures must implement the serde::Deserialize trait. You can use #[derive(Deserialize)] to implement this automatically.

use serde::{Deserialize, Serialize};
use serde_json::Result;

#[derive(Serialize, Deserialize)]
struct Person {
    name: String,
    age: u8,
    phones: Vec<String>,
}

fn typed_example() -> Result<()> {
    let data = r""
        {
            "name": "John Doe",
            "age": 43,
            "phones": [
                "+44 1234567"
            ]
        }"";

    // Parse the string of data into a Person object.
    let p: Person = serde_json::from_str(data)?;

    // Do things just like with any other Rust data structure.
    println!("Please call {} at the number {}", p.name, p.phones[0]);

    Ok(())
}

You can manipulate JSON data without defining a specific Rust structure by parsing it into the serde_json::Value enum. This is useful for loosely typed data or basic manipulations.

Parsing methods

• serde_json::from_str: Parse from a &str.
• serde_json::from_slice: Parse from a byte slice &[u8].
• serde_json::from_reader: Parse from any io::Read (e.g., File, TCP stream).

Accessing data

You can access parts of a Value using square bracket indexing (e.g., v["key"] or v[0]).

• Indexing a map with a string key or an array with an integer key returns a &Value.
• If the key does not exist, the index is out of bounds, or the type is incorrect, the returned element is Value::Null.
• To get a plain Rust string instead of the JSON representation (which includes quotes), use the .as_str() method.

use serde_json::{Result, Value};

fn untyped_example() -> Result<()> {
    // Some JSON input data as a &str. Maybe this comes from the user.
    let data = r""
        {
            "name": "John Doe",
            "age": 43,
            "phones": [
                "+44 1234567"
            ]
        }"";

    // Parse the string of data into serde_json::Value.
    let v: Value = serde_json::from_str(data)?;

    // Access parts of the data by indexing with square brackets.
    println!("Please call {} at the number {}", v["name"], v["phones"][0]);

    Ok(())
}

You can use the IndexMut implementation (the value[index] = ... syntax) to modify or insert values into a serde_json::Value.

• Arrays: If the index is a usize, the value must be an array with a length greater than the index. If the index is out of bounds or the value is not an array, the program will panic.
• Objects: If the index is a str or String, the value must be an object or Value::Null (which is treated as an empty object). If the key is not already present, it will be inserted with a value of Value::Null before being overwritten. If the value is neither an object nor null, the program will panic.

Warning: Unlike read-only indexing, mutable indexing can cause panics if the underlying JSON structure does not match your expectations.

# use serde_json::json;

let mut data = json!({ "x": 0 });

// replace an existing key
data["x"] = json!(1);

// insert a new key
data["y"] = json!([false, false, false]);

// replace an array value
data["y"][0] = json!(true);

// inserted a deeply nested key
data["a"]["b"]["c"]["d"] = json!(true);