eserde

Standard serde deserializers (like serde_json) abort as soon as the first error is encountered. This forces API consumers into a slow feedback loop of fixing one error at a time.

eserde solves this by performing a second pass over the input when an error occurs. It uses the eserde::EDeserialize trait to accumulate multiple errors across the entire payload, allowing you to report all schema violations (e.g., missing fields, type mismatches, or null values) to the user in a single response.

#[derive(Debug, eserde::Deserialize)]
struct Version {
    major: u32,
    minor: u32,
    patch: u32,
}

#[derive(Debug, eserde::Deserialize)]
struct Package {
    version: Version,
    source: String,
}

let payload = r#"{
    "version": {
        "major": 1,
        "minor": "2"
    },
    "source": null
}"#;

// eserde::json::from_str returns all errors found in the payload
let errors = eserde::json::from_str::<Package>(&payload).unwrap_err();

// Output will include multiple errors:
// - version.minor: invalid type: string "2", expected u32 ...
// - version: missing field `patch` ...
// - source: invalid type: null, expected a string ...

The Deserializer<D> struct is an adapter designed to wrap an existing Serde Deserializer. Its primary purpose is to record the structural path (e.g., map keys, sequence indices, enum variants) during the deserialization process. If a deserialization error occurs, this path information can be used to provide precise context about where the error happened in the data structure.

It works by wrapping visitors and seeds with specialized types:

• Wrap<V>: Wraps a Visitor to track structural changes like entering sequences or maps.
• CaptureKey<X>: A specialized Deserializer and Visitor used during map key deserialization to capture the string representation of the key so it can be pushed onto the PathTracker.
• TrackedSeed<X>: Wraps a DeserializeSeed to ensure that when seeds are used (for example, for elements in a sequence or values in a map), they use the path-aware Deserializer.
• SeqAccess and MapAccess: Custom implementations of Serde's access traits that manage the PathTracker state by pushing segments (like Segment::Seq { index } or Segment::Map { key }) and popping them when the scope is exited.

When using the Json extractor in eserde_axum, several types of errors can occur during the request lifecycle. These errors are encapsulated in the JsonRejection enum. All error responses generated by these rejections follow the RFC 9457 Problem Details specification.

Common failure scenarios include:

1. Deserialization Failures (JsonError): Occurs when the request body is valid JSON but cannot be mapped to the target schema. The response includes specific validation errors and JSON pointers to the problematic fields.
2. Missing Content-Type (MissingJsonContentType): Occurs when the Content-Type header is absent from the request.
3. Incorrect Content-Type (JsonContentTypeMismatch): Occurs when the Content-Type header is present but does not match application/json or an application/*+json pattern.
4. Body Buffering Issues (BytesRejection): Occurs when the request body cannot be read or exceeds size limits (e.g., content_too_large).

Unlike serde::Deserialize, which aborts on the first error, eserde::Deserialize is designed to accumulate multiple errors in a single pass. This is useful for providing comprehensive feedback to users of an API.

To implement this, you must:

1. Replace #[derive(serde::Deserialize)] with #[derive(eserde::Deserialize)] on your structs.
2. Use an eserde-specific deserialization function (like eserde::json::from_str) instead of the standard serde_json functions.

#[derive(Debug, eserde::Deserialize)]
struct Package {
    version: Version,
    source: String,
}

#[derive(Debug, eserde::Deserialize)]
struct Version {
    major: u32,
    minor: u32,
    patch: u32,
}

let payload = r#"{
    "version": {
        "major": 1,
        "minor": "2"
    },
    "source": null
}"#;

// Use eserde::json instead of serde_json
let errors = eserde::json::from_str::<Package>(&payload).unwrap_err();

// errors.to_string() will contain multiple errors:
// - version.minor: invalid type: string "2", expected u32...
// - version: missing field `patch`...
// - source: invalid type: null, expected a string...

If you are implementing eserde support for a new data format, you must use the ErrorReporter to collect and report errors during deserialization. Because serde's Deserialize trait does not allow passing an error accumulator through the call stack, eserde uses a thread-local storage mechanism managed by ErrorReporter.

To use it, you must follow this lifecycle:

1. Initialize: Call ErrorReporter::start_deserialization() to create an ErrorReporterGuard. This initializes the PathTracker and the error buffer.
2. Maintain Guard: You must keep the ErrorReporterGuard alive for the entire duration of the deserialization operation. If the guard is dropped, the error buffer is cleared and the operation is considered finished.
3. Report Errors: During deserialization, call ErrorReporter::report(e) whenever an error occurs. This will capture the error along with its location in the data structure.
4. Collect Errors: Once deserialization is complete (but while the guard is still alive), call ErrorReporter::take_errors() to retrieve the accumulated Vec<DeserializationError>.

// Example pattern for format implementers
let _guard = ErrorReporter::start_deserialization();

// ... perform deserialization using EDeserialize::deserialize_for_errors ...

let errors = ErrorReporter::take_errors();
if !errors.is_empty() {
    // handle errors
}
// _guard is dropped here, cleaning up state

To implement the EDeserialize trait for your types, you should not use the eserde_derive crate directly. Instead, use the Deserialize derive macro provided by the main eserde crate. This ensures that the correct version of the procedural macro is used and that all necessary internal shadow types and companion types are correctly wired.

When you apply #[derive(Deserialize)] to a struct or enum, the macro generates:

1. A Shadow Type: An internal representation used to perform the actual deserialization.
2. A Companion Type: Used for error reporting and validation.
3. An implementation of ::eserde::EDeserialize<'de> for error-aware deserialization.
4. An implementation of ::eserde::_serde::Deserialize<'de> that uses the shadow type and then initializes the target type from it.

use eserde::Deserialize;

#[derive(Deserialize)]
struct MyData {
    id: u64,
    name: String,
}