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