| 1 |
# Serde JSON   [![Build Status]][actions] [![Latest Version]][crates.io] [![Rustc Version 1.36+]][rustc] |
| 2 |
|
| 3 |
[Build Status]: https://img.shields.io/github/actions/workflow/status/serde-rs/json/ci.yml?branch=master |
| 4 |
[actions]: https://github.com/serde-rs/json/actions?query=branch%3Amaster |
| 5 |
[Latest Version]: https://img.shields.io/crates/v/serde_json.svg |
| 6 |
[crates.io]: https://crates.io/crates/serde\_json |
| 7 |
[Rustc Version 1.36+]: https://img.shields.io/badge/rustc-1.36+-lightgray.svg |
| 8 |
[rustc]: https://blog.rust-lang.org/2019/07/04/Rust-1.36.0.html |
| 9 |
|
| 10 |
**Serde is a framework for *ser*ializing and *de*serializing Rust data structures efficiently and generically.** |
| 11 |
|
| 12 |
--- |
| 13 |
|
| 14 |
```toml |
| 15 |
[dependencies] |
| 16 |
serde_json = "1.0" |
| 17 |
``` |
| 18 |
|
| 19 |
You may be looking for: |
| 20 |
|
| 21 |
- [JSON API documentation](https://docs.rs/serde_json) |
| 22 |
- [Serde API documentation](https://docs.rs/serde) |
| 23 |
- [Detailed documentation about Serde](https://serde.rs/) |
| 24 |
- [Setting up `#[derive(Serialize, Deserialize)]`](https://serde.rs/derive.html) |
| 25 |
- [Release notes](https://github.com/serde-rs/json/releases) |
| 26 |
|
| 27 |
JSON is a ubiquitous open-standard format that uses human-readable text to |
| 28 |
transmit data objects consisting of key-value pairs. |
| 29 |
|
| 30 |
```json |
| 31 |
{ |
| 32 |
"name": "John Doe", |
| 33 |
"age": 43, |
| 34 |
"address": { |
| 35 |
"street": "10 Downing Street", |
| 36 |
"city": "London" |
| 37 |
}, |
| 38 |
"phones": [ |
| 39 |
"+44 1234567", |
| 40 |
"+44 2345678" |
| 41 |
] |
| 42 |
} |
| 43 |
``` |
| 44 |
|
| 45 |
There are three common ways that you might find yourself needing to work with |
| 46 |
JSON data in Rust. |
| 47 |
|
| 48 |
- **As text data.** An unprocessed string of JSON data that you receive on an |
| 49 |
HTTP endpoint, read from a file, or prepare to send to a remote server. |
| 50 |
- **As an untyped or loosely typed representation.** Maybe you want to check |
| 51 |
that some JSON data is valid before passing it on, but without knowing the |
| 52 |
structure of what it contains. Or you want to do very basic manipulations |
| 53 |
like insert a key in a particular spot. |
| 54 |
- **As a strongly typed Rust data structure.** When you expect all or most of |
| 55 |
your data to conform to a particular structure and want to get real work done |
| 56 |
without JSON's loosey-goosey nature tripping you up. |
| 57 |
|
| 58 |
Serde JSON provides efficient, flexible, safe ways of converting data between |
| 59 |
each of these representations. |
| 60 |
|
| 61 |
## Operating on untyped JSON values |
| 62 |
|
| 63 |
Any valid JSON data can be manipulated in the following recursive enum |
| 64 |
representation. This data structure is [`serde_json::Value`][value]. |
| 65 |
|
| 66 |
```rust |
| 67 |
enum Value { |
| 68 |
Null, |
| 69 |
Bool(bool), |
| 70 |
Number(Number), |
| 71 |
String(String), |
| 72 |
Array(Vec<Value>), |
| 73 |
Object(Map<String, Value>), |
| 74 |
} |
| 75 |
``` |
| 76 |
|
| 77 |
A string of JSON data can be parsed into a `serde_json::Value` by the |
| 78 |
[`serde_json::from_str`][from_str] function. There is also |
| 79 |
[`from_slice`][from_slice] for parsing from a byte slice `&[u8]` and |
| 80 |
[`from_reader`][from_reader] for parsing from any `io::Read` like a File or a |
| 81 |
TCP stream. |
| 82 |
|
| 83 |
<div align="right"> |
| 84 |
<a href="https://play.rust-lang.org/?edition=2018&gist=d69d8e3156d4bb81c4461b60b772ab72" target="_blank"> |
| 85 |
<img align="center" width="85" src="https://raw.githubusercontent.com/serde-rs/serde-rs.github.io/master/img/runtab.png"> |
| 86 |
</a> |
| 87 |
</div> |
| 88 |
|
| 89 |
```rust |
| 90 |
use serde_json::{Result, Value}; |
| 91 |
|
| 92 |
fn untyped_example() -> Result<()> { |
| 93 |
// Some JSON input data as a &str. Maybe this comes from the user. |
| 94 |
let data = r#" |
| 95 |
{ |
| 96 |
"name": "John Doe", |
| 97 |
"age": 43, |
| 98 |
"phones": [ |
| 99 |
"+44 1234567", |
| 100 |
"+44 2345678" |
| 101 |
] |
| 102 |
}"#; |
| 103 |
|
| 104 |
// Parse the string of data into serde_json::Value. |
| 105 |
let v: Value = serde_json::from_str(data)?; |
| 106 |
|
| 107 |
// Access parts of the data by indexing with square brackets. |
| 108 |
println!("Please call {} at the number {}", v["name"], v["phones"][0]); |
| 109 |
|
| 110 |
Ok(()) |
| 111 |
} |
| 112 |
``` |
| 113 |
|
| 114 |
The result of square bracket indexing like `v["name"]` is a borrow of the data |
| 115 |
at that index, so the type is `&Value`. A JSON map can be indexed with string |
| 116 |
keys, while a JSON array can be indexed with integer keys. If the type of the |
| 117 |
data is not right for the type with which it is being indexed, or if a map does |
| 118 |
not contain the key being indexed, or if the index into a vector is out of |
| 119 |
bounds, the returned element is `Value::Null`. |
| 120 |
|
| 121 |
When a `Value` is printed, it is printed as a JSON string. So in the code above, |
| 122 |
the output looks like `Please call "John Doe" at the number "+44 1234567"`. The |
| 123 |
quotation marks appear because `v["name"]` is a `&Value` containing a JSON |
| 124 |
string and its JSON representation is `"John Doe"`. Printing as a plain string |
| 125 |
without quotation marks involves converting from a JSON string to a Rust string |
| 126 |
with [`as_str()`] or avoiding the use of `Value` as described in the following |
| 127 |
section. |
| 128 |
|
| 129 |
[`as_str()`]: https://docs.rs/serde_json/1/serde_json/enum.Value.html#method.as_str |
| 130 |
|
| 131 |
The `Value` representation is sufficient for very basic tasks but can be tedious |
| 132 |
to work with for anything more significant. Error handling is verbose to |
| 133 |
implement correctly, for example imagine trying to detect the presence of |
| 134 |
unrecognized fields in the input data. The compiler is powerless to help you |
| 135 |
when you make a mistake, for example imagine typoing `v["name"]` as `v["nmae"]` |
| 136 |
in one of the dozens of places it is used in your code. |
| 137 |
|
| 138 |
## Parsing JSON as strongly typed data structures |
| 139 |
|
| 140 |
Serde provides a powerful way of mapping JSON data into Rust data structures |
| 141 |
largely automatically. |
| 142 |
|
| 143 |
<div align="right"> |
| 144 |
<a href="https://play.rust-lang.org/?edition=2018&gist=15cfab66d38ff8a15a9cf1d8d897ac68" target="_blank"> |
| 145 |
<img align="center" width="85" src="https://raw.githubusercontent.com/serde-rs/serde-rs.github.io/master/img/runtab.png"> |
| 146 |
</a> |
| 147 |
</div> |
| 148 |
|
| 149 |
```rust |
| 150 |
use serde::{Deserialize, Serialize}; |
| 151 |
use serde_json::Result; |
| 152 |
|
| 153 |
#[derive(Serialize, Deserialize)] |
| 154 |
struct Person { |
| 155 |
name: String, |
| 156 |
age: u8, |
| 157 |
phones: Vec<String>, |
| 158 |
} |
| 159 |
|
| 160 |
fn typed_example() -> Result<()> { |
| 161 |
// Some JSON input data as a &str. Maybe this comes from the user. |
| 162 |
let data = r#" |
| 163 |
{ |
| 164 |
"name": "John Doe", |
| 165 |
"age": 43, |
| 166 |
"phones": [ |
| 167 |
"+44 1234567", |
| 168 |
"+44 2345678" |
| 169 |
] |
| 170 |
}"#; |
| 171 |
|
| 172 |
// Parse the string of data into a Person object. This is exactly the |
| 173 |
// same function as the one that produced serde_json::Value above, but |
| 174 |
// now we are asking it for a Person as output. |
| 175 |
let p: Person = serde_json::from_str(data)?; |
| 176 |
|
| 177 |
// Do things just like with any other Rust data structure. |
| 178 |
println!("Please call {} at the number {}", p.name, p.phones[0]); |
| 179 |
|
| 180 |
Ok(()) |
| 181 |
} |
| 182 |
``` |
| 183 |
|
| 184 |
This is the same `serde_json::from_str` function as before, but this time we |
| 185 |
assign the return value to a variable of type `Person` so Serde will |
| 186 |
automatically interpret the input data as a `Person` and produce informative |
| 187 |
error messages if the layout does not conform to what a `Person` is expected to |
| 188 |
look like. |
| 189 |
|
| 190 |
Any type that implements Serde's `Deserialize` trait can be deserialized this |
| 191 |
way. This includes built-in Rust standard library types like `Vec<T>` and |
| 192 |
`HashMap<K, V>`, as well as any structs or enums annotated with |
| 193 |
`#[derive(Deserialize)]`. |
| 194 |
|
| 195 |
Once we have `p` of type `Person`, our IDE and the Rust compiler can help us use |
| 196 |
it correctly like they do for any other Rust code. The IDE can autocomplete |
| 197 |
field names to prevent typos, which was impossible in the `serde_json::Value` |
| 198 |
representation. And the Rust compiler can check that when we write |
| 199 |
`p.phones[0]`, then `p.phones` is guaranteed to be a `Vec<String>` so indexing |
| 200 |
into it makes sense and produces a `String`. |
| 201 |
|
| 202 |
The necessary setup for using Serde's derive macros is explained on the *[Using |
| 203 |
derive]* page of the Serde site. |
| 204 |
|
| 205 |
[Using derive]: https://serde.rs/derive.html |
| 206 |
|
| 207 |
## Constructing JSON values |
| 208 |
|
| 209 |
Serde JSON provides a [`json!` macro][macro] to build `serde_json::Value` |
| 210 |
objects with very natural JSON syntax. |
| 211 |
|
| 212 |
<div align="right"> |
| 213 |
<a href="https://play.rust-lang.org/?edition=2018&gist=6ccafad431d72b62e77cc34c8e879b24" target="_blank"> |
| 214 |
<img align="center" width="85" src="https://raw.githubusercontent.com/serde-rs/serde-rs.github.io/master/img/runtab.png"> |
| 215 |
</a> |
| 216 |
</div> |
| 217 |
|
| 218 |
```rust |
| 219 |
use serde_json::json; |
| 220 |
|
| 221 |
fn main() { |
| 222 |
// The type of `john` is `serde_json::Value` |
| 223 |
let john = json!({ |
| 224 |
"name": "John Doe", |
| 225 |
"age": 43, |
| 226 |
"phones": [ |
| 227 |
"+44 1234567", |
| 228 |
"+44 2345678" |
| 229 |
] |
| 230 |
}); |
| 231 |
|
| 232 |
println!("first phone number: {}", john["phones"][0]); |
| 233 |
|
| 234 |
// Convert to a string of JSON and print it out |
| 235 |
println!("{}", john.to_string()); |
| 236 |
} |
| 237 |
``` |
| 238 |
|
| 239 |
The `Value::to_string()` function converts a `serde_json::Value` into a `String` |
| 240 |
of JSON text. |
| 241 |
|
| 242 |
One neat thing about the `json!` macro is that variables and expressions can be |
| 243 |
interpolated directly into the JSON value as you are building it. Serde will |
| 244 |
check at compile time that the value you are interpolating is able to be |
| 245 |
represented as JSON. |
| 246 |
|
| 247 |
<div align="right"> |
| 248 |
<a href="https://play.rust-lang.org/?edition=2018&gist=f9101a6e61dfc9e02c6a67f315ed24f2" target="_blank"> |
| 249 |
<img align="center" width="85" src="https://raw.githubusercontent.com/serde-rs/serde-rs.github.io/master/img/runtab.png"> |
| 250 |
</a> |
| 251 |
</div> |
| 252 |
|
| 253 |
```rust |
| 254 |
let full_name = "John Doe"; |
| 255 |
let age_last_year = 42; |
| 256 |
|
| 257 |
// The type of `john` is `serde_json::Value` |
| 258 |
let john = json!({ |
| 259 |
"name": full_name, |
| 260 |
"age": age_last_year + 1, |
| 261 |
"phones": [ |
| 262 |
format!("+44 {}", random_phone()) |
| 263 |
] |
| 264 |
}); |
| 265 |
``` |
| 266 |
|
| 267 |
This is amazingly convenient, but we have the problem we had before with |
| 268 |
`Value`: the IDE and Rust compiler cannot help us if we get it wrong. Serde JSON |
| 269 |
provides a better way of serializing strongly-typed data structures into JSON |
| 270 |
text. |
| 271 |
|
| 272 |
## Creating JSON by serializing data structures |
| 273 |
|
| 274 |
A data structure can be converted to a JSON string by |
| 275 |
[`serde_json::to_string`][to_string]. There is also |
| 276 |
[`serde_json::to_vec`][to_vec] which serializes to a `Vec<u8>` and |
| 277 |
[`serde_json::to_writer`][to_writer] which serializes to any `io::Write` |
| 278 |
such as a File or a TCP stream. |
| 279 |
|
| 280 |
<div align="right"> |
| 281 |
<a href="https://play.rust-lang.org/?edition=2018&gist=3472242a08ed2ff88a944f2a2283b0ee" target="_blank"> |
| 282 |
<img align="center" width="85" src="https://raw.githubusercontent.com/serde-rs/serde-rs.github.io/master/img/runtab.png"> |
| 283 |
</a> |
| 284 |
</div> |
| 285 |
|
| 286 |
```rust |
| 287 |
use serde::{Deserialize, Serialize}; |
| 288 |
use serde_json::Result; |
| 289 |
|
| 290 |
#[derive(Serialize, Deserialize)] |
| 291 |
struct Address { |
| 292 |
street: String, |
| 293 |
city: String, |
| 294 |
} |
| 295 |
|
| 296 |
fn print_an_address() -> Result<()> { |
| 297 |
// Some data structure. |
| 298 |
let address = Address { |
| 299 |
street: "10 Downing Street".to_owned(), |
| 300 |
city: "London".to_owned(), |
| 301 |
}; |
| 302 |
|
| 303 |
// Serialize it to a JSON string. |
| 304 |
let j = serde_json::to_string(&address)?; |
| 305 |
|
| 306 |
// Print, write to a file, or send to an HTTP server. |
| 307 |
println!("{}", j); |
| 308 |
|
| 309 |
Ok(()) |
| 310 |
} |
| 311 |
``` |
| 312 |
|
| 313 |
Any type that implements Serde's `Serialize` trait can be serialized this way. |
| 314 |
This includes built-in Rust standard library types like `Vec<T>` and `HashMap<K, |
| 315 |
V>`, as well as any structs or enums annotated with `#[derive(Serialize)]`. |
| 316 |
|
| 317 |
## Performance |
| 318 |
|
| 319 |
It is fast. You should expect in the ballpark of 500 to 1000 megabytes per |
| 320 |
second deserialization and 600 to 900 megabytes per second serialization, |
| 321 |
depending on the characteristics of your data. This is competitive with the |
| 322 |
fastest C and C++ JSON libraries or even 30% faster for many use cases. |
| 323 |
Benchmarks live in the [serde-rs/json-benchmark] repo. |
| 324 |
|
| 325 |
[serde-rs/json-benchmark]: https://github.com/serde-rs/json-benchmark |
| 326 |
|
| 327 |
## Getting help |
| 328 |
|
| 329 |
Serde is one of the most widely used Rust libraries, so any place that |
| 330 |
Rustaceans congregate will be able to help you out. For chat, consider trying |
| 331 |
the [#rust-questions] or [#rust-beginners] channels of the unofficial community |
| 332 |
Discord (invite: <https://discord.gg/rust-lang-community>), the [#rust-usage] or |
| 333 |
[#beginners] channels of the official Rust Project Discord (invite: |
| 334 |
<https://discord.gg/rust-lang>), or the [#general][zulip] stream in Zulip. For |
| 335 |
asynchronous, consider the [\[rust\] tag on StackOverflow][stackoverflow], the |
| 336 |
[/r/rust] subreddit which has a pinned weekly easy questions post, or the Rust |
| 337 |
[Discourse forum][discourse]. It's acceptable to file a support issue in this |
| 338 |
repo, but they tend not to get as many eyes as any of the above and may get |
| 339 |
closed without a response after some time. |
| 340 |
|
| 341 |
[#rust-questions]: https://discord.com/channels/273534239310479360/274215136414400513 |
| 342 |
[#rust-beginners]: https://discord.com/channels/273534239310479360/273541522815713281 |
| 343 |
[#rust-usage]: https://discord.com/channels/442252698964721669/443150878111694848 |
| 344 |
[#beginners]: https://discord.com/channels/442252698964721669/448238009733742612 |
| 345 |
[zulip]: https://rust-lang.zulipchat.com/#narrow/stream/122651-general |
| 346 |
[stackoverflow]: https://stackoverflow.com/questions/tagged/rust |
| 347 |
[/r/rust]: https://www.reddit.com/r/rust |
| 348 |
[discourse]: https://users.rust-lang.org |
| 349 |
|
| 350 |
## No-std support |
| 351 |
|
| 352 |
As long as there is a memory allocator, it is possible to use serde_json without |
| 353 |
the rest of the Rust standard library. Disable the default "std" feature and |
| 354 |
enable the "alloc" feature: |
| 355 |
|
| 356 |
```toml |
| 357 |
[dependencies] |
| 358 |
serde_json = { version = "1.0", default-features = false, features = ["alloc"] } |
| 359 |
``` |
| 360 |
|
| 361 |
For JSON support in Serde without a memory allocator, please see the |
| 362 |
[`serde-json-core`] crate. |
| 363 |
|
| 364 |
[`serde-json-core`]: https://github.com/rust-embedded-community/serde-json-core |
| 365 |
|
| 366 |
[value]: https://docs.rs/serde_json/1/serde_json/value/enum.Value.html |
| 367 |
[from_str]: https://docs.rs/serde_json/1/serde_json/de/fn.from_str.html |
| 368 |
[from_slice]: https://docs.rs/serde_json/1/serde_json/de/fn.from_slice.html |
| 369 |
[from_reader]: https://docs.rs/serde_json/1/serde_json/de/fn.from_reader.html |
| 370 |
[to_string]: https://docs.rs/serde_json/1/serde_json/ser/fn.to_string.html |
| 371 |
[to_vec]: https://docs.rs/serde_json/1/serde_json/ser/fn.to_vec.html |
| 372 |
[to_writer]: https://docs.rs/serde_json/1/serde_json/ser/fn.to_writer.html |
| 373 |
[macro]: https://docs.rs/serde_json/1/serde_json/macro.json.html |
| 374 |
|
| 375 |
<br> |
| 376 |
|
| 377 |
#### License |
| 378 |
|
| 379 |
<sup> |
| 380 |
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version |
| 381 |
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. |
| 382 |
</sup> |
| 383 |
|
| 384 |
<br> |
| 385 |
|
| 386 |
<sub> |
| 387 |
Unless you explicitly state otherwise, any contribution intentionally submitted |
| 388 |
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall |
| 389 |
be dual licensed as above, without any additional terms or conditions. |
| 390 |
</sub> |