miniserde

Miniserde's derive macros are intentionally minimal and only support a subset of Rust data structures:

• Structs: Braced structs with named fields.
• Enums: Enums with C-style unit variants.

Unsupported structures include:

• Tuple structs.
• Enums with data in their variants (e.g., enums with fields).
• Types that might cause serialization to fail (e.g., Mutex).

Add miniserde to your Cargo.toml dependencies to use the library for JSON serialization and deserialization.

[dependencies]
miniserde = "0.1"

In miniserde, when deserializing data, you can use the Visitor::ignore() method to handle fields that are not part of your target data structure. The ignore() method returns a &'static mut dyn Visitor that effectively consumes any incoming data (nulls, booleans, strings, numbers, sequences, or maps) without performing any operations or returning errors. This is useful for making your deserialization logic resilient to extra fields in the input JSON.

// While the direct usage is typically internal to the deserialization engine,
// the concept allows the parser to skip unknown keys or values.
// The Visitor::ignore() method is the mechanism used to discard data.

When using miniserde's deserialization functions, errors are returned via the miniserde::Result<T> type.

Important Limitation: The miniserde::Error type is an opaque unit struct. It contains no information about why deserialization failed (e.g., missing fields, type mismatches, or syntax errors). If your application requires detailed error messages or diagnostic information to recover from or report specific failures, you should use Serde instead of miniserde.

// Deserialization returns a Result<T, miniserde::Error>
// Note that the error provides no context on the failure.
match miniserde::json::from_str::<MyStruct>(json_data) {
    Ok(data) => println!("Success: {:?}", data),
    Err(e) => println!("Deserialization failed: {}", e), // Prints "miniserde error"
}

Use miniserde::json::to_string to convert any type that implements the Serialize trait into a JSON-formatted String. This is the primary way to perform JSON serialization in miniserde.

use miniserde::{json, Serialize};

#[derive(Serialize, Debug)]
struct Example {
    code: u32,
    message: String,
}

fn main() {
    let example = Example {
        code: 200,
        message: "reminiscent of Serde".to_owned(),
    };

    let j = json::to_string(&example);
    println!("{}", j);
}

Convert any type implementing the Serialize trait into a JSON String. Serialization in miniserde is infallible, meaning it always succeeds and returns a String rather than a Result.

let j = json::to_string(&your_struct);

Parse a JSON string into a type that implements the Deserialize trait. This operation can fail, so it returns a miniserde::Result<T>.

let out: YourType = json::from_str(&json_string)?;

Use miniserde::json::from_str to deserialize a JSON string into a type that implements the Deserialize trait. This function returns a miniserde::Result<T>, which will return Err(Error) if the JSON is malformed or does not match the target type structure.

use miniserde::{json, Deserialize};

#[derive(Deserialize, Debug)]
struct Example {
    code: u32,
    message: String,
}

fn main() -> miniserde::Result<()> {
    let j = r#" {"code": 200, "message": "reminiscent of Serde"} "#;

    let out: Example = json::from_str(&j)?;
    println!("{:?}", out);

    Ok(())
}

To serialize a sequence (like a Vec), implement the Seq trait. The next method should return an Option<&dyn Serialize>, providing the next element in the sequence. This is typically used inside a Fragment::Seq(Box<dyn Seq>) returned by Serialize::begin.

use miniserde::ser::{Fragment, Seq, Serialize};

struct MyVec<T>(Vec<T>);

impl<T> Serialize for MyVec<T>
where
    T: Serialize,
{
    fn begin(&self) -> Fragment {
        Fragment::Seq(Box::new(SliceStream { iter: self.0.iter() }))
    }
}

struct SliceStream<'a, T: 'a> {
    iter: std::slice::Iter<'a, T>,
}

impl<'a, T> Seq for SliceStream<'a, T>
where
    T: Serialize,
{
    fn next(&mut self) -> Option<&dyn Serialize> {
        let element = self.iter.next()?;
        Some(element)
    }
}