sval
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
: assumestd
is available and add support forstd
types. Impliesalloc
.alloc
: assume a global allocator is available.derive
: add support for#[derive(Value)]
.serde
: enable integration with major versions ofserde
. Some implementations ofsval::Value
may not be representable without thealloc
feature.serde1
: enable integration with just the1.x
version ofserde
. Any future versions ofserde
will also receive their own feature.
fmt
: support converting anyValue
into aDebug
.arbitrary-depth
: support stateful values with any depth. Impliesalloc
.test
: add helpers for testing implementations ofValue
. Impliesstd
. You should avoid using this feature outside ofdev-dependencies
.
How to use it
Add sval
to your crate dependencies:
[]
= "1.0.0-alpha.5"
To support my data-structures
Simple struct-like data-structures can derive sval::Value
:
[]
= ["derive"]
extern crate sval;
Other data-structures can implement sval::Value
manually:
use ;
;
To format my data
The sval_json
crate can format any sval::Value
as JSON:
[]
= "1.0.0-alpha.5"
= ["std"]
let my_json = to_string?;
To integrate with serde
sval
has out-of-the-box serde
integration between sval::Value
s and serde::Serialize
s. Add the serde
feature to sval
to enable it:
[]
= ["serde"]
Use the to_serialize
function to turn any sval::Value
into a serde::Serialize
:
let my_serialize = to_serialize;
Use the to_value
function to turn any serde::Serialize
into a sval::Value
:
let my_value = to_value;
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
:
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:
[]
= ["fmt"]
Use the to_debug
function to turn any sval::Value
into a std::fmt::Debug
: