Crate serde_json_path_to_error

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;

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

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.