Crate serde_json_path_to_error

Expand description

§serde_json_path_to_error

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;

#[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.

Modules§

de: Deserialize JSON data to a Rust data structure.
error: When serializing or deserializing JSON goes wrong.
map: A map of String to serde_json::Value.
ser: Serialize a Rust data structure into JSON data.
value: The Value enum, a loosely typed way of representing any valid JSON value.

Macros§

json: Construct a serde_json::Value from a JSON literal.

Structs§

Deserializer: A structure that deserializes JSON into Rust values.
Map: Represents a JSON key/value type.
Number: Represents a JSON number, whether integer or floating point.
Serializer: A structure for serializing Rust values into JSON.
StreamDeserializer: Iterator that deserializes a stream into multiple JSON values.

Enums§

Value: Represents any valid JSON value.

Traits§

Formatter: This trait abstracts away serializing the JSON control characters, which allows the user to optionally pretty print the JSON output.

Functions§

from_reader: Deserialize an instance of type T from an I/O stream of JSON.
from_slice: Deserialize an instance of type T from bytes of JSON text.
from_str: Deserialize an instance of type T from a string of JSON text.
from_value: Interpret a serde_json::Value as an instance of type T.
to_string: Serialize the given data structure as a String of JSON.
to_string_pretty: Serialize the given data structure as a pretty-printed String of JSON.
to_value: Convert a T into serde_json::Value which is an enum that can represent
to_vec: Serialize the given data structure as a JSON byte vector.
to_vec_pretty: Serialize the given data structure as a pretty-printed JSON byte vector.
to_writer: Serialize the given data structure as JSON into the I/O stream.
to_writer_pretty: Serialize the given data structure as pretty-printed JSON into the I/O stream.

Type Aliases§

Error: This type represents all possible errors that can occur when serializing or deserializing JSON data.
Result: Alias for a Result with the error type serde_json_path_to_error::Error.

Crate serde_json_path_to_errorCopy item path