README.md

serde_json_path_to_error

API docs

A drop in replacement for serde_json with errors enriched by serde_path_to_error.

This is usually a better default since it makes it easier to debug when serialization or deserialization fails. Paths are particularly helpful when your schema is large or when it's difficult to see the raw data that causes an error.

This crate exposes the same items as serde_json, just with different error types. For more detailed documentation see serde_json.

Migrating from serde_json

To enrich your errors simply replace your dependency on serde_json with one on serde_json_path_to_error.

- serde_json = "1.0"
+ serde_json = { package = "serde_json_path_to_error", version = "0.1" }

Alternatively, you can add serde_json_path_to_error as a regular dependancy...

# cargo add serde_json_path_to_error 

..and rename the crate in your crate root to get the same API as serde_json.

extern crate serde_json_path_to_error as serde_json;

In most cases, your project should continue to compile after migrating. Your errors will now be enriched with additional context showing the path to serialization and deserialization failures.

// the rename trick shown above
extern crate serde_json_path_to_error as serde_json;

# use std::collections::BTreeMap as Map;
# use serde::Deserialize;
#[derive(Deserialize)]
struct Package {
    name: String,
    dependencies: Map<String, Dependency>,
}

#[derive(Deserialize)]
struct Dependency {
    version: String,
}

fn main() {
    let j = r#"{
        "name": "demo",
        "dependencies": {
            "serde": {
                "version": 1
            }
        }
    }"#;


    // Uses the enriched version from [serde_json_path_to_error] but with the exact same API
    // you've come to expect from [serde_json]
    let result: Result<Package, _> = serde_json::from_str(j);

    match result {
        Ok(_) => panic!("expected a type error"),
        Err(err) => {
            // You get the error including the path as a default
            assert_eq!(
              err.to_string(),
              "dependencies.serde.version: invalid type: integer `1`, expected a string at line 5 column 28",
            );
            // You can get just the path
            assert_eq!(
              err.path().to_string(),
              "dependencies.serde.version",
            );
            // Or just the original serde_json error
            assert_eq!(
              err.into_inner().to_string(),
              "invalid type: integer `1`, expected a string at line 5 column 28",
            );
        }
    }
}

Caveats

There are still a small number of items that don't return enriched errors. I'd be interested in accepting PRs that wrap these items.

• [serde_json::de::Deserializer] #6
• [serde_json::de::StreamDeserializer] #5
• [serde_json::ser::Serializer] #4
• [serde_json::value::Serializer] #3