Crate serde_json5

JSON5 is a superset of JSON with an expanded syntax including some productions from ECMAScript 5.1.

In particular, JSON5 allows comments, trailing commas, object keys without quotes, single quoted strings and more. See the JSON5 project page for full details.

{
  // comments
  unquoted: 'and you can quote me on that',
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Look, Mom! \
No \\n's!",
  hexadecimal: 0xdecaf,
  leadingDecimalPoint: .8675309, andTrailing: 8675309.,
  positiveSign: +1,
  trailingComma: 'in objects', andIn: ['arrays',],
  "backwardsCompatible": "with JSON",
}

This crate provides functions for deserializing JSON5 text into a Rust datatype and for serializing a Rust datatype as JSON5 text, both via the Serde framework.

Deserialization

Implementing Serde’s Deserialize trait on your type will allow you to parse JSON5 text into a value of that type with from_str.

use serde_derive::Deserialize;

#[derive(Deserialize, Debug, PartialEq)]
struct Config {
    message: String,
    n: i32,
}

let config = "
    {
      // A traditional message.
      message: 'hello world',

      // A number for some reason.
      n: 42,
    }
";

assert_eq!(
    serde_json5::from_str(config),
    Ok(Config {
        message: "hello world".to_string(),
        n: 42,
    }),
);

There are many ways to customise the deserialization (e.g. deserializing camelCase field names into a struct with snake_case fields). See the Serde docs, especially the Attributes, Custom serialization and Examples sections.

Serialization

Similarly, implementing Serialize on a Rust type allows you to produce a JSON5 serialization of values of that type with to_string. At present the serializer will just produce JSON (since it’s a valid subset of JSON5), but future work will allow specifying the output style (single over double quotes, trailing commas, indentation etc.).

use serde_derive::Serialize;

#[derive(Serialize, PartialEq, Debug)]
#[serde(untagged)]
enum Val {
    Number(f64),
    Bool(bool),
    String(String),
}

assert_eq!(
    serde_json5::to_string(&vec![
        Val::Number(42.),
        Val::Bool(true),
        Val::String("hello".to_owned()),
    ]),
    Ok("[42,true,\"hello\"]".to_owned()),
)

There are many ways to customise the serialization (e.g. serializing snake_case struct fields as camelCase). See the Serde docs, especially the Attributes, Custom serialization and Examples sections.

Limitations

At the time of writing the following is unsupported:

• deserializing into borrowed types (e.g. fields of type &str)

• serializing or deserializing byte arrays

• specifying the style of JSON5 output from the serializer (single over double quotes, trailing commas, indentation etc.)

Structs

• Location
  One-based line and column at which the error was detected.

Enums

• Error
  A bare bones error type which currently just collapses all the underlying errors in to a single string… This is fine for displaying to the user, but not very useful otherwise. Work to be done here.

Functions

• from_reader
  Deserialize an instance of type T from any implementation of Read. Can fail if the input is invalid JSON5, or doesn’t match the structure of the target type.
• from_slice
  Deserialize an instance of type T from a slice of JSON5 text. Can fail if the input is invalid JSON5, or doesn’t match the structure of the target type.
• from_str
  Deserialize an instance of type T from a string of JSON5 text. Can fail if the input is invalid JSON5, or doesn’t match the structure of the target type.
• to_string
  Attempts to serialize the input as a JSON5 string (actually a JSON string).

Type Aliases

• Result
  Alias for a Result with error type json5::Error