sval 0.4.7

A no-std, object-safe serialization framework

sval

Build Status Latest version Documentation Latest

A lightweight, no-std, object-safe, serialization-only API for structured values with serde and std::fmt support.

Producers of structured values use the value module. Consumers of structured values use the stream module.

sval offers a JSON-like data model, which is more limiting than serde's, but capable enough to represent Rust data-structures in one form or another.

This library is designed to plug a no-std-object-safe sized hole in Rust's current serialization ecosystem. The driving use-case is structured logging, where individual events are typically small, and there's no complete schema that can tie values in any one event to values in another.

sval_json and sval_derive are mostly pilfered from dtolnay's excellent miniserde project.

Supported formats

  • JSON, the ubiquitous JavaScript Object Notation used by many HTTP APIs.

Minimum rustc

This library requires Rust 1.31.0.

See also

Cargo features

sval has the following optional features that can be enabled in your Cargo.toml:

  • std: assume std is available and add support for std types.
  • derive: add support for #[derive(Value)].
  • serde: enable integration with serde.
    • serde_std (same as serde): enable serde integration along with std. This is for maximum ecosystem compatibility.
    • serde_no_std: enable serde integration without needing std. Some implementations of sval::Value may not be representable. This is for specialized no_std use-cases.
  • fmt: support converting any Value into a Debug.
  • arbitrary-depth: support stateful values with any depth.
  • test: add helpers for testing implementations of Value.

How to use it

Add sval to your crate dependencies:

[dependencies.sval]
version = "0.4.7"

To support my data-structures

Simple struct-like data-structures can derive sval::Value:

[dependencies.sval]
features = ["derive"]
#[macro_use]
extern crate sval;

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

Other data-structures can implement sval::Value manually:

use sval::value::{self, Value};

struct MyId(u64);

impl Value for MyId {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.u64(self.0)
    }
}

To format my data

The sval_json crate can format any sval::Value as JSON:

[dependencies.sval_json]
version = "0.4.7"
features = ["std"]
let my_json = sval_json::to_string(my_data)?;

To integrate with serde

sval has out-of-the-box serde integration between sval::Values and serde::Serializes. Add the serde feature to sval to enable it:

[dependencies.sval]
features = ["serde"]

Use the to_serialize function to turn any sval::Value into a serde::Serialize:

let my_serialize = sval::serde::to_serialize(my_data);

Use the to_value function to turn any serde::Serialize into a sval::Value:

let my_value = sval::serde::to_value(my_data);

When the serde feature is available, structures that already derive Serialize can also always derive Value. The Value implementation will behave the same as Serialize:

#[derive(Serialize, Value)]
#[sval(derive_from = "serde")]
struct MyData {
    id: u64,
    name: String,
    #[serde(flatten)]
    props: serde_json::Map<String, serde_json::Value>,
}

To integrate with std::fmt

sval can provide a compatible Debug implementation for any sval::Value. Add the fmt feature to sval to enable it:

[dependencies.sval]
features = ["fmt"]

Use the to_debug function to turn any sval::Value into a std::fmt::Debug:

fn with_value(value: impl Value) {
    dbg!(sval::fmt::to_debug(&value));

    ..
}