1 # Serde JSON   [![Build Status]][travis] [![Latest Version]][crates.io] [![Rustc Version 1.36+]][rustc]
3 [Build Status]: https://img.shields.io/github/workflow/status/serde-rs/json/CI/master
4 [travis]: 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
10 **Serde is a framework for *ser*ializing and *de*serializing Rust data structures efficiently and generically.**
19 You may be looking for:
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/derive.html)
25 - [Release notes](https://github.com/serde-rs/json/releases)
27 JSON is a ubiquitous open-standard format that uses human-readable text to
28 transmit data objects consisting of key-value pairs.
35 "street": "10 Downing Street",
45 There are three common ways that you might find yourself needing to work with
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.
58 Serde JSON provides efficient, flexible, safe ways of converting data between
59 each of these representations.
61 ## Operating on untyped JSON values
63 Any valid JSON data can be manipulated in the following recursive enum
64 representation. This data structure is [`serde_json::Value`][value].
73 Object(Map<String, Value>),
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
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">
90 use serde_json::{Result, Value};
92 fn untyped_example() -> Result<()> {
93 // Some JSON input data as a &str. Maybe this comes from the user.
104 // Parse the string of data into serde_json::Value.
105 let v: Value = serde_json::from_str(data)?;
107 // Access parts of the data by indexing with square brackets.
108 println!("Please call {} at the number {}", v["name"], v["phones"][0]);
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`.
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
129 [`as_str()`]: https://docs.serde.rs/serde_json/enum.Value.html#method.as_str
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.
138 ## Parsing JSON as strongly typed data structures
140 Serde provides a powerful way of mapping JSON data into Rust data structures
141 largely automatically.
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">
150 use serde::{Deserialize, Serialize};
151 use serde_json::Result;
153 #[derive(Serialize, Deserialize)]
160 fn typed_example() -> Result<()> {
161 // Some JSON input data as a &str. Maybe this comes from the user.
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)?;
177 // Do things just like with any other Rust data structure.
178 println!("Please call {} at the number {}", p.name, p.phones[0]);
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
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)]`.
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`.
202 The necessary setup for using Serde's derive macros is explained on the *[Using
203 derive]* page of the Serde site.
205 [Using derive]: https://serde.rs/derive.html
207 ## Constructing JSON values
209 Serde JSON provides a [`json!` macro][macro] to build `serde_json::Value`
210 objects with very natural JSON syntax.
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">
219 use serde_json::json;
222 // The type of `john` is `serde_json::Value`
232 println!("first phone number: {}", john["phones"][0]);
234 // Convert to a string of JSON and print it out
235 println!("{}", john.to_string());
239 The `Value::to_string()` function converts a `serde_json::Value` into a `String`
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
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">
254 let full_name = "John Doe";
255 let age_last_year = 42;
257 // The type of `john` is `serde_json::Value`
260 "age": age_last_year + 1,
262 format!("+44 {}", random_phone())
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
272 ## Creating JSON by serializing data structures
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.
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">
287 use serde::{Deserialize, Serialize};
288 use serde_json::Result;
290 #[derive(Serialize, Deserialize)]
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(),
303 // Serialize it to a JSON string.
304 let j = serde_json::to_string(&address)?;
306 // Print, write to a file, or send to an HTTP server.
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)]`.
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.
325 [serde-rs/json-benchmark]: https://github.com/serde-rs/json-benchmark
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.
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
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. This is supported on Rust 1.36+. Disable
354 the default "std" feature and enable the "alloc" feature:
358 serde_json = { version = "1.0", default-features = false, features = ["alloc"] }
361 For JSON support in Serde without a memory allocator, please see the
362 [`serde-json-core`] crate.
364 [`serde-json-core`]: https://github.com/rust-embedded-community/serde-json-core
366 [value]: https://docs.serde.rs/serde_json/value/enum.Value.html
367 [from_str]: https://docs.serde.rs/serde_json/de/fn.from_str.html
368 [from_slice]: https://docs.serde.rs/serde_json/de/fn.from_slice.html
369 [from_reader]: https://docs.serde.rs/serde_json/de/fn.from_reader.html
370 [to_string]: https://docs.serde.rs/serde_json/ser/fn.to_string.html
371 [to_vec]: https://docs.serde.rs/serde_json/ser/fn.to_vec.html
372 [to_writer]: https://docs.serde.rs/serde_json/ser/fn.to_writer.html
373 [macro]: https://docs.serde.rs/serde_json/macro.json.html
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.
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.