Repository: graphql-rust/juniper (language: rust)

Issue:
Documentation on how to use `LookAhead*` features. 
I saw that support for look ahead functionality was added in #136, but I'm a bit confused as to how to use it since it's not at all documented. I see they are exported [here](https://github.com/graphql-rust/juniper/blob/56f71e934be814722d10b0660156cf56b3753470/juniper/src/lib.rs#L155), but attempting to use them throws a compiler error:

```
error[E0432]: unresolved import `juniper::LookAheadArgument`
 --> src/schema.rs:4:5
  |
4 | use juniper::LookAheadArgument;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^ no `LookAheadArgument` in the root
warning: unused import: `juniper::LookAheadArgument`
 --> src/schema.rs:4:5
  |
4 | use juniper::LookAheadArgument;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: #[warn(unused_imports)] on by default
```

Any help here would be greatly appreciated, thanks!


Discussion / hints:
/cc @weiznich
I think the released version on crates.io does not contain that feature yet. So to make this work you need to dependent directly on the git version.
Oh, yes, sorry...I should have read closer. You need to use master/git until a new release (https://github.com/graphql-rust/juniper/issues/210). Sadly I can't do a release because I don't have permissions and @theduke and @mhallin haven't been around lately.

It would still be good to get some docs on how to actually use it in the book so keeping this open.
Ah I see, I suspected as much, thanks!

Out of curiosity are these the main way people are recommended to tackle the N+1 query problem? I find that even in the most simple case it gets pretty chatty and haven't been able to find much guidance on that in particular. (Well other than using dataloader-rs, which I believe requires async support to work?)
There are basically 2 ways to solve the N+1 query problem:
* Using something like dataloader
* Using a lookahead mechanism to inspect the whole query

The first solution won't work with juniper as implemented currently, because it needs async support, so this leaves currently only the lookahead solution.

(Btw: If you are trying to integrate juniper with a relational database checkout [wundergraph](https://github.com/weiznich/wundergraph))
This discussion may also be of use:

https://github.com/graphql-rust/juniper/issues/124
Yup that's what alerted me to wundergraph's existence 😄. During my first pass through I found it a bit hard to grok, but I haven't set some time aside to really dig into it so I'll do that and report back.
> I guess if we define these types in juniper consumers of the lib aren't forced to use them. They could just use the default Int and Float types and it would be as if they were never added.

Writing documentation is a big point of what's left before wundergraph will be released officially. For now the two examples are the only documentation that exists beside the code.
@weiznich: While it isn't as complete as facebook's GraphQL dataloader, at work we've got a pretty decent to solution to handle batching of nested objects.

-------------------------------------------------------------------------------------

Our solution to handle nested objects is to wrap our `RealObject` in a new struct:

```
struct BatchedObject { id: Id, batch: Rc<MultipleObjectDataWithLazyRefCells> }
```

and then load the data out of the Rc in the `field blah() -> { self.batch.get_blah(&self.id) }`.

Here is a gist with part of the bits you might use https://gist.github.com/kestred/6cac1149b072228bd398e2c60e3c7871.

The gist example is fairly unusual, because all of our typical batching has been replaced a `graphql_batch!` macro which hides most of the noise.
Would anyone, please, mind to show a basic example of how this works? I am not a Rust begginer, but neither a pro... And I could not get any cue from the wundergraph project :(
The basic idea is quite simple:
 You call [`Executor::look_ahead()`](https://docs.rs/juniper/0.10.0/juniper/struct.Executor.html#method.look_ahead) to get a [`LookAheadSelection`](https://docs.rs/juniper/0.10.0/juniper/struct.LookAheadSelection.html). That's basically just a structure that represents the whole request. After that you can use the methods provided by [`LookAheadMethods`](https://docs.rs/juniper/0.10.0/juniper/trait.LookAheadMethods.html) to traverse the request tree. How you do that and what you do with the result depends quite a lot on your exact use case. For wundergraph this is used to construct sql queries.

@LegNeato I think this could be closed because the documentation was released.
@weiznich Thanks, but should this `Executor::look_ahead()` call be made inside an object field code?
What happens if I return e.g. Books with Authors from the `books` field? Will Juniper execute the code for Book.Author for each book anyway?
A simple pseudo code implementation would look like this:

```rust
struct Query;

#[derive(GraphQLObject)]
struct User { 
    id: String,
    posts: Vec<Post>,
}

impl User {
    fn from_lookahead(selection: LookAheadSelection) -> Self {
        // do something with the selection here
    }
}

#[derive(GraphQLObject)]
struct Post {
    id: String,
    content: String,
}

graphql_object!(Query: () |&self| {
    field user(&executor) -> User {
        let lookahead = executor.look_ahead();
        User::from_lookahead(lookahead)
    }
});
```
@weiznich Thank you very much for the effort. But could you please clarify on this?
If I make the following query:
```
{
   users   {
      id,
      name,
      posts      {
         id,
         name
      }
   }
}
```

So, if I return the users, along with the posts, in the `field users`, will Juniper continue traversing the graph? Or I must remove the rest of the graph in the lookahead?

Thank you very much for your time!
That depends on the exact implementation. In the example above juniper will continue to traverse the graph. In detail because of the derives it will just select the right fields from the response. If `GrapQLType` is manually implemented (or by using `graphql_object!`) for `Users` a other behaviour is possible.
In wundergraph I let do juniper the exact field resolution, but look for nested fields (in this case posts) and load them only if they are requested.
Thanks @weiznich I'll try to use your wishdom to implement it when I got home. BTW, you said that the documentation was released. Where has this been done?

Thank you very much!
Basically the api documentation [here](https://docs.rs/juniper/0.10.0/juniper/struct.Executor.html#method.look_ahead) and for all other lookahead related types. 
At the time this issue was opened those documentation did not exist.
Circling back around on this; the example in https://github.com/graphql-rust/juniper/issues/234#issuecomment-438217910 no longer compiles because `LookAheadSelection` and `LookAheadMethods` are generic, but I don't quite understand what they are generic over and how I am supposed to use them.  I'd happily send a PR adding docs if I could figure out how to work it.
It's generic over the lifetime and the scalar type, which will be `juniper::DefaultScalarValue`, unless you customize it.

Fix patch:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5d06ab4a8..b91a9c424 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -404,7 +404,7 @@ jobs:
   deploy-book:
     name: deploy (Book)
     if: ${{ github.ref == 'refs/heads/master'
-         || startsWith(github.ref, 'refs/tags/juniper@') }}
+         || startsWith(github.ref, 'refs/tags/juniper') }}
     needs: ["codespell", "test", "test-book"]
     runs-on: ubuntu-latest
     steps:
diff --git a/README.md b/README.md
index b10a67871..3f8f41008 100644
--- a/README.md
+++ b/README.md
@@ -108,10 +108,10 @@ Juniper has not reached 1.0 yet, thus some API instability should be expected.
 [rocket_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket/examples
 [hyper]: https://hyper.rs
 [rocket]: https://rocket.rs
-[book]: https://graphql-rust.github.io
+[book]: https://graphql-rust.github.io/juniper
 [book_master]: https://graphql-rust.github.io/juniper/master
-[book_index]: https://graphql-rust.github.io
-[book_quickstart]: https://graphql-rust.github.io/quickstart.html
+[book_index]: https://graphql-rust.github.io/juniper
+[book_quickstart]: https://graphql-rust.github.io/juniper/quickstart.html
 [docsrs]: https://docs.rs/juniper
 [warp]: https://github.com/seanmonstar/warp
 [warp_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp/examples
diff --git a/benches/Cargo.toml b/benches/Cargo.toml
index edb6b729a..b3ad64def 100644
--- a/benches/Cargo.toml
+++ b/benches/Cargo.toml
@@ -6,6 +6,7 @@ authors = ["Christoph Herzog <chris@theduke.at>"]
 publish = false
 
 [dependencies]
+dataloader = "0.17" # for Book only
 futures = "0.3"
 juniper = { path = "../juniper" }
 
diff --git a/book/book.toml b/book/book.toml
index 9dad3932f..08f4bb6a4 100644
--- a/book/book.toml
+++ b/book/book.toml
@@ -1,8 +1,11 @@
 [book]
-title = "Juniper Book (GraphQL server for Rust)"
+title = "Juniper Book"
 description = "User guide for Juniper (GraphQL server library for Rust)."
 language = "en"
 multilingual = false
+authors = [
+    "Kai Ren (@tyranron)",
+]
 src = "src"
 
 [build]
@@ -10,7 +13,7 @@ build-dir = "_rendered"
 create-missing = false
 
 [output.html]
-git_repository_url = "https://github.com/graphql-rs/juniper"
+git_repository_url = "https://github.com/graphql-rust/juniper"
 
 [rust]
 edition = "2021"
diff --git a/book/src/README.md b/book/src/README.md
deleted file mode 100644
index 0b0692b1c..000000000
--- a/book/src/README.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Juniper
-
-Juniper is a [GraphQL] server library for Rust. Build type-safe and fast API
-servers with minimal boilerplate and configuration.
-
-[GraphQL][graphql] is a data query language developed by Facebook intended to
-serve mobile and web application frontends.
-
-_Juniper_ makes it possible to write GraphQL servers in Rust that are
-type-safe and blazingly fast. We also try to make declaring and resolving
-GraphQL schemas as convenient as possible as Rust will allow.
-
-Juniper does not include a web server - instead it provides building blocks to
-make integration with existing servers straightforward. It optionally provides a
-pre-built integration for the [Hyper][hyper], [Rocket], and [Warp][warp] frameworks, including
-embedded [Graphiql][graphiql] for easy debugging.
-
-- [Cargo crate](https://crates.io/crates/juniper)
-- [API Reference][docsrs]
-
-## Features
-
-Juniper supports the full GraphQL query language according to the
-[specification (October 2021)][graphql_spec], including interfaces, unions, schema
-introspection, and validations.
-It does not, however, support the schema language.
-
-As an exception to other GraphQL libraries for other languages, Juniper builds
-non-null types by default. A field of type `Vec<Episode>` will be converted into
-`[Episode!]!`. The corresponding Rust type for e.g. `[Episode]` would be
-`Option<Vec<Option<Episode>>>`.
-
-## Integrations
-
-### Data types
-
-Juniper has automatic integration with some very common Rust crates to make
-building schemas a breeze. The types from these crates will be usable in
-your Schemas automatically.
-
-- [uuid][uuid]
-- [url][url]
-- [chrono][chrono]
-- [bson][bson]
-
-### Web Frameworks
-
-- [hyper][hyper]
-- [rocket][rocket]
-- [warp][warp]
-
-## API Stability
-
-Juniper has not reached 1.0 yet, thus some API instability should be expected.
-
-[graphql]: http://graphql.org
-[graphiql]: https://github.com/graphql/graphiql
-[graphql_spec]: https://spec.graphql.org/October2021
-[test_schema_rs]: https://github.com/graphql-rust/juniper/blob/master/juniper/src/tests/schema.rs
-[tokio]: https://github.com/tokio-rs/tokio
-[hyper_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_hyper/examples
-[rocket_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket/examples
-[hyper]: https://hyper.rs
-[rocket]: https://rocket.rs
-[book]: https://graphql-rust.github.io
-[book_quickstart]: https://graphql-rust.github.io/quickstart.html
-[docsrs]: https://docs.rs/juniper
-[warp]: https://github.com/seanmonstar/warp
-[warp_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp/examples
-[uuid]: https://crates.io/crates/uuid
-[url]: https://crates.io/crates/url
-[chrono]: https://crates.io/crates/chrono
-[bson]: https://crates.io/crates/bson
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index eb4013ae9..4caea6af8 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -1,39 +1,28 @@
-- [Introduction](README.md)
-- [Quickstart](quickstart.md)
-
-- [Type System](types/index.md)
+# Summary
 
-  - [Defining objects](types/objects/defining_objects.md)
-    - [Complex fields](types/objects/complex_fields.md)
-    - [Using contexts](types/objects/using_contexts.md)
-    - [Error handling](types/objects/error_handling.md)
-  - [Other types](types/other-index.md)
-    - [Enums](types/enums.md)
+- [Introduction](introduction.md)
+- [Quickstart](quickstart.md)
+- [Type system](types/index.md)
+    - [Objects](types/objects/index.md)
+        - [Complex fields](types/objects/complex_fields.md)
+        - [Context](types/objects/context.md)
+        - [Error handling](types/objects/error/index.md)
+            - [Field errors](types/objects/error/field.md) 
+            - [Schema errors](types/objects/error/schema.md) 
+        - [Generics](types/objects/generics.md)
     - [Interfaces](types/interfaces.md)
+    - [Unions](types/unions.md)
+    - [Enums](types/enums.md)
     - [Input objects](types/input_objects.md)
     - [Scalars](types/scalars.md)
-    - [Unions](types/unions.md)
-
-- [Schemas and mutations](schema/schemas_and_mutations.md)
-
-- [Adding A Server](servers/index.md)
-
-  - [Official Server Integrations](servers/official.md) - [Hyper](servers/hyper.md)
-    - [Warp](servers/warp.md)
-    - [Rocket](servers/rocket.md)
-    - [Hyper](servers/hyper.md)
-  - [Third Party Integrations](servers/third-party.md)
-
+- [Schema](schema/index.md)
+    - [Subscriptions](schema/subscriptions.md)
+    - [Introspection](schema/introspection.md)
+- [Serving](serve/index.md)
+    - [Batching](serve/batching.md)
 - [Advanced Topics](advanced/index.md)
-
-  - [Introspection](advanced/introspection.md)
-  - [Non-struct objects](advanced/non_struct_objects.md)
-  - [Implicit and explicit null](advanced/implicit_and_explicit_null.md)
-  - [Objects and generics](advanced/objects_and_generics.md)
-  - [Multiple operations per request](advanced/multiple_ops_per_request.md)
-  - [Dataloaders](advanced/dataloaders.md)
-  - [Subscriptions](advanced/subscriptions.md)
-
-    # - [Context switching]
-
-    # - [Dynamic type system]
+    - [Implicit and explicit `null`](advanced/implicit_and_explicit_null.md)
+    - [N+1 problem](advanced/n_plus_1.md)
+        - [DataLoader](advanced/dataloader.md)
+        - [Look-ahead](advanced/lookahead.md)
+            - [Eager loading](advanced/eager_loading.md)
diff --git a/book/src/advanced/dataloader.md b/book/src/advanced/dataloader.md
new file mode 100644
index 000000000..274f70025
--- /dev/null
+++ b/book/src/advanced/dataloader.md
@@ -0,0 +1,198 @@
+DataLoader
+==========
+
+DataLoader pattern, named after the correspondent [`dataloader` NPM package][0], represents a mechanism of  batching and caching data requests in a delayed manner for solving the [N+1 problem](n_plus_1.md).
+
+> A port of the "Loader" API originally developed by [@schrockn] at Facebook in 2010 as a simplifying force to coalesce the sundry key-value store back-end APIs which existed at the time. At Facebook, "Loader" became one of the implementation details of the "Ent" framework, a privacy-aware data entity loading and caching layer within web server product code. This ultimately became the underpinning for Facebook's GraphQL server implementation and type definitions.
+
+In [Rust] ecosystem, DataLoader pattern is introduced with the [`dataloader` crate][1], naturally usable with [Juniper].
+
+Let's remake our [example of N+1 problem](n_plus_1.md), so it's solved by applying the DataLoader pattern:
+```rust
+# extern crate anyhow;
+# extern crate dataloader;
+# extern crate juniper;
+# use std::{collections::HashMap, sync::Arc};
+# use anyhow::anyhow;
+# use dataloader::non_cached::Loader;
+# use juniper::{graphql_object, GraphQLObject};
+#
+# type CultId = i32;
+# type UserId = i32;
+#
+# struct Repository;
+#
+# impl Repository {
+#     async fn load_cults_by_ids(&self, cult_ids: &[CultId]) -> anyhow::Result<HashMap<CultId, Cult>> { unimplemented!() }
+#     async fn load_all_persons(&self) -> anyhow::Result<Vec<Person>> { unimplemented!() }
+# }
+#
+struct Context {
+    repo: Repository,
+    cult_loader: CultLoader,
+}
+
+impl juniper::Context for Context {}
+
+#[derive(Clone, GraphQLObject)]
+struct Cult {
+    id: CultId,
+    name: String,
+}
+
+struct CultBatcher {
+    repo: Repository,
+}
+
+// Since `BatchFn` doesn't provide any notion of fallible loading, like 
+// `try_load()` returning `Result<HashMap<K, V>, E>`, we handle possible
+// errors as loaded values and unpack them later in the resolver.
+impl dataloader::BatchFn<CultId, Result<Cult, Arc<anyhow::Error>>> for CultBatcher {
+    async fn load(
+        &mut self, 
+        cult_ids: &[CultId],
+    ) -> HashMap<CultId, Result<Cult, Arc<anyhow::Error>>> {
+        // Effectively performs the following SQL query:
+        // SELECT id, name FROM cults WHERE id IN (${cult_id1}, ${cult_id2}, ...)
+        match self.repo.load_cults_by_ids(cult_ids).await {
+            Ok(found_cults) => {
+                found_cults.into_iter().map(|(id, cult)| (id, Ok(cult))).collect()
+            }
+            // One could choose a different strategy to deal with fallible loads,
+            // like consider values that failed to load as absent, or just panic.
+            // See cksac/dataloader-rs#35 for details:
+            // https://github.com/cksac/dataloader-rs/issues/35
+            Err(e) => {
+                // Since `anyhow::Error` doesn't implement `Clone`, we have to
+                // work around here.
+                let e = Arc::new(e);
+                cult_ids.iter().map(|k| (k.clone(), Err(e.clone()))).collect()
+            }
+        }
+    }
+}
+
+type CultLoader = Loader<CultId, Result<Cult, Arc<anyhow::Error>>, CultBatcher>;
+
+fn new_cult_loader(repo: Repository) -> CultLoader {
+    CultLoader::new(CultBatcher { repo })
+        // Usually a `Loader` will coalesce all individual loads which occur 
+        // within a single frame of execution before calling a `BatchFn::load()`
+        // with all the collected keys. However, sometimes this behavior is not
+        // desirable or optimal (perhaps, a request is expected to be spread out
+        // over a few subsequent ticks).
+        // A larger yield count will allow more keys to be appended to the batch,
+        // but will wait longer before the actual load. For more details see:
+        // https://github.com/cksac/dataloader-rs/issues/12 
+        // https://github.com/graphql/dataloader#batch-scheduling
+        .with_yield_count(100)
+}
+
+struct Person {
+    id: UserId,
+    name: String,
+    cult_id: CultId,
+}
+
+#[graphql_object]
+#[graphql(context = Context)]
+impl Person {
+    fn id(&self) -> CultId {
+        self.id
+    }
+    
+    fn name(&self) -> &str {
+        self.name.as_str()
+    }
+    
+    async fn cult(&self, ctx: &Context) -> anyhow::Result<Cult> {
+        ctx.cult_loader
+            // Here, we don't run the `CultBatcher::load()` eagerly, but rather
+            // only register the `self.cult_id` value in the `cult_loader` and
+            // wait for other concurrent resolvers to do the same.
+            // The actual batch loading happens once all the resolvers register 
+            // their IDs and there is nothing more to execute. 
+            .try_load(self.cult_id)
+            .await
+            // The outer error is the `io::Error` returned by `try_load()` if
+            // no value is present in the `HashMap` for the specified 
+            // `self.cult_id`, meaning that there is no `Cult` with such ID
+            // in the `Repository`.
+            .map_err(|_| anyhow!("No cult exists for ID `{}`", self.cult_id))?
+            // The inner error is the one returned by the `CultBatcher::load()`
+            // if the `Repository::load_cults_by_ids()` fails, meaning that
+            // running the SQL query failed.
+            .map_err(|arc_err| anyhow!("{arc_err}"))
+    }
+}
+
+struct Query;
+
+#[graphql_object]
+#[graphql(context = Context)]
+impl Query {
+    async fn persons(ctx: &Context) -> anyhow::Result<Vec<Person>> {
+        // Effectively performs the following SQL query:
+        // SELECT id, name, cult_id FROM persons
+        ctx.repo.load_all_persons().await
+    }
+}
+
+fn main() {
+    
+}
+```
+
+And now, performing a [GraphQL query which lead to N+1 problem](n_plus_1.md)
+```graphql
+query {
+  persons {
+    id
+    name
+    cult {
+      id
+      name
+    }
+  }
+}
+```
+will lead to efficient [SQL] queries, just as expected:
+```sql
+SELECT id, name, cult_id FROM persons;
+SELECT id, name FROM cults WHERE id IN (1, 2, 3, 4);
+```
+
+
+
+
+## Caching
+
+[`dataloader::cached`] provides a [memoization][2] cache: after `BatchFn::load()` is called once with given keys, the resulting values are cached to eliminate redundant loads.
+
+DataLoader caching does not replace [Redis], [Memcached], or any other shared application-level cache. DataLoader is first and foremost a data loading mechanism, and its cache only serves the purpose of not repeatedly loading the same data [in the context of a single request][3].
+
+> **WARNING**: A DataLoader should be created per-request to avoid risk of bugs where one client is able to load cached/batched data from another client outside its authenticated scope. Creating a DataLoader within an individual resolver will prevent batching from occurring and will nullify any benefits of it.
+
+
+
+
+## Full example
+
+For a full example using DataLoaders in [Juniper] check out the [`jayy-lmao/rust-graphql-docker` repository][4].
+
+
+
+
+[`dataloader::cached`]: https://docs.rs/dataloader/latest/dataloader/cached/index.html
+[@schrockn]: https://github.com/schrockn
+[Juniper]: https://docs.rs/juniper
+[Memcached]: https://memcached.org
+[Redis]: https://redis.io
+[Rust]: https://www.rust-lang.org
+[SQL]: https://en.wikipedia.org/wiki/SQL
+
+[0]: https://github.com/graphql/dataloader
+[1]: https://docs.rs/crate/dataloader
+[2]: https://en.wikipedia.org/wiki/Memoization
+[3]: https://github.com/graphql/dataloader#caching
+[4]: https://github.com/jayy-lmao/rust-graphql-docker
diff --git a/book/src/advanced/dataloaders.md b/book/src/advanced/dataloaders.md
deleted file mode 100644
index 703514c0f..000000000
--- a/book/src/advanced/dataloaders.md
+++ /dev/null
@@ -1,194 +0,0 @@
-# Avoiding the N+1 Problem With Dataloaders
-
-A common issue with graphql servers is how the resolvers query their datasource.
-This issue results in a large number of unnecessary database queries or http requests.
-Say you were wanting to list a bunch of cults people were in
-
-```graphql
-query {
-  persons {
-    id
-    name
-    cult {
-      id
-      name
-    }
-  }
-}
-```
-
-What would be executed by a SQL database would be:
-
-```sql
-SELECT id, name, cult_id FROM persons;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 1;
-SELECT id, name FROM cults WHERE id = 2;
-SELECT id, name FROM cults WHERE id = 2;
-SELECT id, name FROM cults WHERE id = 2;
-# ...
-```
-
-Once the list of users has been returned, a separate query is run to find the cult of each user.
-You can see how this could quickly become a problem.
-
-A common solution to this is to introduce a **dataloader**.
-This can be done with Juniper using the crate [cksac/dataloader-rs](https://github.com/cksac/dataloader-rs), which has two types of dataloaders; cached and non-cached.
-
-#### Cached Loader
-DataLoader provides a memoization cache, after .load() is called once with a given key, the resulting value is cached to eliminate redundant loads.
-
-DataLoader caching does not replace Redis, Memcache, or any other shared application-level cache. DataLoader is first and foremost a data loading mechanism, and its cache only serves the purpose of not repeatedly loading the same data in the context of a single request to your Application. [(read more)](https://github.com/graphql/dataloader#caching)
-
-### What does it look like?
-
-!FILENAME Cargo.toml
-
-```toml
-[dependencies]
-actix-identity = "0.4.0-beta.4"
-actix-rt = "1.0"
-actix-web = "2.0"
-async-trait = "0.1.30"
-dataloader = "0.12.0"
-futures = "0.3"
-juniper = "0.16.0"
-postgres = "0.15.2"
-```
-
-```rust, ignore
-// use dataloader::cached::Loader;
-use dataloader::non_cached::Loader;
-use dataloader::BatchFn;
-use std::collections::HashMap;
-use postgres::{Connection, TlsMode};
-use std::env;
-
-pub fn get_db_conn() -> Connection {
-    let pg_connection_string = env::var("DATABASE_URI").expect("need a db uri");
-    println!("Connecting to {pg_connection_string}");
-    let conn = Connection::connect(&pg_connection_string[..], TlsMode::None).unwrap();
-    println!("Connection is fine");
-    conn
-}
-
-#[derive(Debug, Clone)]
-pub struct Cult {
-  pub id: i32,
-  pub name: String,
-}
-
-pub fn get_cult_by_ids(hashmap: &mut HashMap<i32, Cult>, ids: Vec<i32>) {
-  let conn = get_db_conn();
-  for row in &conn
-    .query("SELECT id, name FROM cults WHERE id = ANY($1)", &[&ids])
-    .unwrap()
-  {
-    let cult = Cult {
-      id: row.get(0),
-      name: row.get(1),
-    };
-    hashmap.insert(cult.id, cult);
-  }
-}
-
-pub struct CultBatcher;
-
-#[async_trait]
-impl BatchFn<i32, Cult> for CultBatcher {
-
-    // A hashmap is used, as we need to return an array which maps each original key to a Cult.
-    async fn load(&self, keys: &[i32]) -> HashMap<i32, Cult> {
-        println!("load cult batch {keys:?}");
-        let mut cult_hashmap = HashMap::new();
-        get_cult_by_ids(&mut cult_hashmap, keys.to_vec());
-        cult_hashmap
-    }
-}
-
-pub type CultLoader = Loader<i32, Cult, CultBatcher>;
-
-// To create a new loader
-pub fn get_loader() -> CultLoader {
-    Loader::new(CultBatcher)
-      // Usually a DataLoader will coalesce all individual loads which occur 
-      // within a single frame of execution before calling your batch function with all requested keys.
-      // However sometimes this behavior is not desirable or optimal. 
-      // Perhaps you expect requests to be spread out over a few subsequent ticks
-      // See: https://github.com/cksac/dataloader-rs/issues/12 
-      // More info: https://github.com/graphql/dataloader#batch-scheduling 
-      // A larger yield count will allow more requests to append to batch but will wait longer before actual load.
-      .with_yield_count(100)
-}
-
-#[juniper::graphql_object(Context = Context)]
-impl Cult {
-  //  your resolvers
-
-  // To call the dataloader 
-  pub async fn cult_by_id(ctx: &Context, id: i32) -> Cult {
-    ctx.cult_loader.load(id).await
-  }
-}
-
-```
-
-### How do I call them?
-
-Once created, a dataloader has the async functions `.load()` and `.load_many()`.
-In the above example `cult_loader.load(id: i32).await` returns `Cult`. If  we had used `cult_loader.load_many(Vec<i32>).await` it would have returned `Vec<Cult>`.
-
-
-### Where do I create my dataloaders?
-
-**Dataloaders** should be created per-request to avoid risk of bugs where one user is able to load cached/batched data from another user/ outside of its authenticated scope.
-Creating dataloaders within individual resolvers will prevent batching from occurring and will nullify the benefits of the dataloader.
-
-For example:
-
-_When you declare your context_
-```rust, ignore
-use juniper;
-
-#[derive(Clone)]
-pub struct Context {
-    pub cult_loader: CultLoader,
-}
-
-impl juniper::Context for Context {}
-
-impl Context {
-    pub fn new(cult_loader: CultLoader) -> Self {
-        Self {
-            cult_loader
-        }
-    }
-}
-```
-
-_Your handler for GraphQL (Note: instantiating context here keeps it per-request)_
-```rust, ignore
-pub async fn graphql(
-    st: web::Data<Arc<Schema>>,
-    data: web::Json<GraphQLRequest>,
-) -> Result<HttpResponse, Error> {
-
-    // Context setup
-    let cult_loader = get_loader();
-    let ctx = Context::new(cult_loader);
-
-    // Execute
-    let res = data.execute(&st, &ctx).await; 
-    let json = serde_json::to_string(&res).map_err(error::ErrorInternalServerError)?;
-
-    Ok(HttpResponse::Ok()
-        .content_type("application/json")
-        .body(json))
-}
-```
-
-### Further Example:
-
-For a full example using Dataloaders and Context check out [jayy-lmao/rust-graphql-docker](https://github.com/jayy-lmao/rust-graphql-docker).
diff --git a/book/src/advanced/eager_loading.md b/book/src/advanced/eager_loading.md
new file mode 100644
index 000000000..95a5c0f84
--- /dev/null
+++ b/book/src/advanced/eager_loading.md
@@ -0,0 +1,280 @@
+Eager loading
+=============
+
+As a further evolution of the [dealing with the N+1 problem via look-ahead](lookahead.md#n1-problem), we may systematically remodel [Rust] types mapping to [GraphQL] ones in the way to encourage doing eager preloading of data for its [fields][0] and using the already preloaded data when resolving a particular [field][0].
+
+At the moment, this approach is represented with the [`juniper-eager-loading`] crate for [Juniper].
+
+> **NOTE**: Since this library requires [`juniper-from-schema`], it's best first to become familiar with it.
+
+<!-- TODO: Provide example of solving the problem from "N+1 chapter" once `juniper-eager-loading` support the latest `juniper`. -->
+
+From ["How this library works at a high level"][11] and ["A real example"][12] sections of [`juniper-eager-loading`] documentation:
+
+> ### How this library works at a high level
+>
+> If you have a GraphQL type like this
+>
+> ```graphql
+> type User {
+>     id: Int!
+>     country: Country!
+> }
+> ```
+>
+> You might create the corresponding Rust model type like this:
+>
+> ```rust
+> struct User {
+>     id: i32,
+>     country_id: i32,
+> }
+> ```
+>
+> However this approach has one big issue. How are you going to resolve the field `User.country`
+> without doing a database query? All the resolver has access to is a `User` with a `country_id`
+> field. It can't get the country without loading it from the database...
+>
+> Fundamentally these kinds of model structs don't work for eager loading with GraphQL. So
+> this library takes a different approach.
+>
+> What if we created separate structs for the database models and the GraphQL models? Something
+> like this:
+>
+> ```rust
+> # fn main() {}
+> #
+> mod models {
+>     pub struct User {
+>         id: i32,
+>         country_id: i32
+>     }
+>
+>     pub struct Country {
+>         id: i32,
+>     }
+> }
+>
+> struct User {
+>     user: models::User,
+>     country: HasOne<Country>,
+> }
+>
+> struct Country {
+>     country: models::Country
+> }
+>
+> enum HasOne<T> {
+>     Loaded(T),
+>     NotLoaded,
+> }
+> ```
+>
+> Now we're able to resolve the query with code like this:
+>
+> 1. Load all the users (first query).
+> 2. Map the users to a list of country ids.
+> 3. Load all the countries with those ids (second query).
+> 4. Pair up the users with the country with the correct id, so change `User.country` from
+>    `HasOne::NotLoaded` to `HasOne::Loaded(matching_country)`.
+> 5. When resolving the GraphQL field `User.country` simply return the loaded country.
+>
+> ### A real example
+>
+> ```rust,ignore
+> use juniper::{Executor, FieldResult};
+> use juniper_eager_loading::{prelude::*, EagerLoading, HasOne};
+> use juniper_from_schema::graphql_schema;
+> use std::error::Error;
+>
+> // Define our GraphQL schema.
+> graphql_schema! {
+>     schema {
+>         query: Query
+>     }
+>
+>     type Query {
+>         allUsers: [User!]! @juniper(ownership: "owned")
+>     }
+>
+>     type User {
+>         id: Int!
+>         country: Country!
+>     }
+>
+>     type Country {
+>         id: Int!
+>     }
+> }
+>
+> // Our model types.
+> mod models {
+>     use std::error::Error;
+>     use juniper_eager_loading::LoadFrom;
+>
+>     #[derive(Clone)]
+>     pub struct User {
+>         pub id: i32,
+>         pub country_id: i32
+>     }
+>
+>     #[derive(Clone)]
+>     pub struct Country {
+>         pub id: i32,
+>     }
+>
+>     // This trait is required for eager loading countries.
+>     // It defines how to load a list of countries from a list of ids.
+>     // Notice that `Context` is generic and can be whatever you want.
+>     // It will normally be your Juniper context which would contain
+>     // a database connection.
+>     impl LoadFrom<i32> for Country {
+>         type Error = Box<dyn Error>;
+>         type Context = super::Context;
+>
+>         fn load(
+>             employments: &[i32],
+>             field_args: &(),
+>             ctx: &Self::Context,
+>         ) -> Result<Vec<Self>, Self::Error> {
+>             // ...
+>             # unimplemented!()
+>         }
+>     }
+> }
+>
+> // Our sample database connection type.
+> pub struct DbConnection;
+>
+> impl DbConnection {
+>     // Function that will load all the users.
+>     fn load_all_users(&self) -> Vec<models::User> {
+>         // ...
+>         # unimplemented!()
+>     }
+> }
+>
+> // Our Juniper context type which contains a database connection.
+> pub struct Context {
+>     db: DbConnection,
+> }
+>
+> impl juniper::Context for Context {}
+>
+> // Our GraphQL user type.
+> // `#[derive(EagerLoading)]` takes care of generating all the boilerplate code.
+> #[derive(Clone, EagerLoading)]
+> // You need to set the context and error type.
+> #[eager_loading(
+>     context = Context,
+>     error = Box<dyn Error>,
+>
+>     // These match the default so you wouldn't have to specify them
+>     model = models::User,
+>     id = i32,
+>     root_model_field = user,
+> )]
+> pub struct User {
+>     // This user model is used to resolve `User.id`
+>     user: models::User,
+>
+>     // Setup a "has one" association between a user and a country.
+>     //
+>     // We could also have used `#[has_one(default)]` here.
+>     #[has_one(
+>         foreign_key_field = country_id,
+>         root_model_field = country,
+>         graphql_field = country,
+>     )]
+>     country: HasOne<Country>,
+> }
+>
+> // And the GraphQL country type.
+> #[derive(Clone, EagerLoading)]
+> #[eager_loading(context = Context, error = Box<dyn Error>)]
+> pub struct Country {
+>     country: models::Country,
+> }
+>
+> // The root query GraphQL type.
+> pub struct Query;
+>
+> impl QueryFields for Query {
+>     // The resolver for `Query.allUsers`.
+>     fn field_all_users(
+>         &self,
+>         executor: &Executor<'_, Context>,
+>         trail: &QueryTrail<'_, User, Walked>,
+>     ) -> FieldResult<Vec<User>> {
+>         let ctx = executor.context();
+>
+>         // Load the model users.
+>         let user_models = ctx.db.load_all_users();
+>
+>         // Turn the model users into GraphQL users.
+>         let mut users = User::from_db_models(&user_models);
+>
+>         // Perform the eager loading.
+>         // `trail` is used to only eager load the fields that are requested. Because
+>         // we're using `QueryTrail`s from "juniper_from_schema" it would be a compile
+>         // error if we eager loaded associations that aren't requested in the query.
+>         User::eager_load_all_children_for_each(&mut users, &user_models, ctx, trail)?;
+>
+>         Ok(users)
+>     }
+> }
+>
+> impl UserFields for User {
+>     fn field_id(
+>         &self,
+>         executor: &Executor<'_, Context>,
+>     ) -> FieldResult<&i32> {
+>         Ok(&self.user.id)
+>     }
+>
+>     fn field_country(
+>         &self,
+>         executor: &Executor<'_, Context>,
+>         trail: &QueryTrail<'_, Country, Walked>,
+>     ) -> FieldResult<&Country> {
+>         // This will unwrap the country from the `HasOne` or return an error if the
+>         // country wasn't loaded, or wasn't found in the database.
+>         Ok(self.country.try_unwrap()?)
+>     }
+> }
+>
+> impl CountryFields for Country {
+>     fn field_id(
+>         &self,
+>         executor: &Executor<'_, Context>,
+>     ) -> FieldResult<&i32> {
+>         Ok(&self.country.id)
+>     }
+> }
+> #
+> # fn main() {}
+> ```
+
+For more details, check out the [`juniper-eager-loading` documentation][`juniper-eager-loading`].
+
+
+
+
+## Full example
+
+For a full example using eager loading in [Juniper] check out the [`davidpdrsn/graphql-app-example` repository][10].
+
+
+
+
+[`juniper-eager-loading`]: https://docs.rs/juniper-eager-loading
+[`juniper-from-schema`]: https://docs.rs/juniper-from-schema
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Redis]: https://redis.io
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Language.Fields
+[10]: https://github.com/davidpdrsn/graphql-app-example
+[11]: https://docs.rs/juniper-eager-loading/latest/juniper_eager_loading#how-this-library-works-at-a-high-level
+[12]: https://docs.rs/juniper-eager-loading/latest/juniper_eager_loading#a-real-example
diff --git a/book/src/advanced/implicit_and_explicit_null.md b/book/src/advanced/implicit_and_explicit_null.md
index 746cb7ee3..66883b3f5 100644
--- a/book/src/advanced/implicit_and_explicit_null.md
+++ b/book/src/advanced/implicit_and_explicit_null.md
@@ -1,101 +1,89 @@
-# Implicit and explicit null
-
-There are two ways that a client can submit a null argument or field in a query.
-
-They can use a null literal:
-
-```graphql
-{
-    field(arg: null)
-}
-```
-
-Or they can simply omit the argument:
-
-```graphql
-{
-    field
-}
-```
-
-The former is an explicit null and the latter is an implicit null.
-
-There are some situations where it's useful to know which one the user provided.
-
-For example, let's say your business logic has a function that allows users to
-perform a "patch" operation on themselves. Let's say your users can optionally
-have favorite and least favorite numbers, and the input for that might look
-like this:
-
+Implicit and explicit `null`
+============================
+
+> [GraphQL] has two semantically different ways to represent the lack of a value:
+> - Explicitly providing the literal value: **null**.
+> - Implicitly not providing a value at all.
+
+There are two ways that a client can submit a [`null` value][0] as an [argument][5] or a [field][4] in a [GraphQL] query:
+1. Either use an explicit `null` literal:
+   ```graphql
+   {
+     field(arg: null)
+   }
+   ```
+2. Or simply omit the [argument][5], so the implicit default `null` value kicks in:
+   ```graphql
+   {
+     field
+   }
+   ```
+
+There are some situations where it's useful to know which one exactly has been provided.
+
+For example, let's say we have a function that allows users to perform a "patch" operation on themselves. Let's say our users can optionally have favorite and least favorite numbers, and the input for that might look like this:
 ```rust
-/// Updates user attributes. Fields that are `None` are left as-is.
-pub struct UserPatch {
-    /// If `Some`, updates the user's favorite number.
-    pub favorite_number: Option<Option<i32>>,
+/// Updates user attributes. Fields that are [`None`] are left as-is.
+struct UserPatch {
+    /// If [`Some`], updates the user's favorite number.
+    favorite_number: Option<Option<i32>>,
 
-    /// If `Some`, updates the user's least favorite number.
-    pub least_favorite_number: Option<Option<i32>>,
+    /// If [`Some`], updates the user's least favorite number.
+    least_favorite_number: Option<Option<i32>>,
 }
-
+#
 # fn main() {}
 ```
 
-To set a user's favorite number to 7, you would set `favorite_number` to
-`Some(Some(7))`. In GraphQL, that might look like this:
-
+To set a user's favorite number to 7, we would set `favorite_number` to `Some(Some(7))`. In [GraphQL], that might look like this:
 ```graphql
 mutation { patchUser(patch: { favoriteNumber: 7 }) }
 ```
 
-To unset the user's favorite number, you would set `favorite_number` to
-`Some(None)`. In GraphQL, that might look like this:
-
+To unset the user's favorite number, we would set `favorite_number` to `Some(None)`. In [GraphQL], that might look like this:
 ```graphql
 mutation { patchUser(patch: { favoriteNumber: null }) }
 ```
 
-If you want to leave the user's favorite number alone, you would set it to
-`None`. In GraphQL, that might look like this:
-
+And if we want to leave the user's favorite number alone, just set it to `None`. In [GraphQL], that might look like this:
 ```graphql
 mutation { patchUser(patch: {}) }
 ```
 
-The last two cases rely on being able to distinguish between explicit and implicit null.
-
-In Juniper, this can be done using the `Nullable` type:
+The last two cases rely on being able to distinguish between [explicit and implicit `null`][1].
 
+Unfortunately, plain `Option` is not capable to distinguish them. That's why in [Juniper], this can be done using the [`Nullable`] type:
 ```rust
 # extern crate juniper;
-use juniper::{FieldResult, Nullable};
+use juniper::{graphql_object, FieldResult, GraphQLInputObject, Nullable};
 
-#[derive(juniper::GraphQLInputObject)]
+#[derive(GraphQLInputObject)]
 struct UserPatchInput {
-    pub favorite_number: Nullable<i32>,
-    pub least_favorite_number: Nullable<i32>,
+    favorite_number: Nullable<i32>,
+    least_favorite_number: Nullable<i32>,
 }
 
-impl Into<UserPatch> for UserPatchInput {
-    fn into(self) -> UserPatch {
-        UserPatch {
-            // The `explicit` function transforms the `Nullable` into an
-            // `Option<Option<T>>` as expected by the business logic layer.
-            favorite_number: self.favorite_number.explicit(),
-            least_favorite_number: self.least_favorite_number.explicit(),
-        }
-    }
+impl From<UserPatchInput> for UserPatch {
+   fn from(input: UserPatchInput) -> Self {
+      Self {
+         // The `explicit()` function transforms the `Nullable` into an
+         // `Option<Option<T>>` as expected by the business logic layer.
+         favorite_number: input.favorite_number.explicit(),
+         least_favorite_number: input.least_favorite_number.explicit(),
+      }
+   }
 }
 
-# pub struct UserPatch {
-#     pub favorite_number: Option<Option<i32>>,
-#     pub least_favorite_number: Option<Option<i32>>,
+# struct UserPatch {
+#     favorite_number: Option<Option<i32>>,
+#     least_favorite_number: Option<Option<i32>>,
 # }
-
+#
 # struct Session;
 # impl Session {
 #     fn patch_user(&self, _patch: UserPatch) -> FieldResult<()> { Ok(()) }
 # }
-
+#
 struct Context {
     session: Session,
 }
@@ -103,15 +91,27 @@ impl juniper::Context for Context {}
 
 struct Mutation;
 
-#[juniper::graphql_object(context = Context)]
+#[graphql_object]
+#[graphql(context = Context)]
 impl Mutation {
-    fn patch_user(ctx: &Context, patch: UserPatchInput) -> FieldResult<bool> {
+    fn patch_user(patch: UserPatchInput, ctx: &Context) -> FieldResult<bool> {
         ctx.session.patch_user(patch.into())?;
         Ok(true)
     }
 }
+#
 # fn main() {}
 ```
 
-This type functions much like `Option`, but has two empty variants so you can
-distinguish between implicit and explicit null.
+
+
+
+[`Nullable`]: https://docs.rs/juniper/latest/juniper/enum.Nullable.html
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Null-Value
+[1]: https://spec.graphql.org/October2021#sel-EAFdRDHAAEJDAoBxzT
+[4]: https://spec.graphql.org/October2021#sec-Language.Fields
+[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
diff --git a/book/src/advanced/index.md b/book/src/advanced/index.md
index 8db84fc64..be2317f2b 100644
--- a/book/src/advanced/index.md
+++ b/book/src/advanced/index.md
@@ -1,11 +1,10 @@
-# Advanced Topics
+Advanced topics
+===============
 
-The chapters below cover some more advanced scenarios.
+The chapters below cover some more advanced topics.
 
-- [Introspection](introspection.md)
-- [Non-struct objects](non_struct_objects.md)
-- [Implicit and explicit null](implicit_and_explicit_null.md)
-- [Objects and generics](objects_and_generics.md)
-- [Multiple operations per request](multiple_ops_per_request.md)
-- [Dataloaders](dataloaders.md)
-- [Subscriptions](subscriptions.md)
+- [Implicit and explicit `null`](implicit_and_explicit_null.md)
+- [N+1 problem](n_plus_1.md)
+    - [DataLoader](dataloader.md)
+    - [Look-ahead](lookahead.md)
+        - [Eager loading](eager_loading.md)
diff --git a/book/src/advanced/introspection.md b/book/src/advanced/introspection.md
deleted file mode 100644
index d7bc7c2f8..000000000
--- a/book/src/advanced/introspection.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Introspection
-
-GraphQL defines a special built-in top-level field called `__schema`. Querying
-for this field allows one to [introspect the schema](https://graphql.org/learn/introspection/)
-at runtime to see what queries and mutations the GraphQL server supports.
-
-Because introspection queries are just regular GraphQL queries, Juniper supports
-them natively. For example, to get all the names of the types supported one
-could execute the following query against Juniper:
-
-```graphql
-{
-  __schema {
-    types {
-      name
-    }
-  }
-}
-```
-
-## Schema introspection output as JSON
-
-Many client libraries and tools in the GraphQL ecosystem require a complete
-representation of the server schema. Often this representation is in JSON and
-referred to as `schema.json`. A complete representation of the schema can be
-produced by issuing a specially crafted introspection query.
-
-Juniper provides a convenience function to introspect the entire schema. The
-result can then be converted to JSON for use with tools and libraries such as
-[graphql-client](https://github.com/graphql-rust/graphql-client):
-
-```rust
-# #![allow(unused_variables)]
-# extern crate juniper;
-# extern crate serde_json;
-use juniper::{
-    graphql_object, EmptyMutation, EmptySubscription, FieldResult, 
-    GraphQLObject, IntrospectionFormat,
-};
-
-// Define our schema.
-
-#[derive(GraphQLObject)]
-struct Example {
-  id: String,
-}
-
-struct Context;
-impl juniper::Context for Context {}
-
-struct Query;
-
-#[graphql_object(context = Context)]
-impl Query {
-   fn example(id: String) -> FieldResult<Example> {
-       unimplemented!()
-   }
-}
-
-type Schema = juniper::RootNode<
-    'static, 
-    Query, 
-    EmptyMutation<Context>, 
-    EmptySubscription<Context>
->;
-
-fn main() {
-    // Create a context object.
-    let ctx = Context;
-
-    // Run the built-in introspection query.
-    let (res, _errors) = juniper::introspect(
-        &Schema::new(Query, EmptyMutation::new(), EmptySubscription::new()),
-        &ctx,
-        IntrospectionFormat::default(),
-    ).unwrap();
-
-    // Convert introspection result to json.
-    let json_result = serde_json::to_string_pretty(&res);
-    assert!(json_result.is_ok());
-}
-```
diff --git a/book/src/advanced/lookahead.md b/book/src/advanced/lookahead.md
new file mode 100644
index 000000000..4ba424369
--- /dev/null
+++ b/book/src/advanced/lookahead.md
@@ -0,0 +1,229 @@
+Look-ahead
+==========
+
+> In backtracking algorithms, **look ahead** is the generic term for a subprocedure that attempts to foresee the effects of choosing a branching variable to evaluate one of its values. The two main aims of look-ahead are to choose a variable to evaluate next and to choose the order of values to assign to it.
+
+In [GraphQL], look-ahead machinery allows us to introspect the currently [executed][1] [GraphQL operation][2] to see which [fields][3] has been actually selected by it.
+
+In [Juniper], it's represented by the [`Executor::look_ahead()`][20] method.
+```rust
+# extern crate juniper;
+# use juniper::{graphql_object, Executor, GraphQLObject, ScalarValue};
+#
+# type UserId = i32;
+#
+#[derive(GraphQLObject)]
+struct Person {
+    id: UserId,
+    name: String,
+}
+
+struct Query;
+
+#[graphql_object]
+// NOTICE: Specifying `ScalarValue` as custom named type parameter,
+//         so its name is similar to the one used in methods.
+#[graphql(scalar = S: ScalarValue)]
+impl Query {
+    fn persons<S: ScalarValue>(executor: &Executor<'_, '_, (), S>) -> Vec<Person> {
+        // Let's see which `Person`'s fields were selected in the client query. 
+        for field_name in executor.look_ahead().children().names() {
+            dbg!(field_name);
+        }
+        // ...
+#       unimplemented!()
+    }
+}
+```
+> **TIP**: `S: ScalarValue` type parameter on the method is required here to keep the [`Executor`] being generic over [`ScalarValue`] types. We, instead, could have used the [`DefaultScalarValue`], which is the default [`ScalarValue`] type for the [`Executor`], and make our code more ergonomic, but less flexible and generic.
+> ```rust
+> # extern crate juniper;
+> # use juniper::{graphql_object, DefaultScalarValue, Executor, GraphQLObject};
+> #
+> # type UserId = i32;
+> #
+> # #[derive(GraphQLObject)]
+> # struct Person {
+> #     id: UserId,
+> #     name: String,
+> # }
+> #
+> # struct Query;
+> #
+> #[graphql_object]
+> #[graphql(scalar = DefaultScalarValue)]
+> impl Query {
+>     fn persons(executor: &Executor<'_, '_, ()>) -> Vec<Person> {
+>         for field_name in executor.look_ahead().children().names() {
+>             dbg!(field_name);
+>         }
+>         // ...
+> #       unimplemented!()
+>     }
+> }
+> ```
+
+
+
+
+## N+1 problem
+
+Naturally, look-ahead machinery allows us to solve [the N+1 problem](n_plus_1.md) by introspecting the requested fields and performing loading in batches eagerly, before actual resolving of those fields:
+```rust
+# extern crate anyhow;
+# extern crate juniper;
+# use std::collections::HashMap;
+# use anyhow::anyhow;
+# use juniper::{graphql_object, Executor, GraphQLObject, ScalarValue};
+#
+# type CultId = i32;
+# type UserId = i32;
+#
+# struct Repository;
+#
+# impl juniper::Context for Repository {}
+#
+# impl Repository {
+#     async fn load_cult_by_id(&self, cult_id: CultId) -> anyhow::Result<Option<Cult>> { unimplemented!() }
+#     async fn load_cults_by_ids(&self, cult_ids: &[CultId]) -> anyhow::Result<HashMap<CultId, Cult>> { unimplemented!() }
+#     async fn load_all_persons(&self) -> anyhow::Result<Vec<Person>> { unimplemented!() }
+# }
+# 
+# enum Either<L, R> {
+#     Absent(L),
+#     Loaded(R),  
+# }
+#
+#[derive(Clone, GraphQLObject)]
+struct Cult {
+    id: CultId,
+    name: String,
+}
+
+struct Person {
+    id: UserId,
+    name: String,
+    cult: Either<CultId, Cult>,
+}
+
+#[graphql_object]
+#[graphql(context = Repository)]
+impl Person {
+    fn id(&self) -> CultId {
+        self.id
+    }
+    
+    fn name(&self) -> &str {
+        self.name.as_str()
+    }
+    
+    async fn cult(&self, #[graphql(ctx)] repo: &Repository) -> anyhow::Result<Cult> {
+        match &self.cult {
+            Either::Loaded(cult) => Ok(cult.clone()),
+            Either::Absent(cult_id) => {
+                // Effectively performs the following SQL query:
+                // SELECT id, name FROM cults WHERE id = ${cult_id} LIMIT 1
+                repo.load_cult_by_id(*cult_id)
+                    .await?
+                    .ok_or_else(|| anyhow!("No cult exists for ID `{cult_id}`"))
+            }
+        }
+    }
+}
+
+struct Query;
+
+#[graphql_object]
+#[graphql(context = Repository, scalar = S: ScalarValue)]
+impl Query {
+    async fn persons<S: ScalarValue>(
+        #[graphql(ctx)] repo: &Repository,
+        executor: &Executor<'_, '_, Repository, S>,
+    ) -> anyhow::Result<Vec<Person>> {
+        // Effectively performs the following SQL query:
+        // SELECT id, name, cult_id FROM persons
+        let mut persons = repo.load_all_persons().await?;
+        
+        // If the `Person.cult` field has been requested.
+        if executor.look_ahead()
+            .children()
+            .iter()
+            .any(|sel| sel.field_original_name() == "cult") 
+        {
+            // Gather `Cult.id`s to load eagerly.
+            let cult_ids = persons
+                .iter()
+                .filter_map(|p| {
+                    match &p.cult {
+                        Either::Absent(cult_id) => Some(*cult_id),
+                        // If for some reason a `Cult` is already loaded,
+                        // then just skip it.
+                        Either::Loaded(_) => None,
+                    }
+                })
+                .collect::<Vec<_>>();
+            
+            // Load the necessary `Cult`s eagerly.
+            // Effectively performs the following SQL query:
+            // SELECT id, name FROM cults WHERE id IN (${cult_id1}, ${cult_id2}, ...)
+            let cults = repo.load_cults_by_ids(&cult_ids).await?;
+            
+            // Populate `persons` with the loaded `Cult`s, so they do not perform
+            // any SQL queries on resolving.
+            for p in &mut persons {
+                let Either::Absent(cult_id) = &p.cult else { continue; };
+                p.cult = Either::Loaded(
+                    cults.get(cult_id)
+                        .ok_or_else(|| anyhow!("No cult exists for ID `{cult_id}`"))?
+                        .clone(),
+                );
+            }
+        }
+        
+        Ok(persons)
+    }
+}
+```
+And so, performing a [GraphQL query which lead to N+1 problem](n_plus_1.md)
+```graphql
+query {
+  persons {
+    id
+    name
+    cult {
+      id
+      name
+    }
+  }
+}
+```
+will lead to efficient [SQL] queries, just as expected:
+```sql
+SELECT id, name, cult_id FROM persons;
+SELECT id, name FROM cults WHERE id IN (1, 2, 3, 4);
+```
+
+
+
+
+## More features
+
+See more available look-ahead features in the API docs of the [`LookAheadSelection`][21] and the [`LookAheadChildren`][22].
+
+
+
+
+[`DefaultScalarValue`]: https://docs.rs/juniper/latest/juniper/enum.DefaultScalarValue.html
+[`Executor`]: https://docs.rs/juniper/latest/juniper/executor/struct.Executor.html
+[`ScalarValue`]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[SQL]: https://en.wikipedia.org/wiki/SQL
+
+[1]: https://spec.graphql.org/October2021#sec-Execution
+[2]: https://spec.graphql.org/October2021#sec-Language.Operations\
+[3]: https://spec.graphql.org/October2021#sec-Language.Fields
+[20]: https://docs.rs/juniper/latest/juniper/executor/struct.Executor.html#method.look_ahead
+[21]: https://docs.rs/juniper/latest/juniper/executor/struct.LookAheadSelection.html
+[22]: https://docs.rs/juniper/latest/juniper/executor/struct.LookAheadChildren.html
diff --git a/book/src/advanced/multiple_ops_per_request.md b/book/src/advanced/multiple_ops_per_request.md
deleted file mode 100644
index 781b994ff..000000000
--- a/book/src/advanced/multiple_ops_per_request.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Multiple operations per request
-
-The GraphQL standard generally assumes there will be one server request for each client operation you want to perform (such as a query or mutation). This is conceptually simple but has the potential to be inefficient.
-
-Some client libraries such as [apollo-link-batch-http](https://www.apollographql.com/docs/link/links/batch-http.html) have added the ability to batch operations in a single HTTP request to save network round-trips and potentially increase performance. There are some [tradeoffs](https://blog.apollographql.com/batching-client-graphql-queries-a685f5bcd41b) that should be considered before batching requests.
-
-Juniper's server integration crates support multiple operations in a single HTTP request using JSON arrays. This makes them compatible with client libraries that support batch operations without any special configuration.
-
-Server integration crates maintained by others are **not required** to support batch requests. Batch requests aren't part of the official GraphQL specification.
-
-Assuming an integration supports batch requests, for the following GraphQL query:
-
-```graphql
-{
-  hero {
-    name
-  }
-}
-```
-
-The json data to POST to the server for an individual request would be:
-
-```json
-{
-  "query": "{hero{name}}"
-}
-```
-
-And the response would be of the form:
-
-```json
-{
-  "data": {
-    "hero": {
-      "name": "R2-D2"
-    }
-  }
-}
-```
-
-If you wanted to run the same query twice in a single HTTP request, the batched json data to POST to the server would be:
-
-```json
-[
-  {
-    "query": "{hero{name}}"
-  },
-  {
-    "query": "{hero{name}}"
-  }
-]
-```
-
-And the response would be of the form:
-
-```json
-[
-  {
-    "data": {
-      "hero": {
-        "name": "R2-D2"
-      }
-    }
-  },
-  {
-    "data": {
-      "hero": {
-        "name": "R2-D2"
-      }
-    }
-  }
-]
-```
diff --git a/book/src/advanced/n_plus_1.md b/book/src/advanced/n_plus_1.md
new file mode 100644
index 000000000..adacb4df8
--- /dev/null
+++ b/book/src/advanced/n_plus_1.md
@@ -0,0 +1,111 @@
+N+1 problem
+===========
+
+A common issue with [GraphQL] server implementations is how the [resolvers][2] query their datasource. With a naive and straightforward approach we quickly run into the N+1 problem, resulting in a large number of unnecessary database queries or [HTTP] requests.
+
+```rust
+# extern crate anyhow;
+# extern crate juniper;
+# use anyhow::anyhow;
+# use juniper::{graphql_object, GraphQLObject};
+#
+# type CultId = i32;
+# type UserId = i32;
+#
+# struct Repository;
+#
+# impl juniper::Context for Repository {}
+#
+# impl Repository {
+#     async fn load_cult_by_id(&self, cult_id: CultId) -> anyhow::Result<Option<Cult>> { unimplemented!() }
+#     async fn load_all_persons(&self) -> anyhow::Result<Vec<Person>> { unimplemented!() }
+# }
+#
+#[derive(GraphQLObject)]
+struct Cult {
+    id: CultId,
+    name: String,
+}
+
+struct Person {
+    id: UserId,
+    name: String,
+    cult_id: CultId,
+}
+
+#[graphql_object]
+#[graphql(context = Repository)]
+impl Person {
+    fn id(&self) -> CultId {
+        self.id
+    }
+    
+    fn name(&self) -> &str {
+        self.name.as_str()
+    }
+    
+    async fn cult(&self, #[graphql(ctx)] repo: &Repository) -> anyhow::Result<Cult> {
+        // Effectively performs the following SQL query:
+        // SELECT id, name FROM cults WHERE id = ${cult_id} LIMIT 1
+        repo.load_cult_by_id(self.cult_id)
+            .await?
+            .ok_or_else(|| anyhow!("No cult exists for ID `{}`", self.cult_id))
+    }
+}
+
+struct Query;
+
+#[graphql_object]
+#[graphql(context = Repository)]
+impl Query {
+    async fn persons(#[graphql(ctx)] repo: &Repository) -> anyhow::Result<Vec<Person>> {
+        // Effectively performs the following SQL query:
+        // SELECT id, name, cult_id FROM persons
+        repo.load_all_persons().await
+    }
+}
+```
+
+Let's say we want to list a bunch of `cult`s `persons` were in:
+```graphql
+query {
+  persons {
+    id
+    name
+    cult {
+      id
+      name
+    }
+  }
+}
+```
+
+Once the `persons` [list][1] has been [resolved][2], a separate [SQL] query is run to find the `cult` of each `Person`. We can see how this could quickly become a problem.
+```sql
+SELECT id, name, cult_id FROM persons;
+SELECT id, name FROM cults WHERE id = 1;
+SELECT id, name FROM cults WHERE id = 2;
+SELECT id, name FROM cults WHERE id = 1;
+SELECT id, name FROM cults WHERE id = 3;
+SELECT id, name FROM cults WHERE id = 4;
+SELECT id, name FROM cults WHERE id = 1;
+SELECT id, name FROM cults WHERE id = 2;
+-- and so on...
+```
+
+There are several ways how this problem may be resolved in [Juniper]. The most common ones are:
+- [DataLoader](dataloader.md)
+- [Look-ahead machinery](lookahead.md)
+    - [Eager loading](eager_loading.md)
+
+
+
+
+[GraphQL]: https://graphql.org
+[HTTP]: https://en.wikipedia.org/wiki/HTTP
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[SQL]: https://en.wikipedia.org/wiki/SQL
+
+[1]: https://spec.graphql.org/October2021#sec-List
+[2]: https://spec.graphql.org/October2021#sec-Executing-Fields
diff --git a/book/src/advanced/non_struct_objects.md b/book/src/advanced/non_struct_objects.md
deleted file mode 100644
index 75169350d..000000000
--- a/book/src/advanced/non_struct_objects.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Non-struct objects
-
-Up until now, we've only looked at mapping structs to GraphQL objects. However,
-any Rust type can be mapped into a GraphQL object. In this chapter, we'll look
-at enums, but traits will work too - they don't _have_ to be mapped into GraphQL
-interfaces.
-
-Using `Result`-like enums can be a useful way of reporting e.g. validation
-errors from a mutation:
-
-```rust
-# extern crate juniper;
-# use juniper::{graphql_object, GraphQLObject};
-# #[derive(juniper::GraphQLObject)] struct User { name: String }
-#
-#[derive(GraphQLObject)]
-struct ValidationError {
-    field: String,
-    message: String,
-}
-
-# #[allow(dead_code)]
-enum SignUpResult {
-    Ok(User),
-    Error(Vec<ValidationError>),
-}
-
-#[graphql_object]
-impl SignUpResult {
-    fn user(&self) -> Option<&User> {
-        match *self {
-            SignUpResult::Ok(ref user) => Some(user),
-            SignUpResult::Error(_) => None,
-        }
-    }
-
-    fn error(&self) -> Option<&Vec<ValidationError>> {
-        match *self {
-            SignUpResult::Ok(_) => None,
-            SignUpResult::Error(ref errors) => Some(errors)
-        }
-    }
-}
-#
-# fn main() {}
-```
-
-Here, we use an enum to decide whether a user's input data was valid or not, and
-it could be used as the result of e.g. a sign up mutation.
-
-While this is an example of how you could use something other than a struct to
-represent a GraphQL object, it's also an example on how you could implement
-error handling for "expected" errors - errors like validation errors. There are
-no hard rules on how to represent errors in GraphQL, but there are
-[some](https://github.com/facebook/graphql/issues/117#issuecomment-170180628)
-[comments](https://github.com/graphql/graphql-js/issues/560#issuecomment-259508214)
-from one of the authors of GraphQL on how they intended "hard" field errors to
-be used, and how to model expected errors.
diff --git a/book/src/advanced/objects_and_generics.md b/book/src/advanced/objects_and_generics.md
deleted file mode 100644
index d71089f68..000000000
--- a/book/src/advanced/objects_and_generics.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Objects and generics
-
-Yet another point where GraphQL and Rust differs is in how generics work. In
-Rust, almost any type could be generic - that is, take type parameters. In
-GraphQL, there are only two generic types: lists and non-nullables.
-
-This poses a restriction on what you can expose in GraphQL from Rust: no generic
-structs can be exposed - all type parameters must be bound. For example, you can
-not make e.g. `Result<T, E>` into a GraphQL type, but you _can_ make e.g.
-`Result<User, String>` into a GraphQL type.
-
-Let's make a slightly more compact but generic implementation of [the last
-chapter](non_struct_objects.md):
-
-```rust
-# extern crate juniper;
-# #[derive(juniper::GraphQLObject)] struct User { name: String }
-# #[derive(juniper::GraphQLObject)] struct ForumPost { title: String }
-
-#[derive(juniper::GraphQLObject)]
-struct ValidationError {
-    field: String,
-    message: String,
-}
-
-# #[allow(dead_code)]
-struct MutationResult<T>(Result<T, Vec<ValidationError>>);
-
-#[juniper::graphql_object(
-    name = "UserResult",
-)]
-impl MutationResult<User> {
-    fn user(&self) -> Option<&User> {
-        self.0.as_ref().ok()
-    }
-
-    fn error(&self) -> Option<&Vec<ValidationError>> {
-        self.0.as_ref().err()
-    }
-}
-
-#[juniper::graphql_object(
-    name = "ForumPostResult",
-)]
-impl MutationResult<ForumPost> {
-    fn forum_post(&self) -> Option<&ForumPost> {
-        self.0.as_ref().ok()
-    }
-
-    fn error(&self) -> Option<&Vec<ValidationError>> {
-        self.0.as_ref().err()
-    }
-}
-
-# fn main() {}
-```
-
-Here, we've made a wrapper around `Result` and exposed some concrete
-instantiations of `Result<T, E>` as distinct GraphQL objects. The reason we
-needed the wrapper is of Rust's rules for when you can derive a trait - in this
-case, both `Result` and Juniper's internal GraphQL trait are from third-party
-sources.
-
-Because we're using generics, we also need to specify a name for our
-instantiated types. Even if Juniper _could_ figure out the name,
-`MutationResult<User>` wouldn't be a valid GraphQL type name.
diff --git a/book/src/advanced/subscriptions.md b/book/src/advanced/subscriptions.md
deleted file mode 100644
index 9aaa93635..000000000
--- a/book/src/advanced/subscriptions.md
+++ /dev/null
@@ -1,175 +0,0 @@
-# Subscriptions
-### How to achieve realtime data with GraphQL subscriptions
-
-GraphQL subscriptions are a way to push data from the server to clients requesting real-time messages 
-from the server. Subscriptions are similar to queries in that they specify a set of fields to be delivered to the client,
-but instead of immediately returning a single answer a result is sent every time a particular event happens on the 
-server. 
-
-In order to execute subscriptions you need a coordinator (that spawns connections) 
-and a GraphQL object that can be resolved into a stream--elements of which will then 
-be returned to the end user. The [`juniper_subscriptions`][juniper_subscriptions] crate 
-provides a default connection implementation. Currently subscriptions are only supported on the `master` branch. Add the following to your `Cargo.toml`:
-```toml
-[dependencies]
-juniper = "0.16.0"
-juniper_subscriptions = "0.17.0"
-```
-
-### Schema Definition
-
-The `Subscription` is just a GraphQL object, similar to the query root and mutations object that you defined for the 
-operations in your [Schema][Schema]. For subscriptions all fields/operations should be async and should return a [Stream][Stream].
-
-This example shows a subscription operation that returns two events, the strings `Hello` and `World!`
-sequentially: 
-
-```rust
-# extern crate futures;
-# extern crate juniper;
-# use std::pin::Pin;
-# use futures::Stream;
-# use juniper::{graphql_object, graphql_subscription, FieldError};
-#
-# #[derive(Clone)]
-# pub struct Database;
-# impl juniper::Context for Database {}
-
-# pub struct Query;
-# #[graphql_object(context = Database)]
-# impl Query {
-#    fn hello_world() -> &'static str {
-#        "Hello World!"
-#    }
-# }
-pub struct Subscription;
-
-type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
-
-#[graphql_subscription(context = Database)]
-impl Subscription {
-    async fn hello_world() -> StringStream {
-        let stream = futures::stream::iter(vec![
-            Ok(String::from("Hello")),
-            Ok(String::from("World!"))
-        ]);
-        Box::pin(stream)
-    }
-}
-#
-# fn main () {}
-```
-
-
-
-### Coordinator
-
-Subscriptions require a bit more resources than regular queries and provide a great vector for DOS attacks. This can can bring down a server easily if not handled correctly. The [`SubscriptionCoordinator`][SubscriptionCoordinator] trait provides coordination logic to enable functionality like DOS attack mitigation and resource limits.
-
-The [`SubscriptionCoordinator`][SubscriptionCoordinator] contains the schema and can keep track of opened connections, handle subscription 
-start and end, and maintain a global subscription id for each subscription. Each time a connection is established,  
-the [`SubscriptionCoordinator`][SubscriptionCoordinator] spawns a [`SubscriptionConnection`][SubscriptionConnection]. The [`SubscriptionConnection`][SubscriptionConnection] handles a single connection, providing resolver logic for a client stream as well as reconnection 
-and shutdown logic.
-
-
-While you can implement [`SubscriptionCoordinator`][SubscriptionCoordinator] yourself, Juniper contains a simple and generic implementation called [`Coordinator`][Coordinator].  The `subscribe` 
-operation returns a [`Future`][Future] with an `Item` value of a `Result<Connection, GraphQLError>`,
-where [`Connection`][Connection] is a `Stream` of values returned by the operation and [`GraphQLError`][GraphQLError] is the error when the subscription fails.
-
-```rust
-# #![allow(dead_code)]
-# extern crate futures;
-# extern crate juniper;
-# extern crate juniper_subscriptions;
-# extern crate serde_json;
-# use juniper::{
-#     http::GraphQLRequest,
-#     graphql_object, graphql_subscription, 
-#     DefaultScalarValue, EmptyMutation, FieldError, 
-#     RootNode, SubscriptionCoordinator,
-# };
-# use juniper_subscriptions::Coordinator;
-# use futures::{Stream, StreamExt};
-# use std::pin::Pin;
-# 
-# #[derive(Clone)]
-# pub struct Database;
-# 
-# impl juniper::Context for Database {}
-# 
-# impl Database {
-#     fn new() -> Self {
-#         Self
-#     }
-# }
-# 
-# pub struct Query;
-# 
-# #[graphql_object(context = Database)]
-# impl Query {
-#     fn hello_world() -> &'static str {
-#         "Hello World!"
-#     }
-# }
-# 
-# pub struct Subscription;
-# 
-# type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
-# 
-# #[graphql_subscription(context = Database)]
-# impl Subscription {
-#     async fn hello_world() -> StringStream {
-#         let stream =
-#             futures::stream::iter(vec![Ok(String::from("Hello")), Ok(String::from("World!"))]);
-#         Box::pin(stream)
-#     }
-# }
-type Schema = RootNode<'static, Query, EmptyMutation<Database>, Subscription>;
-
-fn schema() -> Schema {
-    Schema::new(Query, EmptyMutation::new(), Subscription)
-}
-
-async fn run_subscription() {
-    let schema = schema();
-    let coordinator = Coordinator::new(schema);
-    let req: GraphQLRequest<DefaultScalarValue> = serde_json::from_str(
-        r#"{
-            "query": "subscription { helloWorld }"
-        }"#,
-    )
-        .unwrap();
-    let ctx = Database::new();
-    let mut conn = coordinator.subscribe(&req, &ctx).await.unwrap();
-    while let Some(result) = conn.next().await {
-        println!("{}", serde_json::to_string(&result).unwrap());
-    }
-}
-#
-# fn main() { }
-```     
-
-### Web Integration and Examples
-
-Currently there is an example of subscriptions with [warp][warp], but it still in an alpha state.
-GraphQL over [WS][WS] is not fully supported yet and is non-standard.
-
-- [Warp Subscription Example](https://github.com/graphql-rust/juniper/tree/master/juniper_warp/examples/subscription.rs)
-- [Small Example](https://github.com/graphql-rust/juniper/tree/master/juniper_subscriptions/examples/basic.rs)
-
-
-
-
-[juniper_subscriptions]: https://github.com/graphql-rust/juniper/tree/master/juniper_subscriptions
-[Stream]: https://docs.rs/futures/0.3.4/futures/stream/trait.Stream.html
- <!-- TODO: Fix these links when the documentation for the `juniper_subscriptions` are defined in the docs. --->
-[Coordinator]: https://docs.rs/juniper_subscriptions/0.15.0/struct.Coordinator.html
-[SubscriptionCoordinator]: https://docs.rs/juniper_subscriptions/0.15.0/trait.SubscriptionCoordinator.html
-[Connection]: https://docs.rs/juniper_subscriptions/0.15.0/struct.Connection.html
-[SubscriptionConnection]: https://docs.rs/juniper_subscriptions/0.15.0/trait.SubscriptionConnection.html
-<!--- --->
-[Future]: https://docs.rs/futures/0.3.4/futures/future/trait.Future.html
-[warp]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp
-[WS]: https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md
-[GraphQLError]: https://docs.rs/juniper/0.14.2/juniper/enum.GraphQLError.html
-[Schema]: ../schema/schemas_and_mutations.md
diff --git a/book/src/introduction.md b/book/src/introduction.md
new file mode 100644
index 000000000..d4c55b565
--- /dev/null
+++ b/book/src/introduction.md
@@ -0,0 +1,83 @@
+Introduction
+============
+
+> [GraphQL] is a query language for APIs and a runtime for fulfilling those queries with your existing data. [GraphQL] provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
+
+[Juniper] is a library for creating [GraphQL] servers in [Rust]. Build type-safe and fast API servers with minimal boilerplate and configuration (we do try to make declaring and resolving [GraphQL] schemas as convenient as possible as [Rust] will allow).
+
+[Juniper] doesn't include a web server itself, instead, it provides building blocks to make integration with existing web servers straightforward. It optionally provides a pre-built integration for some widely used web server frameworks in [Rust] ecosystem.
+
+- [Cargo crate](https://crates.io/crates/juniper)
+- [API reference][`juniper`]
+
+
+
+
+## Features
+
+[Juniper] supports the full GraphQL query language according to the [specification (October 2021)][GraphQL spec].
+
+> **NOTE**: As an exception to other [GraphQL] libraries for other languages, [Juniper] builds non-`null` types by default. A field of type `Vec<Episode>` will be converted into `[Episode!]!`. The corresponding Rust type for a `null`able `[Episode]` would be `Option<Vec<Option<Episode>>>` instead.
+
+
+
+
+## Integrations
+
+
+### Types
+
+[Juniper] provides out-of-the-box integration for some very common [Rust] crates to make building schemas a breeze. The types from these crates will be usable in your schemas automatically after enabling the correspondent self-titled [Cargo feature]:
+- [`bigdecimal`]
+- [`bson`]
+- [`chrono`], [`chrono-tz`]
+- [`rust_decimal`]
+- [`time`]
+- [`url`]
+- [`uuid`]
+
+
+
+
+### Web server frameworks
+
+- [`actix-web`] ([`juniper_actix`] crate)
+- [`axum`] ([`juniper_axum`] crate)
+- [`hyper`] ([`juniper_hyper`] crate)
+- [`rocket`] ([`juniper_rocket`] crate)
+- [`warp`] ([`juniper_warp`] crate)
+
+
+
+
+## API stability
+
+[Juniper] has not reached 1.0 yet, thus some API instability should be expected.
+
+
+
+
+[`actix-web`]: https://docs.rs/actix-web
+[`axum`]: https://docs.rs/axum
+[`bigdecimal`]: https://docs.rs/bigdecimal
+[`bson`]: https://docs.rs/bson
+[`chrono`]: https://docs.rs/chrono
+[`chrono-tz`]: https://docs.rs/chrono-tz
+[`juniper`]: https://docs.rs/juniper
+[`juniper_actix`]: https://docs.rs/juniper_actix
+[`juniper_axum`]: https://docs.rs/juniper_axum
+[`juniper_hyper`]: https://docs.rs/juniper_hyper
+[`juniper_rocket`]: https://docs.rs/juniper_rocket
+[`juniper_warp`]: https://docs.rs/juniper_warp
+[`hyper`]: https://docs.rs/hyper
+[`rocket`]: https://docs.rs/rocket
+[`rust_decimal`]: https://docs.rs/rust_decimal
+[`time`]: https://docs.rs/time
+[`url`]: https://docs.rs/url
+[`uuid`]: https://docs.rs/uuid
+[`warp`]: https://docs.rs/warp
+[Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
+[GraphQL]: https://graphql.org
+[GraphQL spec]: https://spec.graphql.org/October2021
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
diff --git a/book/src/quickstart.md b/book/src/quickstart.md
index a8633414e..eddfe6a7c 100644
--- a/book/src/quickstart.md
+++ b/book/src/quickstart.md
@@ -1,8 +1,14 @@
-# Quickstart
+Quickstart
+==========
+
+This page will give you a short introduction to the concepts in [Juniper].
+
+**[Juniper] follows a [code-first] approach to define a [GraphQL] schema.**
+
+> **TIP**: For a [schema-first] approach, consider using a [`juniper-from-schema`] crate for generating a [`juniper`]-based code from a [schema] file.
+
 
-This page will give you a short introduction to the concepts in Juniper.
 
-Juniper follows a [code-first approach][schema_approach] to defining GraphQL schemas. If you would like to use a [schema-first approach][schema_approach] instead, consider [juniper-from-schema][] for generating code from a schema file.
 
 ## Installation
 
@@ -11,24 +17,23 @@ Juniper follows a [code-first approach][schema_approach] to defining GraphQL sch
 juniper = "0.16.0"
 ```
 
-## Schema example
 
-Exposing simple enums and structs as GraphQL is just a matter of adding a custom
-derive attribute to them. Juniper includes support for basic Rust types that
-naturally map to GraphQL features, such as `Option<T>`, `Vec<T>`, `Box<T>`,
-`String`, `f64`, and `i32`, references, and slices.
 
-For more advanced mappings, Juniper provides multiple macros to map your Rust
-types to a GraphQL schema. The most important one is the
-[graphql_object][graphql_object] procedural macro that is used for declaring an object with
-resolvers, which you will use for the `Query` and `Mutation` roots.
+
+## Schema
+
+Exposing simple enums and structs as [GraphQL] types is just a matter of adding a custom [derive attribute] to them. [Juniper] includes support for basic [Rust] types that naturally map to [GraphQL] features, such as `Option<T>`, `Vec<T>`, `Box<T>`, `Arc<T>`, `String`, `f64`, `i32`, references, slices and arrays.
+
+For more advanced mappings, [Juniper] provides multiple macros to map your [Rust] types to a [GraphQL schema][schema]. The most important one is the [`#[graphql_object]` attribute][2] that is used for declaring a [GraphQL object] with resolvers (typically used for declaring [`Query` and `Mutation` roots][1]).
 
 ```rust
-# #![allow(unused_variables)]
+# # ![allow(unused_variables)]
 # extern crate juniper;
+#
 # use std::fmt::Display;
+#
 use juniper::{
-    graphql_object, EmptySubscription, FieldResult, GraphQLEnum, 
+    graphql_object, EmptySubscription, FieldResult, GraphQLEnum,
     GraphQLInputObject, GraphQLObject, ScalarValue,
 };
 #
@@ -56,7 +61,6 @@ struct Human {
 }
 
 // There is also a custom derive for mapping GraphQL input objects.
-
 #[derive(GraphQLInputObject)]
 #[graphql(description = "A humanoid creature in the Star Wars universe")]
 struct NewHuman {
@@ -65,52 +69,58 @@ struct NewHuman {
     home_planet: String,
 }
 
-// Now, we create our root Query and Mutation types with resolvers by using the
-// object macro.
-// Objects can have contexts that allow accessing shared state like a database
-// pool.
+// Now, we create our root `Query` and `Mutation` types with resolvers by using 
+// the `#[graphql_object]` attribute.
 
+// Resolvers can have a context that allows accessing shared state like a 
+// database pool.
 struct Context {
     // Use your real database pool here.
-    pool: DatabasePool,
+    db: DatabasePool,
 }
 
-// To make our context usable by Juniper, we have to implement a marker trait.
+// To make our `Context` usable by `juniper`, we have to implement a marker 
+// trait.
 impl juniper::Context for Context {}
 
 struct Query;
 
-#[graphql_object(
-    // Here we specify the context type for the object.
-    // We need to do this in every type that
-    // needs access to the context.
-    context = Context,
-)]
+// Here we specify the context type for the object.
+// We need to do this in every type that needs access to the `Context`.
+#[graphql_object]
+#[graphql(context = Context)]
 impl Query {
-    fn apiVersion() -> &'static str {
+    // Note, that the field name will be automatically converted to the
+    // `camelCased` variant, just as GraphQL conventions imply.
+    fn api_version() -> &'static str {
         "1.0"
     }
 
-    // Arguments to resolvers can either be simple types or input objects.
-    // To gain access to the context, we specify a argument
-    // that is a reference to the Context type.
-    // Juniper automatically injects the correct context here.
-    fn human(context: &Context, id: String) -> FieldResult<Human> {
-        // Get a db connection.
-        let connection = context.pool.get_connection()?;
-        // Execute a db query.
+    fn human(
+        // Arguments to resolvers can either be simple scalar types, enums or 
+        // input objects.
+        id: String,
+        // To gain access to the `Context`, we specify a `context`-named 
+        // argument referring the correspondent `Context` type, and `juniper`
+        // will inject it automatically.
+        context: &Context,
+    ) -> FieldResult<Human> {
+        // Get a `db` connection.
+        let conn = context.db.get_connection()?;
+        // Execute a `db` query.
         // Note the use of `?` to propagate errors.
-        let human = connection.find_human(&id)?;
+        let human = conn.find_human(&id)?;
         // Return the result.
         Ok(human)
     }
 }
 
-// Now, we do the same for our Mutation type.
+// Now, we do the same for our `Mutation` type.
 
 struct Mutation;
 
-#[graphql_object(
+#[graphql_object]
+#[graphql(
     context = Context,
     // If we need to use `ScalarValue` parametrization explicitly somewhere
     // in the object definition (like here in `FieldResult`), we could
@@ -118,42 +128,48 @@ struct Mutation;
     scalar = S: ScalarValue + Display,
 )]
 impl Mutation {
-    fn createHuman<S: ScalarValue + Display>(context: &Context, new_human: NewHuman) -> FieldResult<Human, S> {
-        let db = context.pool.get_connection().map_err(|e| e.map_scalar_value())?;
+    fn create_human<S: ScalarValue + Display>(
+        new_human: NewHuman,
+        context: &Context,
+    ) -> FieldResult<Human, S> {
+        let db = context.db.get_connection().map_err(|e| e.map_scalar_value())?;
         let human: Human = db.insert_human(&new_human).map_err(|e| e.map_scalar_value())?;
         Ok(human)
     }
 }
 
-// A root schema consists of a query, a mutation, and a subscription.
-// Request queries can be executed against a RootNode.
+// Root schema consists of a query, a mutation, and a subscription.
+// Request queries can be executed against a `RootNode`.
 type Schema = juniper::RootNode<'static, Query, Mutation, EmptySubscription<Context>>;
 #
 # fn main() {
-#   let _ = Schema::new(Query, Mutation, EmptySubscription::new());
+#     _ = Schema::new(Query, Mutation, EmptySubscription::new());
 # }
 ```
 
-We now have a very simple but functional schema for a GraphQL server!
+Now we have a very simple but functional schema for a [GraphQL] server!
+
+To actually serve the [schema], see the guides for our various [server integrations](serve/index.md).
+
 
-To actually serve the schema, see the guides for our various [server integrations](./servers/index.md).
 
-Juniper is a library that can be used in many contexts--it does not require a server and it does not have a dependency on a particular transport or serialization format. You can invoke the executor directly to get a result for a query:
 
-## Executor
+## Execution
 
-You can invoke `juniper::execute` directly to run a GraphQL query:
+[Juniper] is a library that can be used in many contexts: it doesn't require a server, nor it has a dependency on a particular transport or serialization format. You can invoke the `juniper::execute()` directly to get a result for a [GraphQL] query:
 
 ```rust
 # // Only needed due to 2018 edition because the macro is not accessible.
 # #[macro_use] extern crate juniper;
 use juniper::{
-    graphql_object, EmptyMutation, EmptySubscription, FieldResult, 
-    GraphQLEnum, Variables, graphql_value,
+    graphql_object, graphql_value, EmptyMutation, EmptySubscription, 
+    GraphQLEnum, Variables, 
 };
 
 #[derive(GraphQLEnum, Clone, Copy)]
 enum Episode {
+    // Note, that the enum value will be automatically converted to the
+    // `SCREAMING_SNAKE_CASE` variant, just as GraphQL conventions imply.
     NewHope,
     Empire,
     Jedi,
@@ -166,22 +182,21 @@ impl juniper::Context for Ctx {}
 
 struct Query;
 
-#[graphql_object(context = Ctx)]
+#[graphql_object]
+#[graphql(context = Ctx)]
 impl Query {
-    fn favoriteEpisode(context: &Ctx) -> FieldResult<Episode> {
-        Ok(context.0)
+    fn favorite_episode(context: &Ctx) -> Episode {
+        context.0
     }
 }
 
-// A root schema consists of a query, a mutation, and a subscription.
-// Request queries can be executed against a RootNode.
 type Schema = juniper::RootNode<'static, Query, EmptyMutation<Ctx>, EmptySubscription<Ctx>>;
 
 fn main() {
-    // Create a context object.
+    // Create a context.
     let ctx = Ctx(Episode::NewHope);
 
-    // Run the executor.
+    // Run the execution.
     let (res, _errors) = juniper::execute_sync(
         "query { favoriteEpisode }",
         None,
@@ -190,20 +205,28 @@ fn main() {
         &ctx,
     ).unwrap();
 
-    // Ensure the value matches.
     assert_eq!(
         res,
         graphql_value!({
             "favoriteEpisode": "NEW_HOPE",
-        })
+        }),
     );
 }
 ```
 
-[juniper-from-schema]: https://github.com/davidpdrsn/juniper-from-schema
-[schema_approach]: https://blog.logrocket.com/code-first-vs-schema-first-development-graphql/
-[hyper]: servers/hyper.md
-[warp]: servers/warp.md
-[rocket]: servers/rocket.md
-[tutorial]: ./tutorial.html
-[graphql_object]: https://docs.rs/juniper/latest/juniper/macro.graphql_object.html
+
+
+
+[`juniper`]: https://docs.rs/juniper
+[`juniper-from-schema`]: https://docs.rs/juniper-from-schema
+[code-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#code-only
+[derive attribute]: https://doc.rust-lang.org/stable/reference/attributes/derive.html#derive
+[GraphQL]: https://graphql.org
+[GraphQL object]: https://spec.graphql.org/October2021#sec-Objects
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[schema]: https://graphql.org/learn/schema
+[schema-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#schema-first
+
+[1]: https://spec.graphql.org/October2021#sec-Root-Operation-Types
+[2]: https://docs.rs/juniper/latest/juniper/macro.graphql_object.html
diff --git a/book/src/schema/index.md b/book/src/schema/index.md
new file mode 100644
index 000000000..bad4b7b40
--- /dev/null
+++ b/book/src/schema/index.md
@@ -0,0 +1,185 @@
+Schema
+======
+
+**[Juniper] follows a [code-first] approach to define a [GraphQL] schema.**
+
+> **TIP**: For a [schema-first] approach, consider using a [`juniper-from-schema`] crate for generating a [`juniper`]-based code from a [schema] file.
+
+[GraphQL schema][0] consists of three [object types][4]: a [query root][1], a [mutation root][2], and a [subscription root][3].
+
+> The **query** root operation type must be provided and must be an [Object][4] type.
+> 
+> The **mutation** root operation type is optional; if it is not provided, the service does not support mutations. If it is provided, it must be an [Object][4] type.
+> 
+> Similarly, the **subscription** root operation type is also optional; if it is not provided, the service does not support subscriptions. If it is provided, it must be an [Object][4] type.
+> 
+> The **query**, **mutation**, and **subscription** root types must all be different types if provided.
+
+In [Juniper], the [`RootNode`] type represents a [schema][0]. When the [schema][0] is first created, [Juniper] will traverse the entire object graph and register all types it can find. This means that if we [define a GraphQL object](../types/objects/index.md) somewhere but never use or reference it, it won't be exposed in a [GraphQL schema][0].
+
+Both [query][1] and [mutation][2] objects are regular [GraphQL objects][4], defined like [any other object in Juniper](../types/objects/index.md). The [mutation][2] and [subscription][3] objects, however, are optional, since [schemas][0] can be read-only and do not require [subscriptions][3].
+
+> **TIP**: If [mutation][2]/[subscription][3] functionality is not needed, consider using the predefined [`EmptyMutation`]/[`EmptySubscription`] types for stubbing them in a [`RootNode`].
+
+```rust
+# extern crate juniper;
+# use juniper::{
+#     graphql_object, EmptySubscription, FieldResult, GraphQLObject, RootNode,
+# };
+#
+#[derive(GraphQLObject)] 
+struct User { 
+    name: String,
+}
+
+struct Query;
+
+#[graphql_object]
+impl Query {
+    fn user_with_username(username: String) -> FieldResult<Option<User>> {
+        // Look up user in database...
+#       unimplemented!()
+    }
+}
+
+struct Mutation;
+
+#[graphql_object]
+impl Mutation {
+    fn sign_up_user(name: String, email: String) -> FieldResult<User> {
+        // Validate inputs and save user in database...
+#       unimplemented!()
+    }
+}
+
+type Schema = RootNode<'static, Query, Mutation, EmptySubscription>;
+#
+# fn main() {}
+```
+
+> **NOTE**: It's considered a [good practice][5] to name [query][1], [mutation][2], and [subscription][3] root types as `Query`, `Mutation`, and `Subscription` respectively.
+
+The usage of [subscriptions][3] is a little different from the [mutation][2] and [query][1] [objects][4], so they are discussed in the [separate chapter](subscriptions.md).
+
+
+
+
+## Export
+
+Many tools in [GraphQL] ecosystem require a [schema] definition to operate on. With [Juniper] we can export our [GraphQL schema][0] defined in [Rust] code either represented in the [GraphQL schema language][6] or in [JSON].
+
+
+### SDL (schema definition language)
+
+To generate an [SDL (schema definition language)][6] representation of a [GraphQL schema][0] defined in [Rust] code, the [`as_sdl()` method][20] should be used for the direct extraction (requires enabling the `schema-language` [Juniper] feature):
+```rust
+# extern crate juniper;
+# use juniper::{
+#     graphql_object, EmptyMutation, EmptySubscription, FieldResult, RootNode,
+# };
+#
+struct Query;
+
+#[graphql_object]
+impl Query {
+    fn hello(&self) -> FieldResult<&str> {
+        Ok("hello world")
+    }
+}
+
+fn main() {
+    // Define our schema in Rust.
+    let schema = RootNode::new(
+        Query,
+        EmptyMutation::<()>::new(),
+        EmptySubscription::<()>::new(),
+    );
+
+    // Convert the Rust schema into the GraphQL SDL schema.
+    let result = schema.as_sdl();
+
+    let expected = "\
+schema {
+  query: Query
+}
+
+type Query {
+  hello: String!
+}
+";
+#   #[cfg(not(target_os = "windows"))]
+    assert_eq!(result, expected);
+}
+```
+
+
+### JSON
+
+To export a [GraphQL schema][0] defined in [Rust] code as [JSON] (often referred to as `schema.json`), the specially crafted [introspection query][21] should be issued. [Juniper] provides a [convenience `introspect()` function][22] to [introspect](introspection.md) the entire [schema][0], which result can be serialized into [JSON]:
+```rust
+# extern crate juniper;
+# extern crate serde_json;
+# use juniper::{
+#     graphql_object, EmptyMutation, EmptySubscription, GraphQLObject,
+#     IntrospectionFormat, RootNode,
+# };
+#
+#[derive(GraphQLObject)]
+struct Example {
+    id: String,
+}
+
+struct Query;
+
+#[graphql_object]
+impl Query {
+   fn example(id: String) -> Example {
+       unimplemented!()
+   }
+}
+
+type Schema = RootNode<'static, Query, EmptyMutation, EmptySubscription>;
+
+fn main() {
+    // Run the built-in introspection query.
+    let (res, _errors) = juniper::introspect(
+        &Schema::new(Query, EmptyMutation::new(), EmptySubscription::new()),
+        &(),
+        IntrospectionFormat::default(),
+    ).unwrap();
+
+    // Serialize the introspection result into JSON.
+    let json_result = serde_json::to_string_pretty(&res);
+    assert!(json_result.is_ok());
+}
+```
+
+> **TIP**: We still can convert the generated [JSON] into a [GraphQL schema language][6] representation by using tools like [`graphql-json-to-sdl` command line utility][30].
+
+
+
+
+[`EmptyMutation`]: https://docs.rs/juniper/latest/juniper/struct.EmptyMutation.html
+[`EmptySubscription`]: https://docs.rs/juniper/latest/juniper/struct.EmptySubscription.html
+[`juniper`]: https://docs.rs/juniper
+[`juniper-from-schema`]: https://docs.rs/juniper-from-schema
+[`RootNode`]: https://docs.rs/juniper/latest/juniper/struct.RootNode.html
+[code-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#code-only
+[schema-first]: https://www.apollographql.com/blog/backend/architecture/schema-first-vs-code-only-graphql#schema-first
+[GraphQL]: https://graphql.org
+[JSON]: https://www.json.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[schema]: https://graphql.org/learn/schema
+
+[0]: https://spec.graphql.org/October2021#sec-Schema
+[1]: https://spec.graphql.org/October2021#sel-FAHTRFCAACChCtpG
+[2]: https://spec.graphql.org/October2021#sel-FAHTRHCAACCuE9yD
+[3]: https://spec.graphql.org/October2021#sel-FAHTRJCAACC3EhsX
+[4]: https://spec.graphql.org/October2021#sec-Objects
+[5]: https://spec.graphql.org/October2021#sec-Root-Operation-Types.Default-Root-Operation-Type-Names
+[6]: https://graphql.org/learn/schema#type-language
+[20]: https://docs.rs/juniper/latest/juniper/struct.RootNode.html#method.as_sdl
+[21]: https://docs.rs/crate/juniper/latest/source/src/introspection/query.graphql
+[22]: https://docs.rs/juniper/latest/juniper/fn.introspect.html
+[30]: https://npmjs.com/package/graphql-json-to-sdl
\ No newline at end of file
diff --git a/book/src/schema/introspection.md b/book/src/schema/introspection.md
new file mode 100644
index 000000000..14594f43a
--- /dev/null
+++ b/book/src/schema/introspection.md
@@ -0,0 +1,83 @@
+Introspection
+=============
+
+> The [schema introspection][1] system is accessible from the meta-fields `__schema` and `__type` which are accessible from the type of the root of a query operation.
+> ```graphql
+> __schema: __Schema!
+> __type(name: String!): __Type
+> ```
+> Like all meta-fields, these are implicit and do not appear in the fields list in the root type of the query operation.
+
+[GraphQL] provides [introspection][0], allowing to see what [queries][2], [mutations][3] and [subscriptions][4] a [GraphQL] server supports at runtime.
+
+Because [introspection][0] queries are just regular [GraphQL queries][2], [Juniper] supports them natively. For example, to get all the names of the types supported, we could [execute][5] the following [query][2] against [Juniper]:
+```graphql
+{
+  __schema {
+    types {
+      name
+    }
+  }
+}
+```
+
+
+
+
+## Disabling
+
+> Disabling introspection in production is a widely debated topic, but we believe it’s one of the first things you can do to harden your GraphQL API in production.
+
+[Some security requirements and considerations][10] may mandate to disable [GraphQL schema introspection][1] in production environments. In [Juniper] this can be achieved by using the [`RootNode::disable_introspection()`][9] method:
+```rust
+# extern crate juniper;
+# use juniper::{
+#     graphql_object, graphql_vars, EmptyMutation, EmptySubscription, GraphQLError,
+#     RootNode,
+# };
+#
+pub struct Query;
+
+#[graphql_object]
+impl Query {
+    fn some() -> bool {
+        true
+    }
+}
+
+type Schema = RootNode<'static, Query, EmptyMutation, EmptySubscription>;
+
+fn main() {
+    let schema = Schema::new(Query, EmptyMutation::new(), EmptySubscription::new())
+        .disable_introspection();
+
+    let query = "query { __schema { queryType { name } } }";
+
+    match juniper::execute_sync(query, None, &schema, &graphql_vars! {}, &()) {
+        Err(GraphQLError::ValidationError(errs)) => {
+            assert_eq!(
+                errs.first().unwrap().message(),
+                "GraphQL introspection is not allowed, but the operation contained `__schema`",
+            );
+        }
+        res => panic!("expected `ValidationError`, returned: {res:#?}"),
+    }
+}
+```
+> **NOTE**: Attempt to execute an [introspection query][1] results in [validation][11] error, rather than [execution][5] error.
+
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+
+[0]: https://spec.graphql.org/October2021#sec-Introspection
+[1]: https://spec.graphql.org/October2021#sec-Schema-Introspection
+[2]: https://spec.graphql.org/October2021#sel-GAFRJBABABF_jB
+[3]: https://spec.graphql.org/October2021#sel-GAFRJDABABI5C
+[4]: https://spec.graphql.org/October2021#sel-GAFRJFABABMvpN
+[5]: https://spec.graphql.org/October2021#sec-Execution
+[9]: https://docs.rs/juniper/latest/juniper/struct.RootNode.html#method.disable_introspection
+[10]: https://www.apollographql.com/blog/why-you-should-disable-graphql-introspection-in-production
+[11]: https://spec.graphql.org/October2021#sec-Validation
diff --git a/book/src/schema/schemas_and_mutations.md b/book/src/schema/schemas_and_mutations.md
deleted file mode 100644
index 716b76ce2..000000000
--- a/book/src/schema/schemas_and_mutations.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Schemas
-
-Juniper follows a [code-first approach][schema_approach] to defining GraphQL schemas. If you would like to use a [schema-first approach][schema_approach] instead, consider [juniper-from-schema][] for generating code from a schema file.
-
-A schema consists of three types: a query object, a mutation object, and a subscription object.
-These three define the root query fields, mutations and subscriptions of the schema, respectively.
-
-The usage of subscriptions is a little different from the mutation and query objects, so there is a specific [section][section] that discusses them.
-
-Both query and mutation objects are regular GraphQL objects, defined like any
-other object in Juniper. The mutation and subscription objects, however, are optional since schemas
-can be read-only and do not require subscriptions. If mutation/subscription functionality is not needed, consider using [EmptyMutation][EmptyMutation]/[EmptySubscription][EmptySubscription].
-
-In Juniper, the `RootNode` type represents a schema. When the schema is first created,
-Juniper will traverse the entire object graph
-and register all types it can find. This means that if you define a GraphQL
-object somewhere but never reference it, it will not be exposed in a schema.
-
-## The query root
-
-The query root is just a GraphQL object. You define it like any other GraphQL
-object in Juniper, most commonly using the `graphql_object` proc macro:
-
-```rust
-# #![allow(unused_variables)]
-# extern crate juniper;
-# use juniper::{graphql_object, FieldResult, GraphQLObject};
-# #[derive(GraphQLObject)] struct User { name: String }
-struct Root;
-
-#[graphql_object]
-impl Root {
-    fn userWithUsername(username: String) -> FieldResult<Option<User>> {
-        // Look up user in database...
-#       unimplemented!()
-    }
-}
-#
-# fn main() { }
-```
-
-## Mutations
-
-Mutations are _also_ just GraphQL objects. Each mutation is a single field
-that performs some mutating side-effect such as updating a database.
-
-```rust
-# #![allow(unused_variables)]
-# extern crate juniper;
-# use juniper::{graphql_object, FieldResult, GraphQLObject};
-# #[derive(GraphQLObject)] struct User { name: String }
-struct Mutations;
-
-#[graphql_object]
-impl Mutations {
-    fn signUpUser(name: String, email: String) -> FieldResult<User> {
-        // Validate inputs and save user in database...
-#       unimplemented!()
-    }
-}
-#
-# fn main() { }
-```
-
-# Converting a Rust schema to the [GraphQL Schema Language][schema_language]
-
-Many tools in the GraphQL ecosystem require the schema to be defined in the [GraphQL Schema Language][schema_language]. You can generate a [GraphQL Schema Language][schema_language] representation of your schema defined in Rust using the `schema-language` feature (on by default):
-
-```rust
-# extern crate juniper;
-use juniper::{
-    graphql_object, EmptyMutation, EmptySubscription, FieldResult, RootNode,
-};
-
-struct Query;
-
-#[graphql_object]
-impl Query {
-    fn hello(&self) -> FieldResult<&str> {
-        Ok("hello world")
-    }
-}
-
-fn main() {
-    // Define our schema in Rust.
-    let schema = RootNode::new(
-        Query,
-        EmptyMutation::<()>::new(),
-        EmptySubscription::<()>::new(),
-    );
-
-    // Convert the Rust schema into the GraphQL Schema Definition Language.
-    let result = schema.as_sdl();
-
-    let expected = "\
-schema {
-  query: Query
-}
-
-type Query {
-  hello: String!
-}
-";
-#   #[cfg(not(target_os = "windows"))]
-    assert_eq!(result, expected);
-}
-```
-
-Note the `schema-language` feature may be turned off if you do not need this functionality to reduce dependencies and speed up
-compile times.
-
-
-[schema_language]: https://graphql.org/learn/schema/#type-language
-[juniper-from-schema]: https://github.com/davidpdrsn/juniper-from-schema
-[schema_approach]: https://blog.logrocket.com/code-first-vs-schema-first-development-graphql/
-[section]: ../advanced/subscriptions.md
-[EmptyMutation]: https://docs.rs/juniper/0.14.2/juniper/struct.EmptyMutation.html
-<!--TODO: Fix This URL when the EmptySubscription become available in the Documentation  -->
-[EmptySubscription]: https://docs.rs/juniper/0.14.2/juniper/struct.EmptySubscription.html
diff --git a/book/src/schema/subscriptions.md b/book/src/schema/subscriptions.md
new file mode 100644
index 000000000..0bd261934
--- /dev/null
+++ b/book/src/schema/subscriptions.md
@@ -0,0 +1,176 @@
+Subscriptions
+=============
+
+[GraphQL subscriptions][9] are a way to push data from a server to clients requesting real-time messages from a server. [Subscriptions][9] are similar to [queries][7] in that they specify a set of fields to be delivered to a client, but instead of immediately returning a single answer a result is sent every time a particular event happens on a server.
+
+In order to execute [subscriptions][9] in [Juniper], we need a coordinator (spawning long-lived connections) and a [GraphQL object][4] with [fields][5] resolving into a [`Stream`] of elements which will then be returned to a client. The [`juniper_subscriptions` crate][30] provides a default implementation of these abstractions.
+
+The [subscription root][3] is just a [GraphQL object][4], similar to the [query root][1] and [mutations root][2] that we define for operations in our [GraphQL schema][0]. For [subscriptions][9] all fields should be `async` and return a [`Stream`] of some [GraphQL type][6] values, rather than direct values.
+
+```rust
+# extern crate futures;
+# extern crate juniper;
+# use std::pin::Pin;
+# use futures::Stream;
+# use juniper::{graphql_object, graphql_subscription, FieldError};
+#
+# #[derive(Clone)]
+# pub struct Database;
+#
+# impl juniper::Context for Database {}
+#
+# pub struct Query;
+#
+# #[graphql_object]
+# #[graphql(context = Database)]
+# impl Query {
+#    fn hello_world() -> &'static str {
+#        "Hello World!"
+#    }
+# }
+#
+type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
+
+pub struct Subscription;
+
+#[graphql_subscription]
+#[graphql(context = Database)]
+impl Subscription {
+    // This subscription operation emits two values sequentially:
+    // the `String`s "Hello" and "World!".
+    async fn hello_world() -> StringStream {
+        let stream = futures::stream::iter([
+            Ok(String::from("Hello")),
+            Ok(String::from("World!")),
+        ]);
+        Box::pin(stream)
+    }
+}
+#
+# fn main () {}
+```
+
+
+
+
+## Coordinator
+
+[GraphQL subscriptions][9] require a bit more resources than regular [queries][7] and provide a great vector for [DoS attacks][20]. This can can bring down a server easily if not handled correctly. The [`SubscriptionCoordinator` trait][`SubscriptionCoordinator`] provides coordination logic to enable functionality like [DoS attacks][20] mitigation and resource limits.
+
+The [`SubscriptionCoordinator`] contains the [schema][0] and can keep track of opened connections, handle [subscription][9] start and end, and maintain a global ID for each [subscription][9]. Each time a connection is established, the [`SubscriptionCoordinator`] spawns a [32], which handles a single connection, providing resolver logic for a client stream as well as reconnection and shutdown logic.
+
+While we can implement [`SubscriptionCoordinator`] ourselves, [Juniper] contains a simple and generic implementation called [`Coordinator`]. The `subscribe` method returns a [`Future`] resolving into a `Result<Connection, GraphQLError>`, where [`Connection`] is a [`Stream`] of [values][10] returned by the operation, and a [`GraphQLError`] is the error when the [subscription operation][9] fails.
+
+```rust
+# extern crate futures;
+# extern crate juniper;
+# extern crate juniper_subscriptions;
+# extern crate serde_json;
+# use std::pin::Pin;
+# use futures::{Stream, StreamExt as _};
+# use juniper::{
+#     http::GraphQLRequest,
+#     graphql_object, graphql_subscription, 
+#     DefaultScalarValue, EmptyMutation, FieldError, 
+#     RootNode, SubscriptionCoordinator,
+# };
+# use juniper_subscriptions::Coordinator;
+# 
+# #[derive(Clone)]
+# pub struct Database;
+# 
+# impl juniper::Context for Database {}
+# 
+# impl Database {
+#     fn new() -> Self {
+#         Self
+#     }
+# }
+# 
+# pub struct Query;
+# 
+# #[graphql_object]
+# #[graphql(context = Database)]
+# impl Query {
+#     fn hello_world() -> &'static str {
+#         "Hello World!"
+#     }
+# }
+#
+# type StringStream = Pin<Box<dyn Stream<Item = Result<String, FieldError>> + Send>>;
+#
+# pub struct Subscription;
+# 
+# #[graphql_subscription]
+# #[graphql(context = Database)]
+# impl Subscription {
+#     async fn hello_world() -> StringStream {
+#         let stream = futures::stream::iter([
+#             Ok(String::from("Hello")), 
+#             Ok(String::from("World!")),
+#         ]);
+#         Box::pin(stream)
+#     }
+# }
+#
+type Schema = RootNode<'static, Query, EmptyMutation<Database>, Subscription>;
+
+fn schema() -> Schema {
+    Schema::new(Query, EmptyMutation::new(), Subscription)
+}
+
+async fn run_subscription() {
+    let schema = schema();
+    let coordinator = Coordinator::new(schema);
+    let db = Database::new();
+
+    let req: GraphQLRequest<DefaultScalarValue> = serde_json::from_str(
+        r#"{
+            "query": "subscription { helloWorld }"
+        }"#,
+    ).unwrap();
+    
+    let mut conn = coordinator.subscribe(&req, &db).await.unwrap();
+    while let Some(result) = conn.next().await {
+        println!("{}", serde_json::to_string(&result).unwrap());
+    }
+}
+#
+# fn main() {}
+```
+
+
+
+
+## WebSocket
+
+For information about serving [GraphQL subscriptions][9] over [WebSocket], see the ["Serving" chapter](../serve/index.md#websocket).
+
+
+
+
+[`Coordinator`]: https://docs.rs/juniper_subscriptions/latest/juniper_subscriptions/struct.Coordinator.html
+[`Connection`]: https://docs.rs/juniper_subscriptions/latest/juniper_subscriptions/struct.Connection.html
+[`Future`]: https://doc.rust-lang.org/stable/std/future/trait.Future.html
+[`GraphQLError`]: https://docs.rs/juniper/latest/juniper/enum.GraphQLError.html
+[`Stream`]: https://docs.rs/futures/latest/futures/stream/trait.Stream.html
+[`SubscriptionCoordinator`]:  https://docs.rs/juniper/latest/juniper/trait.SubscriptionCoordinator.html
+[`SubscriptionConnection`]: https://docs.rs/juniper/latest/juniper/trait.SubscriptionConnection.html
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[WebSocket]: https://en.wikipedia.org/wiki/WebSocket
+
+[0]: https://spec.graphql.org/October2021#sec-Schema
+[1]: https://spec.graphql.org/October2021#sel-FAHTRFCAACChCtpG
+[2]: https://spec.graphql.org/October2021#sel-FAHTRHCAACCuE9yD
+[3]: https://spec.graphql.org/October2021#sel-FAHTRJCAACC3EhsX
+[4]: https://spec.graphql.org/October2021#sec-Objects
+[5]: https://spec.graphql.org/October2021#sec-Language.Fields
+[6]: https://spec.graphql.org/October2021#sec-Types
+[7]: https://spec.graphql.org/October2021#sec-Query
+[8]: https://spec.graphql.org/October2021#sec-Mutation
+[9]: https://spec.graphql.org/October2021#sec-Subscription
+[10]: https://spec.graphql.org/October2021#sec-Values
+[20]: https://en.wikipedia.org/wiki/Denial-of-service_attack
+[30]: https://docs.rs/juniper_subscriptions
diff --git a/book/src/serve/batching.md b/book/src/serve/batching.md
new file mode 100644
index 000000000..713c26978
--- /dev/null
+++ b/book/src/serve/batching.md
@@ -0,0 +1,81 @@
+Batching
+========
+
+The [GraphQL] standard generally assumes that there will be one server request per each client operation to perform (such as a query or mutation). This is conceptually simple but potentially inefficient.
+
+Some client libraries (such as [`apollo-link-batch-http`][1]) have the ability to batch operations in a single [HTTP] request to save network round-trips and potentially increase performance. There are [some tradeoffs][3], though, that should be considered before [batching operations][2].
+
+[Juniper]'s [server integration crates](index.md#officially-supported) support [batching multiple operations][2] in a single [HTTP] request out-of-the-box via [JSON] arrays. This makes them compatible with client libraries that support [batch operations][2] without any special configuration.
+
+> **NOTE**: If you use a custom server integration, it's **not a hard requirement** to support [batching][2], as it's not a part of the [official GraphQL specification][0].
+
+Assuming an integration supports [operations batching][2], for the following GraphQL query:
+```graphql
+{
+  hero {
+    name
+  }
+}
+```
+
+The [JSON] `data` to [POST] for an individual request would be:
+```json
+{
+  "query": "{hero{name}}"
+}
+```
+And the response would be in the form:
+```json
+{
+  "data": {
+    "hero": {
+      "name": "R2-D2"
+    }
+  }
+}
+```
+
+However, if we want to run the same query twice in a single [HTTP] request, the batched [JSON] `data` to [POST] would be:
+```json
+[
+  {
+    "query": "{hero{name}}"
+  },
+  {
+    "query": "{hero{name}}"
+  }
+]
+```
+And then, the response would be in the following array form:
+```json
+[
+  {
+    "data": {
+      "hero": {
+        "name": "R2-D2"
+      }
+    }
+  },
+  {
+    "data": {
+      "hero": {
+        "name": "R2-D2"
+      }
+    }
+  }
+]
+```
+
+
+
+
+[GraphQL]: https://graphql.org
+[HTTP]: https://en.wikipedia.org/wiki/HTTP
+[JSON]: https://www.json.org
+[Juniper]: https://docs.rs/juniper
+[POST]: https://en.wikipedia.org/wiki/POST_(HTTP)
+
+[0]: https://spec.graphql.org/October2021
+[1]: https://www.apollographql.com/docs/link/links/batch-http.html
+[2]: https://www.apollographql.com/blog/batching-client-graphql-queries
+[3]: https://www.apollographql.com/blog/batching-client-graphql-queries#what-are-the-tradeoffs-with-batching
diff --git a/book/src/serve/index.md b/book/src/serve/index.md
new file mode 100644
index 000000000..75dd7f8c2
--- /dev/null
+++ b/book/src/serve/index.md
@@ -0,0 +1,69 @@
+Serving
+=======
+
+Once we have built a [GraphQL schema][1], the next obvious step would be to serve it, so clients can interact with our [GraphQL] API. Usually, [GraphQL] APIs are served via [HTTP]. 
+
+
+
+
+## Web server frameworks
+
+Though the [`juniper`] crate doesn't provide a built-in [HTTP] server, the surrounding ecosystem does.
+
+
+### Officially supported
+
+[Juniper] officially supports the following widely used and adopted web server frameworks in [Rust] ecosystem:
+- [`actix-web`] ([`juniper_actix`] crate)
+- [`axum`] ([`juniper_axum`] crate)
+- [`hyper`] ([`juniper_hyper`] crate)
+- [`rocket`] ([`juniper_rocket`] crate)
+- [`warp`] ([`juniper_warp`] crate)
+
+See their API docs and usage examples (accessible from API docs) for further details of how they should be used.
+
+> **NOTE**: All the officially supported web server framework integrations provide a simple and convenient way for exposing [GraphiQL] and/or [GraphQL Playground] with the [GraphQL schema][1] along. These powerful tools ease the development process by enabling you to explore and send client requests to the [GraphQL] API under development.
+
+
+
+
+## WebSocket
+
+> **NOTE**: [WebSocket] is a crucial part for serving [GraphQL subscriptions][2] over [HTTP].
+
+There are two widely adopted protocols for serving [GraphQL] over [WebSocket]:
+1. [Legacy `graphql-ws` GraphQL over WebSocket Protocol][ws-old], formerly used by [Apollo] and the [`subscriptions-transport-ws` npm package], and now being deprecated.
+2. [New `graphql-transport-ws` GraphQL over WebSocket Protocol][ws-new], provided by the [`graphql-ws` npm package] and being used by [Apollo] as for now.
+
+In the [Juniper] ecosystem, both implementations are provided by the [`juniper_graphql_ws`] crate. Most of the [officially supported web server framework integrations](#officially-supported) are able to serve a [GraphQL schema][1] over [WebSocket] (including [subscriptions][2]) and even support [auto-negotiation of the correct protocol based on the `Sec-Websocket-Protocol` HTTP header value][3]. See their API docs and usage examples (accessible from API docs) for further details of how to do so.
+
+
+
+
+[`actix-web`]: https://docs.rs/actix-web
+[`axum`]: https://docs.rs/axum
+[`graphql-ws` npm package]: https://npmjs.com/package/graphql-ws
+[`juniper`]: https://docs.rs/juniper
+[`juniper_actix`]: https://docs.rs/juniper_actix
+[`juniper_axum`]: https://docs.rs/juniper_axum
+[`juniper_graphql_ws`]: https://docs.rs/juniper_graphql_ws
+[`juniper_rocket`]: https://docs.rs/juniper_rocket
+[`juniper_warp`]: https://docs.rs/juniper_warp
+[`hyper`]: https://docs.rs/hyper
+[`rocket`]: https://docs.rs/rocket
+[`subscriptions-transport-ws` npm package]: https://npmjs.com/package/subscriptions-transport-ws
+[`warp`]: https://docs.rs/warp
+[Apollo]: https://www.apollographql.com
+[GraphiQL]: https://github.com/graphql/graphiql
+[GraphQL]: https://graphql.org
+[GraphQL Playground]: https://github.com/prisma/graphql-playground
+[HTTP]: https://en.wikipedia.org/wiki/HTTP
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[WebSocket]: https://en.wikipedia.org/wiki/WebSocket
+[ws-new]: https://github.com/enisdenjo/graphql-ws/blob/v5.14.0/PROTOCOL.md
+[ws-old]: https://github.com/apollographql/subscriptions-transport-ws/blob/v0.11.0/PROTOCOL.md
+
+[1]: ../schema/index.md
+[2]: ../schema/subscriptions.md
+[3]: https://developer.mozilla.org/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols
\ No newline at end of file
diff --git a/book/src/servers/hyper.md b/book/src/servers/hyper.md
deleted file mode 100644
index f53f25c8d..000000000
--- a/book/src/servers/hyper.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Integrating with Hyper
-
-[Hyper] is a fast HTTP implementation that many other Rust web frameworks
-leverage. It offers asynchronous I/O via the tokio runtime and works on
-Rust's stable channel.
-
-Hyper is not a higher-level web framework and accordingly
-does not include ergonomic features such as simple endpoint routing,
-baked-in HTTP responses, or reusable middleware. For GraphQL, those aren't
-large downsides as all POSTs and GETs usually go through a single endpoint with
-a few clearly-defined response payloads.
-
-Juniper's Hyper integration is contained in the [`juniper_hyper`][juniper_hyper] crate:
-
-!FILENAME Cargo.toml
-
-```toml
-[dependencies]
-juniper = "0.16.0"
-juniper_hyper = "0.9.0"
-```
-
-Included in the source is a [small example][example] which sets up a basic GraphQL and [GraphiQL] handler.
-
-[graphiql]: https://github.com/graphql/graphiql
-[hyper]: https://hyper.rs/
-[juniper_hyper]: https://github.com/graphql-rust/juniper/tree/master/juniper_hyper
-[example]: https://github.com/graphql-rust/juniper/blob/master/juniper_hyper/examples/hyper_server.rs
diff --git a/book/src/servers/index.md b/book/src/servers/index.md
deleted file mode 100644
index 4f03e0d98..000000000
--- a/book/src/servers/index.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Adding A Server
-
-To allow using Juniper with the HTTP server of your choice,
-it does **not** come with a built in HTTP server.
-
-To actually get a server up and running, there are multiple official and 
-third-party integration crates that will get you there.
-
-- [Official Server Integrations](official.md)
-    - [Warp](warp.md)
-    - [Rocket](rocket.md)
-    - [Hyper](hyper.md)
-- [Third Party Integrations](third-party.md)
-    - [Actix-Web](https://github.com/actix/examples/tree/master/graphql/juniper)
-    - [Finchers](https://github.com/finchers-rs/finchers-juniper)
-    - [Tsukuyomi](https://github.com/tsukuyomi-rs/tsukuyomi/tree/master/examples/juniper)
diff --git a/book/src/servers/official.md b/book/src/servers/official.md
deleted file mode 100644
index 690fc2fca..000000000
--- a/book/src/servers/official.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Official Server Integrations
-
-Juniper provides official integration crates for several popular Rust server
-libraries.
-
-- [Warp](warp.md)
-- [Rocket](rocket.md)
-- [Hyper](hyper.md)
diff --git a/book/src/servers/rocket.md b/book/src/servers/rocket.md
deleted file mode 100644
index fe2f6cfbb..000000000
--- a/book/src/servers/rocket.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Integrating with Rocket
-
-[Rocket] is a web framework for Rust that makes it simple to write fast web applications without sacrificing flexibility or type safety. All with minimal code. Rocket
-does not work on Rust's stable channel and instead requires the nightly
-channel.
-
-Juniper's Rocket integration is contained in the [`juniper_rocket`][juniper_rocket] crate:
-
-!FILENAME Cargo.toml
-
-```toml
-[dependencies]
-juniper = "0.16.0"
-juniper_rocket = "0.9.0"
-```
-
-Included in the source is a [small example][example] which sets up a basic GraphQL and [GraphiQL] handler.
-
-[graphiql]: https://github.com/graphql/graphiql
-[rocket]: https://rocket.rs/
-[juniper_rocket]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket
-[example]: https://github.com/graphql-rust/juniper/blob/master/juniper_rocket/examples/simple.rs
diff --git a/book/src/servers/third-party.md b/book/src/servers/third-party.md
deleted file mode 100644
index feee6b94b..000000000
--- a/book/src/servers/third-party.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Other Examples
-
-These examples are not officially maintained by Juniper developers.
-
-- [Actix Web](https://github.com/actix/examples/tree/HEAD/graphql/juniper) | [Actix Web (advanced)](https://github.com/actix/examples/tree/HEAD/graphql/juniper-advanced)
diff --git a/book/src/servers/warp.md b/book/src/servers/warp.md
deleted file mode 100644
index 70ea945ae..000000000
--- a/book/src/servers/warp.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Integrating with Warp
-
-[Warp] is a super-easy, composable, web server framework for warp speeds.
-The fundamental building block of warp is the Filter: they can be combined and composed to express rich requirements on requests. Warp is built on [Hyper] and works on
-Rust's stable channel.
-
-Juniper's Warp integration is contained in the [`juniper_warp`][juniper_warp] crate:
-
-!FILENAME Cargo.toml
-
-```toml
-[dependencies]
-juniper = "0.16.0"
-juniper_warp = "0.8.0"
-```
-
-Included in the source is a [small example][example] which sets up a basic GraphQL and [GraphiQL]/[GraphQL Playground] handlers with subscriptions support.
-
-[GraphiQL]: https://github.com/graphql/graphiql
-[GraphQL Playground]: https://github.com/prisma/graphql-playground
-[hyper]: https://hyper.rs/
-[warp]: https://crates.io/crates/warp
-[juniper_warp]: https://github.com/graphql-rust/juniper/tree/master/juniper_warp
-[example]: https://github.com/graphql-rust/juniper/blob/master/juniper_warp/examples/subscription.rs
diff --git a/book/src/types/enums.md b/book/src/types/enums.md
index a818b1fe0..947039bed 100644
--- a/book/src/types/enums.md
+++ b/book/src/types/enums.md
@@ -1,73 +1,151 @@
-# Enums
+Enums
+=====
 
-Enums in GraphQL are string constants grouped together to represent a set of
-possible values. Simple Rust enums can be converted to GraphQL enums by using a
-custom derive attribute:
+> [GraphQL enum][0] types, like [scalar][1] types, also represent leaf values in a GraphQL type system. However [enum][0] types describe the set of possible values.
+>
+> [Enums][0] are not references for a numeric value, but are unique values in their own right. They may serialize as a string: the name of the represented value.
 
+With [Juniper] a [GraphQL enum][0] may be defined by using the [`#[derive(GraphQLEnum)]`][2] attribute on a [Rust enum][3] as long as its variants do not have any fields:
 ```rust
 # extern crate juniper;
-#[derive(juniper::GraphQLEnum)]
+# use juniper::GraphQLEnum;
+#
+#[derive(GraphQLEnum)]
 enum Episode {
     NewHope,
     Empire,
     Jedi,
 }
-
+#
 # fn main() {}
 ```
 
-Juniper converts all enum variants to uppercase, so the corresponding string
-values for these variants are `NEWHOPE`, `EMPIRE`, and `JEDI`, respectively. If
-you want to override this, you can use the `graphql` attribute, similar to how
-it works when [defining objects](objects/defining_objects.md):
 
+### Renaming
+
+By default, [enum][3] variants are converted from [Rust]'s standard `PascalCase` naming convention into [GraphQL]'s `SCREAMING_SNAKE_CASE` convention:
 ```rust
 # extern crate juniper;
-#[derive(juniper::GraphQLEnum)]
+# use juniper::GraphQLEnum;
+#
+#[derive(GraphQLEnum)]
 enum Episode {
-    #[graphql(name="NEW_HOPE")]
-    NewHope,
+    NewHope, // exposed as `NEW_HOPE` in GraphQL schema
+    Empire,  // exposed as `EMPIRE` in GraphQL schema
+    Jedi,    // exposed as `JEDI` in GraphQL schema
+}
+#
+# fn main() {}
+```
+
+We can override the name by using the `#[graphql(name = "...")]` attribute:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLEnum;
+#
+#[derive(GraphQLEnum)]
+#[graphql(name = "WrongEpisode")] // now exposed as `WrongEpisode` in GraphQL schema
+enum Episode {
+    #[graphql(name = "LAST_HOPE")]
+    NewHope, // exposed as `LAST_HOPE` in GraphQL schema
     Empire,
     Jedi,
 }
+#
+# fn main() {}
+```
 
+Or provide a different renaming policy for all the [enum][3] variants:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLEnum;
+#
+#[derive(GraphQLEnum)]
+#[graphql(rename_all = "none")] // disables any renaming
+enum Episode {
+    NewHope, // exposed as `NewHope` in GraphQL schema
+    Empire,  // exposed as `Empire` in GraphQL schema
+    Jedi,    // exposed as `Jedi` in GraphQL schema
+}
+#
 # fn main() {}
 ```
+> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
 
-## Documentation and deprecation
 
-Just like when defining objects, the type itself can be renamed and documented,
-while individual enum variants can be renamed, documented, and deprecated:
+### Documentation and deprecation
 
+Just like when [defining GraphQL objects](objects/index.md#documentation), the [GraphQL enum][0] type and its values could be [documented][4] and [deprecated][5] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
 ```rust
 # extern crate juniper;
-#[derive(juniper::GraphQLEnum)]
-#[graphql(name="Episode", description="An episode of Star Wars")]
+# use juniper::GraphQLEnum;
+#
+/// This doc comment is visible only in Rust API docs.
+#[derive(GraphQLEnum)]
+#[graphql(description = "An episode of Star Wars")]
 enum StarWarsEpisode {
-    #[graphql(deprecated="We don't really talk about this one")]
-    ThePhantomMenace,
-
-    #[graphql(name="NEW_HOPE")]
+    /// This doc comment is visible only in Rust API docs.
+    #[graphql(description = "This description is visible only in GraphQL schema.")]
     NewHope,
 
-    #[graphql(description="Arguably the best one in the trilogy")]
+    /// This doc comment is visible only in Rust API docs.
+    #[graphql(desc = "Arguably the best one in the trilogy.")]
+    //        ^^^^ shortcut for a `description` argument
     Empire,
+
+    /// This doc comment is visible in both Rust API docs and GraphQL schema 
+    /// descriptions.
     Jedi,
+    
+    #[deprecated(note = "Only visible in Rust.")]
+    #[graphql(deprecated = "We don't really talk about this one.")]
+    //        ^^^^^^^^^^ takes precedence over Rust's `#[deprecated]` attribute
+    ThePhantomMenace, // has no description in GraphQL schema
 }
+#
+# fn main() {}
+```
+> **NOTE**: Only [GraphQL object][6]/[interface][7] fields and [GraphQL enum][0] values can be [deprecated][5].
+
 
+### Ignoring
+
+By default, all [enum][3] variants are included in the generated [GraphQL enum][0] type as values. To prevent including a specific variant, annotate it with the `#[graphql(ignore)]` attribute:
+```rust
+# #![allow(dead_code)]
+# extern crate juniper;
+# use juniper::GraphQLEnum;
+#
+#[derive(GraphQLEnum)]
+enum Episode<T> {
+    NewHope,
+    Empire,
+    Jedi,
+    #[graphql(ignore)]
+    Legends(T),   // cannot be queried from GraphQL
+    #[graphql(skip)]
+    //        ^^^^ alternative naming, up to your preference
+    CloneWars(T), // cannot be queried from GraphQL
+}
+#
 # fn main() {}
 ```
 
-## Supported Macro Attributes (Derive)
-
-| Name of Attribute | Container Support | Field Support    |
-|-------------------|:-----------------:|:----------------:|
-| context           | ✔                 | ?                |
-| deprecated        | ✔                 | ✔                |
-| description       | ✔                 | ✔                |
-| interfaces        | ?                 | ✘                |
-| name              | ✔                 | ✔                |
-| noasync           | ✔                 | ?                |
-| scalar            | ✘                 | ?                |
-| skip              | ?                 | ✘                |
-| ✔: supported      | ✘: not supported  | ?: not available |
+> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLEnum)]`][2] attribute.
+
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Enums
+[1]: https://spec.graphql.org/October2021#sec-Scalars
+[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLEnum.html
+[3]: https://doc.rust-lang.org/reference/items/enumerations.html
+[4]: https://spec.graphql.org/October2021#sec-Descriptions
+[5]: https://spec.graphql.org/October2021#sec--deprecated
+[6]: https://spec.graphql.org/October2021#sec-Objects
+[7]: https://spec.graphql.org/October2021#sec-Interfaces
+[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
\ No newline at end of file
diff --git a/book/src/types/index.md b/book/src/types/index.md
index 560c70956..4b00e7114 100644
--- a/book/src/types/index.md
+++ b/book/src/types/index.md
@@ -1,20 +1,28 @@
-# Type System
-
-Most of the work in working with juniper consists of mapping the 
-GraphQL type system to the Rust types your application uses.
-
-Juniper provides some convenient abstractions that try to make this process
-as painless as possible.
-
-Find out more in the individual chapters below.
-
-- [Defining objects](objects/defining_objects.md)
-  - [Complex fields](objects/complex_fields.md)
-  - [Using contexts](objects/using_contexts.md)
-  - [Error handling](objects/error_handling.md)
-- [Other types](other-index.md)
-  - [Enums](enums.md)
-  - [Interfaces](interfaces.md)
-  - [Input objects](input_objects.md)
-  - [Scalars](scalars.md)
-  - [Unions](unions.md)
+Type system
+===========
+
+Most of the work in working with [Juniper] consists of mapping the [GraphQL type system][0] to the [Rust] types our application uses.
+
+[Juniper] provides some convenient abstractions making this process as painless as possible.
+
+Find out more in the individual chapters below:
+- [Objects](objects/index.md)
+    - [Complex fields](objects/complex_fields.md)
+    - [Context](objects/Context.md)
+    - [Error handling](objects/error/index.md)
+        - [Field errors](objects/error/field.md)
+        - [Schema errors](objects/error/schema.md)
+    - [Generics](objects/generics.md)
+- [Interfaces](interfaces.md)
+- [Unions](unions.md)
+- [Enums](enums.md)
+- [Input objects](input_objects.md)
+- [Scalars](scalars.md)
+
+
+
+
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Type-System
diff --git a/book/src/types/input_objects.md b/book/src/types/input_objects.md
index ef103aacf..a80509bc7 100644
--- a/book/src/types/input_objects.md
+++ b/book/src/types/input_objects.md
@@ -1,62 +1,163 @@
-# Input objects
+Input objects
+=============
 
-Input objects are complex data structures that can be used as arguments to
-GraphQL fields. In Juniper, you can define input objects using a custom derive
-attribute, similar to simple objects and enums:
+> [Fields][4] may accept [arguments][5] to configure their behavior. These inputs are often [scalars][12] or [enums][10], but they sometimes need to represent more complex values.
+>
+> A [GraphQL input object][0] defines a set of input fields; the input fields are either [scalars][12], [enums][10], or other [input objects][0]. This allows [arguments][5] to accept arbitrarily complex structs.
 
+In [Juniper], defining a [GraphQL input object][0] is quite straightforward and similar to how [trivial GraphQL objects are defined](objects/index.md) - by using the [`#[derive(GraphQLInputObject)]` attribute][2] on a [Rust struct][struct]:
 ```rust
 # #![allow(unused_variables)]
 # extern crate juniper;
-#[derive(juniper::GraphQLInputObject)]
+# use juniper::{graphql_object, GraphQLInputObject, GraphQLObject};
+#
+#[derive(GraphQLInputObject)]
 struct Coordinate {
     latitude: f64,
     longitude: f64
 }
 
 struct Root;
-# #[derive(juniper::GraphQLObject)] struct User { name: String }
+# #[derive(GraphQLObject)] struct User { name: String }
 
-#[juniper::graphql_object]
+#[graphql_object]
 impl Root {
     fn users_at_location(coordinate: Coordinate, radius: f64) -> Vec<User> {
         // Send coordinate to database
         // ...
-# unimplemented!()
+#       unimplemented!()
     }
 }
+#
+# fn main() {}
+```
+
+
+### Renaming
+
+Just as with [defining GraphQL objects](objects/index.md#renaming), by default [struct] fields are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLInputObject;
+#
+#[derive(GraphQLInputObject)]
+struct Person {
+    first_name: String, // exposed as `firstName` in GraphQL schema
+    last_name: String,  // exposed as `lastName` in GraphQL schema
+}
+#
+# fn main() {}
+```
 
+We can override the name by using the `#[graphql(name = "...")]` attribute:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLInputObject;
+#
+#[derive(GraphQLInputObject)]
+#[graphql(name = "WebPerson")] // now exposed as `WebPerson` in GraphQL schema
+struct Person {
+    name: String,
+    age: i32,
+    #[graphql(name = "websiteURL")]
+    website_url: Option<String>, // now exposed as `websiteURL` in GraphQL schema
+}
+#
+# fn main() {}
+```
+
+Or provide a different renaming policy for all the [struct] fields:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLInputObject;
+#
+#[derive(GraphQLInputObject)]
+#[graphql(rename_all = "none")] // disables any renaming
+struct Person {
+    name: String,
+    age: i32,
+    website_url: Option<String>, // exposed as `website_url` in GraphQL schema
+}
+#
 # fn main() {}
 ```
+> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
 
-## Documentation and renaming
 
-Just like the [other](objects/defining_objects.md) [derives](enums.md), you can rename
-and add documentation to both the type and the fields:
+### Documentation
 
+Similarly, [GraphQL descriptions][7] may be provided by either using [Rust doc comments][6] or with the `#[graphql(description = "...")]` attribute:
 ```rust
-# #![allow(unused_variables)]
 # extern crate juniper;
-#[derive(juniper::GraphQLInputObject)]
-#[graphql(name="Coordinate", description="A position on the globe")]
-struct WorldCoordinate {
-    #[graphql(name="lat", description="The latitude")]
-    latitude: f64,
+# use juniper::GraphQLInputObject;
+#
+/// This doc comment is visible only in Rust API docs.
+#[derive(GraphQLInputObject)]
+#[graphql(description = "This description is visible only in GraphQL schema.")]
+struct Person {
+    /// This doc comment is visible only in Rust API docs.
+    #[graphql(desc = "This description is visible only in GraphQL schema.")]
+    //        ^^^^ shortcut for a `description` argument
+    name: String,
 
-    #[graphql(name="long", description="The longitude")]
-    longitude: f64
+    /// This doc comment is visible in both Rust API docs and GraphQL schema 
+    /// descriptions.
+    age: i32,
 }
+#
+# fn main() {}
+```
+> **NOTE**: As of [October 2021 GraphQL specification][spec], [GraphQL input object][0]'s fields **cannot be** [deprecated][9].
 
-struct Root;
-# #[derive(juniper::GraphQLObject)] struct User { name: String }
 
-#[juniper::graphql_object]
-impl Root {
-    fn users_at_location(coordinate: WorldCoordinate, radius: f64) -> Vec<User> {
-        // Send coordinate to database
-        // ...
-# unimplemented!()
-    }
+### Ignoring
+
+By default, all [struct] fields are included into the generated [GraphQL input object][0] type. To prevent inclusion of a specific field annotate it with the `#[graphql(ignore)]` attribute:
+> **WARNING**: Ignored fields must either implement `Default` or be annotated with the `#[graphql(default = <expression>)]` argument.
+```rust
+# extern crate juniper;
+# use juniper::GraphQLInputObject;
+#
+enum System {
+    Cartesian,
 }
 
+#[derive(GraphQLInputObject)]
+struct Point2D {
+    x: f64,
+    y: f64,
+    #[graphql(ignore, default = System::Cartesian)]
+    //                ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    // This attribute is required, as we need to be able to construct
+    // a `Point2D` value from the `{ x: 0.0, y: 0.0 }` GraphQL input value,
+    // received from client-side.
+    system: System,
+    // `Default::default()` value is used, if no 
+    // `#[graphql(default = <expression>)]` is specified.
+    #[graphql(skip)]
+    //        ^^^^ alternative naming, up to your preference
+    shift: f64, 
+}
+#
 # fn main() {}
 ```
+
+> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLInputObject)]`][2] attribute.
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[struct]: https://doc.rust-lang.org/reference/items/structs.html
+[spec]: https://spec.graphql.org/October2021
+
+[0]: https://spec.graphql.org/October2021#sec-Input-Objects
+[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLInputObject.html
+[4]: https://spec.graphql.org/October2021#sec-Language.Fields
+[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
+[6]: https://doc.rust-lang.org/reference/comments.html#doc-comments
+[7]: https://spec.graphql.org/October2021#sec-Descriptions
+[9]: https://spec.graphql.org/October2021#sec--deprecated
+[10]: https://spec.graphql.org/October2021#sec-Enums
+[12]: https://spec.graphql.org/October2021#sec-Scalars
diff --git a/book/src/types/interfaces.md b/book/src/types/interfaces.md
index 1ae086d3a..6ce5fda0b 100644
--- a/book/src/types/interfaces.md
+++ b/book/src/types/interfaces.md
@@ -1,76 +1,45 @@
 Interfaces
 ==========
 
-[GraphQL interfaces][1] map well to interfaces known from common object-oriented languages such as Java or C#, but Rust, unfortunately, has no concept that maps perfectly to them. The nearest analogue of [GraphQL interfaces][1] are Rust traits, and the main difference is that in GraphQL an [interface type][1] serves both as an _abstraction_ and a _boxed value (downcastable to concrete implementers)_, while in Rust, a trait is an _abstraction only_ and _to represent such a boxed value a separate type is required_, like enum or trait object, because Rust trait doesn't represent a type itself, and so can have no values. This difference imposes some unintuitive and non-obvious corner cases when we try to express [GraphQL interfaces][1] in Rust, but on the other hand gives you full control over which type is backing your interface, and how it's resolved.
+> [GraphQL interfaces][0] represent a list of named [fields][4] and their [arguments][5]. [GraphQL objects][10] and [interfaces][0] can then implement these [interfaces][0] which requires that the implementing type will define all [fields][4] defined by those [interfaces][0].
 
-For implementing [GraphQL interfaces][1] Juniper provides the `#[graphql_interface]` macro.
+[GraphQL interfaces][0] map well to interfaces known from common object-oriented languages such as Java or C#, but [Rust], unfortunately, has no concept that maps perfectly to them. The nearest analogue of [GraphQL interfaces][0] are [Rust traits][20], but the main difference is that in [GraphQL] an [interface type][0] serves both as an _abstraction_ and a _boxed value (dispatchable to concrete implementers)_, while in [Rust], a [trait][20] is an _abstraction only_, and _to represent such a boxed value a separate type is required_, like a [trait object][21] or an [enum][22] consisting of implementer types, because [Rust trait][20] doesn't represent a type itself, and so, can have no values.
 
+Another notable difference is that [GraphQL interfaces][0] are more like [structurally-typed][30] contracts: they _only declare a list of [fields][4]_ a [GraphQL] type should already have. [Rust traits][20], on the other hand, are [type classes][31], which don't really care about existing methods, but, rather, _require to provide implementations for required methods_ despite the fact whether the type already has such methods or not. This difference makes the [trait implementation][23] not a good fit for expressing a [GraphQL interface][0] implementation, because _we don't really need to implement any [fields][4]_, the [GraphQL] type implementing a [GraphQL interface][0] has those [fields][4] already. _We only need to check that [fields'][4] signatures match_.
 
+That's why [Juniper] takes the following approach to represent [GraphQL interfaces][0], which consists of two parts:
+1. Either a [struct][24], or a [trait][20] (in case [fields][4] have [arguments][5]), which acts only as a blueprint describing the required list of [fields][4], and is not used in runtime at all.
+2. An auto-generated [enum][22], representing a dispatchable value-type for the [GraphQL interfaces][0], which may be referred and returned by other [fields][4].
 
-
-## Traits
-
-Defining a trait is mandatory for defining a [GraphQL interface][1], because this is the _obvious_ way we describe an _abstraction_ in Rust. All [interface][1] fields are defined as computed ones via trait methods.
-
+This may be done by using either the [`#[graphql_interface]` attribute][3] or the [`#[derive(GraphQLInterface)]`][2]:
 ```rust
 # extern crate juniper;
-use juniper::graphql_interface;
-
-#[graphql_interface]
-trait Character {
-    fn id(&self) -> &str;
-}
+# use juniper::{graphql_interface, GraphQLInterface, GraphQLObject};
 #
-# fn main() {}
-```
-
-However, to return values of such [interface][1], we should provide its implementers and the Rust type representing a _boxed value of this trait_. The last one can be represented in two flavors: enum and [trait object][2].
-
-
-### Enum values (default)
-
-By default, Juniper generates an enum representing the values of the defined [GraphQL interface][1], and names it straightforwardly, `{Interface}Value`.
-
-```rust
-# extern crate juniper;
-use juniper::{graphql_interface, GraphQLObject};
-
-#[graphql_interface(for = [Human, Droid])] // enumerating all implementers is mandatory 
-trait Character {
-    fn id(&self) -> &str;
-}
-
-#[derive(GraphQLObject)]
-#[graphql(impl = CharacterValue)] // notice enum name, NOT trait name
-struct Human {
-    id: String,
-}
-
-#[derive(GraphQLObject)]
-#[graphql(impl = CharacterValue)]
-struct Droid {
+// By default a `CharacterValue` enum is generated by macro to represent
+// values of this GraphQL interface.
+#[derive(GraphQLInterface)]
+#[graphql(for = Human)] // enumerating all implementers is mandatory
+struct Character {
     id: String,
 }
-#
-# fn main() {}
-```
 
-Also, enum name can be specified explicitly, if desired.
-
-```rust
-# extern crate juniper;
-use juniper::{graphql_interface, GraphQLObject};
-
-#[graphql_interface(enum = CharacterInterface, for = Human)] 
-trait Character {
-    fn id(&self) -> &str;
+// Using a trait to describe the required fields is fine too. 
+#[graphql_interface]
+#[graphql(enum = HasHomeEnum, for = Human)]
+//        ^^^^ the generated value-type enum can be renamed, if required
+trait HasHome {
+    fn home_planet(&self) -> &str;
 }
 
 #[derive(GraphQLObject)]
-#[graphql(impl = CharacterInterface)]
+#[graphql(impl = [CharacterValue, HasHomeEnum])] 
+//                ^^^^^^^^^^^^^^  ^^^^^^^^^^^
+// Notice the enum type names, neither the trait name nor the struct name
+// is used to refer the GraphQL interface.
 struct Human {
-    id: String,
-    home_planet: String,
+  id: String,          // also resolves `Character.id` field
+  home_planet: String, // also resolves `HasHome.homePlanet` field
 }
 #
 # fn main() {}
@@ -79,18 +48,19 @@ struct Human {
 
 ### Interfaces implementing other interfaces
 
-GraphQL allows implementing interfaces on other interfaces in addition to objects.
-
+[GraphQL] allows implementing [interfaces][0] on other [interfaces][0] in addition to [objects][10]:
 ```rust
 # extern crate juniper;
-use juniper::{graphql_interface, graphql_object, ID};
-
-#[graphql_interface(for = [HumanValue, Luke])]
+# use juniper::{graphql_object, GraphQLInterface, ID};
+#
+#[derive(GraphQLInterface)]
+#[graphql(for = [HumanValue, Luke])]
 struct Node {
     id: ID,
 }
 
-#[graphql_interface(impl = NodeValue, for = Luke)]
+#[derive(GraphQLInterface)]
+#[graphql(impl = NodeValue, for = Luke)]
 struct Human {
     id: ID,
     home_planet: String,
@@ -100,15 +70,16 @@ struct Luke {
     id: ID,
 }
 
-#[graphql_object(impl = [HumanValue, NodeValue])]
+#[graphql_object]
+#[graphql(impl = [HumanValue, NodeValue])]
 impl Luke {
     fn id(&self) -> &ID {
         &self.id
     }
 
-    // As `String` and `&str` aren't distinguished by 
-    // GraphQL spec, you can use them interchangeably.
-    // Same is applied for `Cow<'a, str>`.
+    // As `String` and `&str` aren't distinguished by GraphQL spec and 
+    // represent the same `!String` GraphQL scalar, we can use them 
+    // interchangeably. The same is applied for `Cow<'a, str>`.
     //                  ⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄⌄
     fn home_planet() -> &'static str {
         "Tatooine"
@@ -118,78 +89,84 @@ impl Luke {
 # fn main() {}
 ```
 
-> __NOTE:__ Every interface has to specify all other interfaces/objects it implements or implemented for. Missing one of `for = ` or `impl = ` attributes is a compile-time error.
-
-```compile_fail
-# extern crate juniper;
-use juniper::{graphql_interface, GraphQLObject};
-
-#[derive(GraphQLObject)]
-pub struct ObjA {
-  id: String,
-}
-
-#[graphql_interface(for = ObjA)]
-// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at 
-// 'Failed to implement interface `Character` on `ObjA`: missing interface reference in implementer's `impl` attribute.'
-struct Character {
-  id: String,
-}
-
-fn main() {}
-```
-
-
-### GraphQL subtyping and additional `null`able fields
-
-GraphQL allows implementers (both objects and other interfaces) to return "subtypes" instead of an original value. Basically, this allows you to impose additional bounds on the implementation.
+> **NOTE**: Every [interface][0] has to specify all other [interfaces][0]/[objects][0] it implements or implemented for. Missing one of `for = ` or `impl = ` attribute arguments is a **compile-time error**.
+> ```rust,compile_fail
+> # extern crate juniper;
+> # use juniper::{GraphQLInterface, GraphQLObject};
+> #
+> #[derive(GraphQLObject)]
+> pub struct ObjA {
+>     id: String,
+> }
+>
+> #[derive(GraphQLInterface)]
+> #[graphql(for = ObjA)]
+> //        ^^^^^^^^^^ the evaluated program panicked at 
+> // 'Failed to implement interface `Character` on `ObjA`: missing interface 
+> //  reference in implementer's `impl` attribute.'
+> struct Character {
+>   id: String,
+> }
+> #
+> # fn main() {}
+> ```
+
+
+### Subtyping and additional `null`able arguments
+
+[GraphQL] allows implementers (both [objects][10] and other [interfaces][0]) to return "subtypes" instead of an original value. Basically, this allows to impose additional bounds on the implementation.
 
 Valid "subtypes" are:
-- interface implementer instead of an interface itself:
+- [interface][0] implementer instead of an [interface][0] itself:
   - `I implements T` in place of a `T`;
   - `Vec<I implements T>` in place of a `Vec<T>`.
-- non-null value in place of a nullable:
+- [non-`null`][6] value in place of a `null`able:
   - `T` in place of a `Option<T>`;
   - `Vec<T>` in place of a `Vec<Option<T>>`.
 
 These rules are recursively applied, so `Vec<Vec<I implements T>>` is a valid "subtype" of a `Option<Vec<Option<Vec<Option<T>>>>>`.
 
-Also, GraphQL allows implementers to add `null`able fields, which aren't present on an original interface.
+Also, [GraphQL] allows implementers to add `null`able [field arguments][5], which aren't present on an original interface.
 
 ```rust
 # extern crate juniper;
-use juniper::{graphql_interface, graphql_object, ID};
-
-#[graphql_interface(for = [HumanValue, Luke])]
+# use juniper::{graphql_interface, graphql_object, GraphQLInterface, ID};
+#
+#[derive(GraphQLInterface)]
+#[graphql(for = [HumanValue, Luke])]
 struct Node {
     id: ID,
 }
 
-#[graphql_interface(for = HumanConnectionValue)]
+#[derive(GraphQLInterface)]
+#[graphql(for = HumanConnectionValue)]
 struct Connection {
     nodes: Vec<NodeValue>,
 }
 
-#[graphql_interface(impl = NodeValue, for = Luke)]
+#[derive(GraphQLInterface)]
+#[graphql(impl = NodeValue, for = Luke)]
 struct Human {
     id: ID,
     home_planet: String,
 }
 
-#[graphql_interface(impl = ConnectionValue)]
+#[derive(GraphQLInterface)]
+#[graphql(impl = ConnectionValue)]
 struct HumanConnection {
     nodes: Vec<HumanValue>,
     //         ^^^^^^^^^^ notice not `NodeValue`
-    // This can happen, because every `Human` is a `Node` too, so we are just
-    // imposing additional bounds, which still can be resolved with
-    // `... on Connection { nodes }`.
+    // This can happen, because every `Human` is a `Node` too, so we just
+    // impose additional bounds, which still can be resolved with
+    // `... on Connection { nodes }` syntax.
 }
 
 struct Luke {
     id: ID,
 }
 
-#[graphql_object(impl = [HumanValue, NodeValue])]
+#[graphql_object]
+#[graphql(impl = [HumanValue, NodeValue])]
 impl Luke {
     fn id(&self) -> &ID {
         &self.id
@@ -197,13 +174,13 @@ impl Luke {
     
     fn home_planet(language: Option<String>) -> &'static str {
         //                   ^^^^^^^^^^^^^^
-        // Notice additional `null`able field, which is missing on `Human`.
-        // Resolving `...on Human { homePlanet }` will provide `None` for this
-        // argument.
+        // Notice additional `null`able field argument, which is missing on 
+        // `Human`. Resolving `...on Human { homePlanet }` will provide `None` 
+        // for this argument (default argument value).
         match language.as_deref() {
             None | Some("en") => "Tatooine",
             Some("ko") => "타투인",
-            _ => todo!(),
+            _ => unimplemented!(),
         }
     }
 }
@@ -211,271 +188,229 @@ impl Luke {
 # fn main() {}
 ```
 
-Violating GraphQL "subtyping" or additional nullable field rules is a compile-time error.
-
-```compile_fail
+> **NOTE**: Violating [GraphQL] "subtyping" or additional `null`able [argument][5] rules is a **compile-time error**.
+>
+> ```rust,compile_fail
+> # extern crate juniper;
+> # use juniper::{graphql_object, GraphQLInterface};
+> #
+> pub struct ObjA {
+>     id: String,
+> }
+>
+> #[graphql_object]
+> #[graphql(impl = CharacterValue)]
+> impl ObjA {
+>     fn id(&self, is_present: bool) -> &str {
+> //     ^^ the evaluated program panicked at 
+> // 'Failed to implement interface `Character` on `ObjA`: Field `id`: Argument 
+> //  `isPresent` of type `Boolean!` isn't present on the interface and so has
+> //  to be nullable.'        
+>         is_present.then_some(&self.id).unwrap_or("missing")
+>     }
+> }
+>
+> #[derive(GraphQLInterface)]
+> #[graphql(for = ObjA)]
+> struct Character {
+>     id: String,
+> }
+> #
+> # fn main() {}
+> ```
+>
+> ```rust,compile_fail
+> # extern crate juniper;
+> # use juniper::{GraphQLInterface, GraphQLObject};
+> #
+> #[derive(GraphQLObject)]
+> #[graphql(impl = CharacterValue)]
+> pub struct ObjA {
+>     id: Vec<String>,
+> //  ^^ the evaluated program panicked at 
+> // 'Failed to implement interface `Character` on `ObjA`: Field `id`: 
+> //  implementer is expected to return a subtype of interface's return
+> //  object: `[String!]!` is not a subtype of `String!`.'    
+> }
+>
+> #[derive(GraphQLInterface)]
+> #[graphql(for = ObjA)]
+> struct Character {
+>     id: String,
+> }
+> #
+> # fn main() {}
+> ```
+
+
+### Default arguments
+
+[Similarly to GraphQL object fields](objects/complex_fields.md#default-arguments), [GraphQL arguments][4] of [interfaces][0] are able to have default values, though [Rust] doesn't have such notion:
+```rust
 # extern crate juniper;
-use juniper::{graphql_interface, graphql_object};
-
-pub struct ObjA {
-    id: String,
-}
-
-#[graphql_object(impl = CharacterValue)]
-impl ObjA {
-    fn id(&self, is_present: bool) -> &str {
-//     ^^ the evaluated program panicked at 
-//        'Failed to implement interface `Character` on `ObjA`: Field `id`: Argument `isPresent` of type `Boolean!` 
-//         isn't present on the interface and so has to be nullable.'        
-        is_present.then_some(&self.id).unwrap_or("missing")
-    }
-}
-
-#[graphql_interface(for = ObjA)]
-struct Character {
-    id: String,
-}
+# use juniper::graphql_interface;
 #
-# fn main() {}
-```
-
-```compile_fail
-# extern crate juniper;
-use juniper::{graphql_interface, GraphQLObject};
-
-#[derive(GraphQLObject)]
-#[graphql(impl = CharacterValue)]
-pub struct ObjA {
-    id: Vec<String>,
-//  ^^ the evaluated program panicked at 
-//     'Failed to implement interface `Character` on `ObjA`: Field `id`: implementer is expected to return a subtype of 
-//      interface's return object: `[String!]!` is not a subtype of `String!`.'    
-}
-
-#[graphql_interface(for = ObjA)]
-struct Character {
-    id: String,
+#[graphql_interface]
+trait Person {
+    fn field1(
+        // Default value can be any valid Rust expression, including a function
+        // call, etc.
+        #[graphql(default = true)]
+        arg1: bool,
+        // If default expression is not specified, then the `Default::default()` 
+        // value is used.
+        #[graphql(default)]
+        arg2: i32,
+    ) -> String;
 }
 #
 # fn main() {}
 ```
 
 
-### Ignoring trait methods
+### Renaming
 
-We may want to omit some trait methods to be assumed as [GraphQL interface][1] fields and ignore them.
+Just as with [defining GraphQL objects](objects/index.md#renaming), by default, [fields][4] are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention:
 
+We can override the name by using the `#[graphql(name = "...")]` attribute:
 ```rust
 # extern crate juniper;
-use juniper::{graphql_interface, GraphQLObject};
-
-#[graphql_interface(for = Human)]  
-trait Character {
-    fn id(&self) -> &str;
-
-    #[graphql(ignore)] // or `#[graphql(skip)]`, your choice
-    fn ignored(&self) -> u32 { 0 }
+# use juniper::{graphql_interface, GraphQLInterface};
+#
+#[derive(GraphQLInterface)]
+#[graphql(name = "CharacterInterface")]
+struct Character { // exposed as `CharacterInterface` in GraphQL schema
+    #[graphql(name = "myCustomFieldName")]
+    renamed_field: bool, // exposed as `myCustomFieldName` in GraphQL schema
 }
 
-#[derive(GraphQLObject)]
-#[graphql(impl = CharacterValue)]
-struct Human {
-    id: String,
+#[graphql_interface]
+#[graphql(name = "PersonInterface")]
+trait Person { // exposed as `PersonInterface` in GraphQL schema
+    #[graphql(name = "myCustomFieldName")]
+    fn renamed_field( // exposed as `myCustomFieldName` in GraphQL schema
+        #[graphql(name = "myArgument")]
+        renamed_argument: bool, // exposed as `myArgument` in GraphQL schema
+    ) -> bool;
 }
 #
 # fn main() {}
 ```
 
-
-### Fields, arguments and interface customization
-
-Similarly to [GraphQL objects][5] Juniper allows to fully customize [interface][1] fields and their arguments.
-
+Or provide a different renaming policy for all the defined [fields][4]:
 ```rust
-# #![allow(deprecated)]
 # extern crate juniper;
-use juniper::graphql_interface;
-
-// Renames the interface in GraphQL schema.
-#[graphql_interface(name = "MyCharacter")] 
-// Describes the interface in GraphQL schema.
-#[graphql_interface(description = "My own character.")]
-// Usual Rust docs are supported too as GraphQL interface description, 
-// but `description` attribute argument takes precedence over them, if specified.
-/// This doc is absent in GraphQL schema.  
-trait Character {
-    // Renames the field in GraphQL schema.
-    #[graphql(name = "myId")]
-    // Deprecates the field in GraphQL schema.
-    // Usual Rust `#[deprecated]` attribute is supported too as field deprecation,
-    // but `deprecated` attribute argument takes precedence over it, if specified.
-    #[graphql(deprecated = "Do not use it.")]
-    // Describes the field in GraphQL schema.
-    #[graphql(description = "ID of my own character.")]
-    // Usual Rust docs are supported too as field description, 
-    // but `description` attribute argument takes precedence over them, if specified.
-    /// This description is absent in GraphQL schema.  
-    fn id(
-        &self,
-        // Renames the argument in GraphQL schema.
-        #[graphql(name = "myNum")]
-        // Describes the argument in GraphQL schema.
-        #[graphql(description = "ID number of my own character.")]
-        // Specifies the default value for the argument.
-        // The concrete value may be omitted, and the `Default::default` one 
-        // will be used in such case.
-        #[graphql(default = 5)]
-        num: i32,
-    ) -> &str;
-}
+# use juniper::graphql_interface;
 #
-# fn main() {}
-```
-
-Renaming policies for all [GraphQL interface][1] fields and arguments are supported as well:
-```rust
-# #![allow(deprecated)]
-# extern crate juniper;
-use juniper::graphql_interface;
-
-#[graphql_interface(rename_all = "none")] // disables any renaming
-trait Character {
-    // Now exposed as `my_id` and `my_num` in the schema
-    fn my_id(&self, my_num: i32) -> &str;
+#[graphql_interface]
+#[graphql(rename_all = "none")] // disables any renaming
+trait Person {
+    fn renamed_field( // exposed as `renamed_field` in GraphQL schema
+        renamed_argument: bool, // exposed as `renamed_argument` in GraphQL schema
+    ) -> bool;
 }
 #
 # fn main() {}
 ```
+> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
 
 
-### Custom context
-
-If a [`Context`][6] is required in a trait method to resolve a [GraphQL interface][1] field, specify it as an argument.
+### Documentation and deprecation
 
+Similarly, [GraphQL fields][4] of [interfaces][0] may also be [documented][7] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
 ```rust
 # extern crate juniper;
-# use std::collections::HashMap;
-use juniper::{graphql_interface, GraphQLObject};
-
-struct Database {
-    humans: HashMap<String, Human>,
-}
-impl juniper::Context for Database {}
-
-#[graphql_interface(for = Human)] // look, ma, context type is inferred! ＼(^o^)／
-trait Character {                 // while still can be specified via `Context = ...` attribute argument
-    // If a field argument is named `context` or `ctx`, it's automatically assumed
-    // as a context argument.
-    fn id(&self, context: &Database) -> Option<&str>;
-
-    // Otherwise, you may mark it explicitly as a context argument.
-    fn name(&self, #[graphql(context)] db: &Database) -> Option<&str>;
-}
-
-#[derive(GraphQLObject)]
-#[graphql(impl = CharacterValue, Context = Database)]
-struct Human {
-    id: String,
-    name: String,
-}
+# use juniper::graphql_interface;
 #
-# fn main() {}
-```
-
-
-### Using executor and explicit generic scalar
-
-If an [`Executor`][4] is required in a trait method to resolve a [GraphQL interface][1] field, specify it as an argument.
-
-This requires to explicitly parametrize over [`ScalarValue`][3], as [`Executor`][4] does so. 
-
-```rust
-# extern crate juniper;
-use juniper::{graphql_interface, graphql_object, Executor, ScalarValue};
-
-#[graphql_interface(for = Human, Scalar = S)] // notice specifying `ScalarValue` as existing type parameter
-trait Character<S: ScalarValue> {             
-    // If a field argument is named `executor`, it's automatically assumed
-    // as an executor argument.
-    fn id<'a>(&self, executor: &'a Executor<'_, '_, (), S>) -> &'a str;
-
-    // Otherwise, you may mark it explicitly as an executor argument.
-    fn name<'b>(
-        &'b self,
-        #[graphql(executor)] another: &Executor<'_, '_, (), S>,
-    ) -> &'b str;
+/// This doc comment is visible only in Rust API docs.
+#[graphql_interface]
+#[graphql(description = "This description overwrites the one from doc comment.")]
+trait Person {
+    /// This doc comment is visible only in Rust API docs.
+    #[graphql(description = "This description is visible only in GraphQL schema.")]
+    fn empty() -> &'static str;
     
-    fn home_planet(&self) -> &str;
-}
-
-struct Human {
-    id: String,
-    name: String,
-    home_planet: String,
-}
-#[graphql_object(scalar = S: ScalarValue, impl = CharacterValue<S>)]
-impl Human {
-    async fn id<'a, S>(&self, executor: &'a Executor<'_, '_, (), S>) -> &'a str 
-    where
-        S: ScalarValue,
-    {
-        executor.look_ahead().field_name()
-    }
-
-    async fn name<'b, S>(&'b self, #[graphql(executor)] _: &Executor<'_, '_, (), S>) -> &'b str {
-        &self.name
-    }
+    #[graphql(desc = "This description is visible only in GraphQL schema.")]
+    //        ^^^^ shortcut for a `description` argument
+    fn field(
+        #[graphql(desc = "This description is visible only in GraphQL schema.")]
+        arg: bool,
+    ) -> bool;
+
+    /// This doc comment is visible in both Rust API docs and GraphQL schema 
+    /// descriptions.
+    #[graphql(deprecated = "Just because.")]
+    fn deprecated_graphql() -> bool;
     
-    fn home_planet<'c, S>(&'c self, #[graphql(executor)] _: &Executor<'_, '_, (), S>) -> &'c str {
-        // Executor may not be present on the trait method  ^^^^^^^^^^^^^^^^^^^^^^^^
-        &self.home_planet
-    }
+    // Standard Rust's `#[deprecated]` attribute works too!
+    #[deprecated(note = "Reason is optional, btw!")]
+    fn deprecated_standard() -> bool; // has no description in GraphQL schema
 }
 #
 # fn main() {}
 ```
+> **NOTE**: Only [GraphQL interface][0]/[object][10] fields and [GraphQL enum][11] values can be [deprecated][9].
 
 
+### Ignoring
 
-
-## `ScalarValue` considerations
-
-By default, `#[graphql_interface]` macro generates code, which is generic over a [`ScalarValue`][3] type. This may introduce a problem when at least one of [GraphQL interface][1] implementers is restricted to a concrete [`ScalarValue`][3] type in its implementation. To resolve such problem, a concrete [`ScalarValue`][3] type should be specified.
-
+By default, all [struct][24] fields or [trait][20] methods are considered as [GraphQL fields][4]. If a helper method is needed, or it should be ignored for some reason, then it should be marked with the `#[graphql(ignore)]` attribute:
 ```rust
+# #![allow(dead_code)]
 # extern crate juniper;
-use juniper::{graphql_interface, DefaultScalarValue, GraphQLObject};
-
-#[graphql_interface(for = [Human, Droid])]
-#[graphql_interface(scalar = DefaultScalarValue)] // removing this line will fail compilation
-trait Character {
-    fn id(&self) -> &str;
+# use std::marker::PhantomPinned;
+# use juniper::{graphql_interface, GraphQLInterface};
+#
+#[derive(GraphQLInterface)]
+struct Character {
+    id: i32,
+    #[graphql(ignore)]
+    _pin: PhantomPinned,
 }
 
-#[derive(GraphQLObject)]
-#[graphql(impl = CharacterValue, Scalar = DefaultScalarValue)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
+#[graphql_interface]
+trait Person {
+    fn name(&self) -> &str;
 
-#[derive(GraphQLObject)]
-#[graphql(impl = CharacterValue, Scalar = DefaultScalarValue)]
-struct Droid {
-    id: String,
-    primary_function: String,
+    fn age(&self) -> i32;
+
+    #[graphql(ignore)]
+    fn hidden_from_graphql(&self) {
+        // Ignored methods are allowed to have a default implementation!
+    }
+
+    #[graphql(skip)]
+    //        ^^^^ alternative naming, up to your preference
+    fn also_hidden_from_graphql(&self);
 }
 #
 # fn main() {}
 ```
 
-
-
-
-
-[1]: https://spec.graphql.org/October2021#sec-Interfaces
-[2]: https://doc.rust-lang.org/reference/types/trait-object.html
-[3]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
-[4]: https://docs.rs/juniper/latest/juniper/struct.Executor.html
-[5]: https://spec.graphql.org/October2021#sec-Objects
-[6]: https://docs.rs/juniper/0.14.2/juniper/trait.Context.html
+> **TIP**: See more available features in the API docs of the [`#[graphql_interface]`][3] attribute.
+
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Interfaces
+[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLInterface.html
+[3]: https://docs.rs/juniper/latest/juniper/attr.graphql_interface.html
+[4]: https://spec.graphql.org/October2021#sec-Language.Fields
+[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
+[6]: https://spec.graphql.org/October2021#sec-Non-Null
+[7]: https://spec.graphql.org/October2021#sec-Descriptions
+[9]: https://spec.graphql.org/October2021#sec--deprecated
+[10]: https://spec.graphql.org/October2021#sec-Objects
+[11]: https://spec.graphql.org/October2021#sec-Enums
+[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
+[20]: https://doc.rust-lang.org/reference/items/traits.html#traits
+[21]: https://doc.rust-lang.org/reference/types/trait-object.html#trait-objects
+[22]: https://doc.rust-lang.org/reference/items/enumerations.html#enumerations
+[23]: https://doc.rust-lang.org/reference/items/implementations.html#trait-implementations
+[24]: https://doc.rust-lang.org/reference/items/structs.html
+[30]: https://en.wikipedia.org/wiki/Structural_type_system
+[31]: https://en.wikipedia.org/wiki/Type_class
diff --git a/book/src/types/objects/complex_fields.md b/book/src/types/objects/complex_fields.md
index f8aa13992..e2f607834 100644
--- a/book/src/types/objects/complex_fields.md
+++ b/book/src/types/objects/complex_fields.md
@@ -1,53 +1,13 @@
-# Complex fields
-
-If you've got a struct that can't be mapped directly to GraphQL, that contains
-computed fields or circular structures, you have to use a more powerful tool:
-the `#[graphql_object]` procedural macro. This macro lets you define GraphQL object
-fields in a Rust `impl` block for a type. Note, that GraphQL fields are defined in 
-this `impl` block by default. If you want to define normal methods on the struct,
-you have to do so either in a separate "normal" `impl` block, or mark them with
-`#[graphql(ignore)]` attribute to be omitted by the macro. Continuing with the
-example from the last chapter, this is how you would define `Person` using the
-macro:
+Complex fields
+==============
 
-```rust
-# #![allow(dead_code)]
-# extern crate juniper;
-# use juniper::graphql_object;
-#
-struct Person {
-    name: String,
-    age: i32,
-}
-
-#[graphql_object]
-impl Person {
-    fn name(&self) -> &str {
-        self.name.as_str()
-    }
-
-    fn age(&self) -> i32 {
-        self.age
-    }
-
-    #[graphql(ignore)]
-    pub fn hidden_from_graphql(&self) {
-        // [...]
-    }
-}
-
-impl Person {
-    pub fn hidden_from_graphql2(&self) {
-        // [...]
-    }
-}
-#
-# fn main() { }
-```
-
-While this is a bit more verbose, it lets you write any kind of function in the
-field resolver. With this syntax, fields can also take arguments:
+Using a plain [Rust struct][struct] for representing a [GraphQL object][0] is easy and trivial but does not cover every case. What if we need to express something non-trivial as a [GraphQL field][4], such as:
+- Calling non-trivial logic while [executing][1] the [field][4] (like querying database, etc.).
+- Accepting [field arguments][5].
+- Defining a circular [GraphQL object][0], where one of its [fields][4] returns the type itself.
+- Using some other (non-[struct]) [Rust] type to represent a [GraphQL object][0].
 
+To support these more complicated use cases, we need a way to define a [GraphQL field][4] as a function. In [Juniper] this is achievable by placing the [`#[graphql_object]` attribute][3] on an [`impl` block][6], which turns its methods into [GraphQL fields][4]:
 ```rust
 # extern crate juniper;
 # use juniper::{graphql_object, GraphQLObject};
@@ -62,9 +22,11 @@ struct House {
     inhabitants: Vec<Person>,
 }
 
+// Defines the `House` GraphQL object.
 #[graphql_object]
 impl House {
-    // Creates the field `inhabitantWithName(name)`, returning a nullable `Person`.
+    // Creates the field `inhabitantWithName(name: String!)`, 
+    // returning a `null`able `Person`.
     fn inhabitant_with_name(&self, name: String) -> Option<&Person> {
         self.inhabitants.iter().find(|p| p.name == name)
     }
@@ -72,135 +34,196 @@ impl House {
 #
 # fn main() {}
 ```
+> **NOTE**: To access global data such as database connections or authentication information, a _context_ is used. To learn more about this, see the ["Context" chapter](context.md).
 
-To access global data such as database connections or authentication
-information, a _context_ is used. To learn more about this, see the next
-chapter: [Using contexts](using_contexts.md).
-
-## Description, renaming, and deprecation
 
-Like with the derive attribute, field names will be converted from `snake_case`
-to `camelCase`. If you need to override the conversion, you can simply rename
-the field. Also, the type name can be changed with an alias:
+### Default arguments
 
+Though [Rust] doesn't have the notion of default arguments, [GraphQL arguments][4] are able to have default values. These default values are used when a GraphQL operation doesn't specify the argument explicitly. In [Juniper], defining a default value for a [GraphQL argument][4] is enabled by the `#[graphql(default)]` attribute:
 ```rust
 # extern crate juniper;
 # use juniper::graphql_object;
 #
 struct Person;
 
-/// Doc comments are used as descriptions for GraphQL.
-#[graphql_object(
-    // With this attribute you can change the public GraphQL name of the type.
-    name = "PersonObject",
-
-    // You can also specify a description here, which will overwrite 
-    // a doc comment description.
-    description = "...",
-)]
+#[graphql_object]
 impl Person {
-    /// A doc comment on the field will also be used for GraphQL.
-    #[graphql(
-        // Or provide a description here.
-        description = "...",
-    )]
-    fn doc_comment(&self) -> &str {
-        ""
+    fn field1(
+        // Default value can be any valid Rust expression, including a function
+        // call, etc.
+        #[graphql(default = true)]
+        arg1: bool,
+        // If default expression is not specified, then the `Default::default()` 
+        // value is used.
+        #[graphql(default)]
+        arg2: i32,
+    ) -> String {
+        format!("{arg1} {arg2}")
     }
+}
+#
+# fn main() {}
+```
 
-    // Fields can also be renamed if required.
-    #[graphql(name = "myCustomFieldName")]
-    fn renamed_field() -> bool {
-        true
-    }
 
-    // Deprecations also work as you'd expect.
-    // Both the standard Rust syntax and a custom attribute is accepted.
-    #[deprecated(note = "...")]
-    fn deprecated_standard() -> bool {
-        false
-    }
+### Renaming
 
-    #[graphql(deprecated = "...")]
-    fn deprecated_graphql() -> bool {
-        true
+Like with the [`#[derive(GraphQLObject)]` attribute on structs](index.md#renaming), [field][4] names are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention.
+
+We can override the name by using the `#[graphql(name = "...")]` attribute:
+```rust
+# extern crate juniper;
+# use juniper::graphql_object;
+#
+struct Person;
+
+#[graphql_object]
+#[graphql(name = "PersonObject")]
+impl Person { // exposed as `PersonObject` in GraphQL schema
+    #[graphql(name = "myCustomFieldName")]
+    fn renamed_field( // exposed as `myCustomFieldName` in GraphQL schema
+        #[graphql(name = "myArgument")]
+        renamed_argument: bool, // exposed as `myArgument` in GraphQL schema
+    ) -> bool {
+        renamed_argument
     }
 }
 #
-# fn main() { }
+# fn main() {}
 ```
 
-Or provide a different renaming policy on a `impl` block for all its fields:
+Or provide a different renaming policy for all the defined [fields][4]:
 ```rust
 # extern crate juniper;
 # use juniper::graphql_object;
+#
 struct Person;
 
-#[graphql_object(rename_all = "none")] // disables any renaming
+#[graphql_object]
+#[graphql(rename_all = "none")] // disables any renaming
 impl Person {
-    // Now exposed as `renamed_field` in the schema
-    fn renamed_field() -> bool {
-        true
+    fn renamed_field( // exposed as `renamed_field` in GraphQL schema
+        renamed_argument: bool, // exposed as `renamed_argument` in GraphQL schema
+    ) -> bool {
+        renamed_argument
     }
 }
 #
 # fn main() {}
 ```
+> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
 
-## Customizing arguments
 
-Method field arguments can also be customized.
-
-They can have custom descriptions and default values.
+### Documentation and deprecation
 
+Similarly, [GraphQL fields][4] may also be [documented][7] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
 ```rust
 # extern crate juniper;
 # use juniper::graphql_object;
 #
 struct Person;
 
+/// This doc comment is visible only in Rust API docs.
 #[graphql_object]
+#[graphql(description = "This description overwrites the one from doc comment.")]
 impl Person {
-    fn field1(
-        &self,
-        #[graphql(
-            // Arguments can also be renamed if required.
-            name = "arg",
-            // Set a default value which will be injected if not present.
-            // The default can be any valid Rust expression, including a function call, etc.
-            default = true,
-            // Set a description.
-            description = "The first argument..."
-        )]
-        arg1: bool,
-        // If default expression is not specified then `Default::default()` value is used.
-        #[graphql(default)]
-        arg2: i32,
-    ) -> String {
-        format!("{arg1} {arg2}")
+    /// This doc comment is visible only in Rust API docs.
+    #[graphql(description = "This description is visible only in GraphQL schema.")]
+    fn empty() -> &'static str {
+        ""
+    }
+    
+    #[graphql(desc = "This description is visible only in GraphQL schema.")]
+    //        ^^^^ shortcut for a `description` argument
+    fn field(
+        #[graphql(desc = "This description is visible only in GraphQL schema.")]
+        arg: bool,
+    ) -> bool {
+        arg
+    }
+
+    /// This doc comment is visible in both Rust API docs and GraphQL schema 
+    /// descriptions.
+    #[graphql(deprecated = "Just because.")]
+    fn deprecated_graphql() -> bool {
+        true
+    }
+    
+    // Standard Rust's `#[deprecated]` attribute works too!
+    #[deprecated(note = "Reason is optional, btw!")]
+    fn deprecated_standard() -> bool { // has no description in GraphQL schema
+        false
     }
 }
 #
-# fn main() { }
+# fn main() {}
 ```
+> **NOTE**: Only [GraphQL object][0]/[interface][11] fields and [GraphQL enum][10] values can be [deprecated][9].
 
-Provide a different renaming policy on a `impl` block also implies for arguments:
+
+### Ignoring
+
+By default, all methods of an [`impl` block][6] are exposed as [GraphQL fields][4]. If a method should not be exposed as a [GraphQL field][4], it should be defined in a separate [`impl` block][6] or marked with the `#[graphql(ignore)]` attribute:
 ```rust
+# #![allow(dead_code)]
 # extern crate juniper;
 # use juniper::graphql_object;
-struct Person;
+#
+struct Person {
+    name: String,
+    age: i32,
+}
 
-#[graphql_object(rename_all = "none")] // disables any renaming
+#[graphql_object]
 impl Person {
-    // Now exposed as `my_arg` in the schema
-    fn field(my_arg: bool) -> bool {
-        my_arg
+    fn name(&self) -> &str {
+        self.name.as_str()
+    }
+
+    fn age(&self) -> i32 {
+        self.age
+    }
+
+    #[graphql(ignore)]
+    pub fn hidden_from_graphql(&self) {
+        // whatever goes...
+    }
+
+    #[graphql(skip)]
+    //        ^^^^ alternative naming, up to your preference
+    pub fn also_hidden_from_graphql(&self) {
+        // whatever goes...
+    }
+}
+
+impl Person {
+    pub fn not_even_considered_for_graphql(&self) {
+        // whatever goes...
     }
 }
 #
 # fn main() {}
 ```
 
-## More features
+> **TIP**: See more available features in the API docs of the [`#[graphql_object]`][3] attribute.
+
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[struct]: https://doc.rust-lang.org/reference/items/structs.html
 
-These, and more features, are described more thoroughly in [the reference documentation](https://docs.rs/juniper/latest/juniper/attr.graphql_object.html).
+[0]: https://spec.graphql.org/October2021#sec-Objects
+[1]: https://spec.graphql.org/October2021#sec-Execution
+[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLObject.html
+[3]: https://docs.rs/juniper/latest/juniper/attr.graphql_object.html
+[4]: https://spec.graphql.org/October2021#sec-Language.Fields
+[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
+[6]: https://doc.rust-lang.org/reference/items/implementations.html#inherent-implementations
+[7]: https://spec.graphql.org/October2021#sec-Descriptions
+[9]: https://spec.graphql.org/October2021#sec--deprecated
+[10]: https://spec.graphql.org/October2021#sec-Enums
+[11]: https://spec.graphql.org/October2021#sec-Interfaces
+[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
diff --git a/book/src/types/objects/context.md b/book/src/types/objects/context.md
new file mode 100644
index 000000000..5171408a0
--- /dev/null
+++ b/book/src/types/objects/context.md
@@ -0,0 +1,156 @@
+Context
+=======
+
+_Context_ is a feature in [Juniper] that lets [field][4] resolvers access global data, most commonly database connections or authentication information.
+
+Let's say that we have a simple `User`s database in a `HashMap`:
+```rust
+# #![allow(dead_code)]
+# use std::collections::HashMap;
+#
+struct Database {
+    users: HashMap<i32, User>,
+}
+
+struct User {
+    id: i32,
+    name: String,
+    friend_ids: Vec<i32>,
+}
+#
+# fn main() {}
+```
+We would like to define a `friends` [field][4] on `User` that returns a list of `User` [objects][0]. In order to write such a [field][4] we need to query a `Database`. To accomplish this we must first mark the `Database` as a valid context type and then assign it to the `User` [object][0]. To gain access to the context in the `friends` [field][4], we need to specify an argument with the same type as the specified context:
+```rust
+# extern crate juniper;
+# use std::collections::HashMap;
+# use juniper::graphql_object;
+#
+struct Database {
+    users: HashMap<i32, User>,
+}
+
+// Mark the `Database` as a valid context type for Juniper.
+impl juniper::Context for Database {}
+
+struct User {
+    id: i32,
+    name: String,
+    friend_ids: Vec<i32>,
+}
+
+#[graphql_object]
+#[graphql(context = Database)] // assign `Database` as the context type
+impl User {
+    // Inject the `Database` context by specifying an argument with the 
+    // context type: 
+    // - the type must be a reference;
+    // - the name of the argument SHOULD be `context` (or `ctx`).
+    fn friends<'db>(&self, context: &'db Database) -> Vec<&'db User> {
+        //                 ^^^^^^^ or `ctx`, up to your preference
+        self.friend_ids.iter()
+            .map(|id| {
+                context.users.get(&id).expect("could not find `User` with ID")
+            })
+            .collect()
+    }
+
+    fn friend<'db>(
+        &self, 
+        id: i32, 
+        // Alternatively, the context argument may be marked with an attribute,
+        // and thus, named arbitrary.
+        #[graphql(context)] db: &'db Database,
+        //        ^^^^^^^ or `ctx`, up to your preference
+    ) -> Option<&'db User> {
+        self.friend_ids.contains(&id).then(|| {
+            db.users.get(&id).expect("could not find `User` with ID")
+        })
+    }
+
+    fn name(&self) -> &str { 
+        self.name.as_str() 
+    }
+
+    fn id(&self) -> i32 { 
+        self.id 
+    }
+}
+#
+# fn main() {}
+```
+
+
+### Mutating and mutable references
+
+Context cannot be a mutable reference as [fields][4] may be resolved concurrently. If something in the context requires a mutable reference, the context type should leverage the [_interior mutability_ pattern][5] (e.g. use `RwLock`, `RefCell` or similar).
+
+For example, when using async runtime with [work stealing][6] (like [`tokio`]), which obviously requires thread safety in addition, we will need to use a corresponding async version of `RwLock`:
+```rust
+# extern crate juniper;
+# extern crate tokio;
+# use std::collections::HashMap;
+# use juniper::graphql_object;
+use tokio::sync::RwLock;
+
+struct Database {
+    requested_count: HashMap<i32, i32>,
+}
+
+// Since we cannot directly implement `juniper::Context`
+// for `RwLock`, we use the newtype idiom.
+struct DatabaseContext(RwLock<Database>);
+
+impl juniper::Context for DatabaseContext {}
+
+struct User {
+    id: i32,
+    name: String
+}
+
+#[graphql_object]
+#[graphql(context = DatabaseContext)]
+impl User {
+    async fn times_requested<'db>(&self, ctx: &'db DatabaseContext) -> i32 {
+        // Acquire a mutable reference and `.await` if async `RwLock` is used,
+        // which is necessary if context consists of async operations like 
+        // querying remote databases.
+        
+        // Obtain base type.
+        let DatabaseContext(db) = ctx;
+        // If context is immutable use `.read()` on `RwLock` instead.
+        let mut db = db.write().await;
+        
+        // Perform a mutable operation.
+        db.requested_count
+            .entry(self.id)
+            .and_modify(|e| *e += 1)
+            .or_insert(1)
+            .clone()
+    }
+
+    fn name(&self) -> &str { 
+        self.name.as_str() 
+    }
+
+    fn id(&self) -> i32 { 
+        self.id 
+    }
+}
+#
+# fn main() {}
+```
+> **TIP**: Replace `tokio::sync::RwLock` with `std::sync::RwLock` (or similar) if you don't intend to use async resolving.
+
+
+
+
+[`tokio`]: https://docs.rs/tokio
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Objects
+[4]: https://spec.graphql.org/October2021#sec-Language.Fields
+[5]: https://doc.rust-lang.org/reference/interior-mutability.html#interior-mutability
+[6]: https://en.wikipedia.org/wiki/Work_stealing
diff --git a/book/src/types/objects/defining_objects.md b/book/src/types/objects/defining_objects.md
deleted file mode 100644
index 5f32c6862..000000000
--- a/book/src/types/objects/defining_objects.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# Defining objects
-
-While any type in Rust can be exposed as a GraphQL object, the most common one
-is a struct.
-
-There are two ways to create a GraphQL object in Juniper. If you've got a simple
-struct you want to expose, the easiest way is to use the custom derive
-attribute. The other way is described in the [Complex fields](complex_fields.md)
-chapter.
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-struct Person {
-    name: String,
-    age: i32,
-}
-#
-# fn main() {}
-```
-
-This will create a GraphQL object type called `Person`, with two fields: `name`
-of type `String!`, and `age` of type `Int!`. Because of Rust's type system,
-everything is exported as non-null by default. If you need a nullable field, you
-can use `Option<T>`.
-
-We should take advantage of the
-fact that GraphQL is self-documenting and add descriptions to the type and
-fields. Juniper will automatically use associated doc comments as GraphQL
-descriptions:
-
-!FILENAME GraphQL descriptions via Rust doc comments
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-/// Information about a person
-struct Person {
-    /// The person's full name, including both first and last names
-    name: String,
-    /// The person's age in years, rounded down
-    age: i32,
-}
-#
-# fn main() {}
-```
-
-Objects and fields without doc comments can instead set a `description`
-via the `graphql` attribute. The following example is equivalent to the above:
-
-!FILENAME GraphQL descriptions via attribute
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-#[graphql(description = "Information about a person")]
-struct Person {
-    #[graphql(description = "The person's full name, including both first and last names")]
-    name: String,
-    #[graphql(description = "The person's age in years, rounded down")]
-    age: i32,
-}
-#
-# fn main() {}
-```
-
-Descriptions set via the `graphql` attribute take precedence over Rust
-doc comments. This enables internal Rust documentation and external GraphQL
-documentation to differ:
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-#[graphql(description = "This description shows up in GraphQL")]
-/// This description shows up in RustDoc
-struct Person {
-    #[graphql(description = "This description shows up in GraphQL")]
-    /// This description shows up in RustDoc
-    name: String,
-    /// This description shows up in both RustDoc and GraphQL
-    age: i32,
-}
-#
-# fn main() {}
-```
-
-## Relationships
-
-You can only use the custom derive attribute under these circumstances:
-
-- The annotated type is a `struct`,
-- Every struct field is either
-  - A primitive type (`i32`, `f64`, `bool`, `String`, `juniper::ID`), or
-  - A valid custom GraphQL type, e.g. another struct marked with this attribute,
-    or
-  - A container/reference containing any of the above, e.g. `Vec<T>`, `Box<T>`,
-    `Option<T>`
-
-Let's see what that means for building relationships between objects:
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-struct Person {
-    name: String,
-    age: i32,
-}
-
-#[derive(GraphQLObject)]
-struct House {
-    address: Option<String>, // Converted into String (nullable)
-    inhabitants: Vec<Person>, // Converted into [Person!]!
-}
-#
-# fn main() {}
-```
-
-Because `Person` is a valid GraphQL type, you can have a `Vec<Person>` in a
-struct and it'll be automatically converted into a list of non-nullable `Person`
-objects.
-
-## Renaming fields
-
-By default, struct fields are converted from Rust's standard `snake_case` naming
-convention into GraphQL's `camelCase` convention:
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-struct Person {
-    first_name: String, // Would be exposed as firstName in the GraphQL schema
-    last_name: String, // Exposed as lastName
-}
-#
-# fn main() {}
-```
-
-You can override the name by using the `graphql` attribute on individual struct
-fields:
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-struct Person {
-    name: String,
-    age: i32,
-    #[graphql(name = "websiteURL")]
-    website_url: Option<String>, // now exposed as `websiteURL` in the schema
-}
-#
-# fn main() {}
-```
-
-Or provide a different renaming policy on a struct for all its fields:
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-#[graphql(rename_all = "none")] // disables any renaming
-struct Person {
-    name: String,
-    age: i32,
-    website_url: Option<String>, // now exposed as `website_url` in the schema
-}
-#
-# fn main() {}
-```
-
-## Deprecating fields
-
-To deprecate a field, you specify a deprecation reason using the `graphql`
-attribute:
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-struct Person {
-    name: String,
-    age: i32,
-    #[graphql(deprecated = "Please use the name field instead")]
-    first_name: String,
-}
-#
-# fn main() {}
-```
-
-The `name`, `description`, and `deprecation` arguments can of course be
-combined. Some restrictions from the GraphQL spec still applies though; you can
-only deprecate object fields and enum values.
-
-## Ignoring fields
-
-By default, all fields in a `GraphQLObject` are included in the generated GraphQL type. To prevent including a specific field, annotate the field with `#[graphql(ignore)]`:
-
-```rust
-# extern crate juniper;
-# use juniper::GraphQLObject;
-#[derive(GraphQLObject)]
-struct Person {
-    name: String,
-    age: i32,
-    #[graphql(ignore)]
-    # #[allow(dead_code)]
-    password_hash: String, // cannot be queried or modified from GraphQL
-}
-#
-# fn main() {}
-```
diff --git a/book/src/types/objects/error/field.md b/book/src/types/objects/error/field.md
new file mode 100644
index 000000000..d65677047
--- /dev/null
+++ b/book/src/types/objects/error/field.md
@@ -0,0 +1,183 @@
+Field errors
+============
+
+[Rust] provides [two ways of dealing with errors][11]:
+- [`Result<T, E>`][12] for recoverable errors;
+- [`panic!`][13] for unrecoverable errors.
+
+[Juniper] does not do anything about panicking, it naturally bubbles up to the surrounding code/framework and can be dealt with there.
+
+For recoverable errors, [Juniper] works well with the [built-in `Result` type][12]. You can use the [`?` operator][14] and things will work as you expect them to:
+```rust
+# extern crate juniper;
+# use std::{fs::File, io::Read, path::PathBuf, str};
+# use juniper::{graphql_object, FieldResult};
+#
+struct Example {
+    filename: PathBuf,
+}
+
+#[graphql_object]
+impl Example {
+    fn contents(&self) -> FieldResult<String> {
+        let mut file = File::open(&self.filename)?;
+        let mut contents = String::new();
+        file.read_to_string(&mut contents)?;
+        Ok(contents)
+    }
+
+    fn foo() -> FieldResult<Option<String>> {
+        // Some invalid bytes.
+        let invalid = vec![128, 223];
+
+        Ok(Some(str::from_utf8(&invalid)?.to_string()))
+    }
+}
+#
+# fn main() {}
+```
+
+[`FieldResult<T>`][21] is an alias for [`Result<T, FieldError>`][22], which is the [error type][1] all fallible [fields][6] must return. By using the [`?` operator][14], any type that implements the [`Display` trait][15] (which most of the error types out there do) can be automatically converted into a [`FieldError`][22].
+
+> **TIP**: If a custom conversion into a [`FieldError`][22] is needed (to [fill up `extensions`][2], for example), the [`IntoFieldError` trait][23] should be implemented.
+
+> **NOTE**: [`FieldError`][22]s are [GraphQL field errors][1] and are [not visible][9] in a [GraphQL schema][8] in any way.
+
+
+
+
+## Error payloads, `null`, and partial errors
+
+[Juniper]'s error behavior conforms to the [GraphQL specification][0].
+
+When a [field][6] returns an [error][11], the [field][6]'s result is replaced by `null`, and an additional `errors` object is created at the top level of the [response][7], and the [execution][5] is resumed.
+
+Let's run the following query against the previous example:
+```graphql
+{
+  example {
+    contents
+    foo
+  }
+}
+```
+
+If `str::from_utf8` results in a `std::str::Utf8Error`, then the following will be returned:
+```json
+{
+  "data": {
+    "example": {
+      "contents": "<Contents of the file>",
+      "foo": null
+    }
+  },
+  "errors": [{
+    "message": "invalid utf-8 sequence of 2 bytes from index 0",
+    "locations": [{"line": 2, "column": 4}]
+  }]
+}
+```
+
+> Since [`Non-Null` type][4] [fields][5] cannot be **null**, [field errors][1] are propagated to be handled by the parent [field][5]. If the parent [field][5] may be **null** then it resolves to **null**, otherwise if it is a [`Non-Null` type][4], the [field error][1] is further propagated to its parent [field][5].
+
+For example, with the following query:
+```graphql
+{
+  example {
+    contents
+  }
+}
+```
+
+If the `File::open()` above results in a `std::io::ErrorKind::PermissionDenied`, the following ill be returned:
+```json
+{
+  "data": null,
+  "errors": [{
+    "message": "Permission denied (os error 13)",
+    "locations": [{"line": 2, "column": 4}]
+  }]
+}
+```
+
+
+
+
+## Additional information
+
+Sometimes it's desirable to return additional structured error information to clients. This can be accomplished by implementing the [`IntoFieldError` trait][23]:
+```rust
+# #[macro_use] extern crate juniper;
+# use juniper::{graphql_object, FieldError, IntoFieldError, ScalarValue};
+#
+enum CustomError {
+    WhateverNotSet,
+}
+
+impl<S: ScalarValue> IntoFieldError<S> for CustomError {
+    fn into_field_error(self) -> FieldError<S> {
+        match self {
+            Self::WhateverNotSet => FieldError::new(
+                "Whatever does not exist",
+                graphql_value!({
+                    "type": "NO_WHATEVER"
+                }),
+            ),
+        }
+    }
+}
+
+struct Example {
+    whatever: Option<bool>,
+}
+
+#[graphql_object]
+impl Example {
+    fn whatever(&self) -> Result<bool, CustomError> {
+        if let Some(value) = self.whatever {
+            return Ok(value);
+        }
+        Err(CustomError::WhateverNotSet)
+    }
+}
+#
+# fn main() {}
+```
+And the specified structured error information will be included into the [error's `extensions`][2]:
+```json
+{
+  "errors": [{
+    "message": "Whatever does not exist",
+    "locations": [{"line": 2, "column": 4}],
+    "extensions": {
+      "type": "NO_WHATEVER"
+    }
+  }]
+}
+```
+> **NOTE**: This pattern is particularly useful when it comes to instrumentation of returned [field errors][1] with custom error codes or additional diagnostics (like stack traces or tracing IDs).
+
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Handling-Field-Errors
+[1]: https://spec.graphql.org/October2021#sec-Errors.Field-errors
+[2]: https://spec.graphql.org/October2021#sel-GAPHRPZCAACCC_7Q
+[4]: https://spec.graphql.org/October2021#sec-Non-Null
+[5]: https://spec.graphql.org/October2021#sec-Execution
+[6]: https://spec.graphql.org/October2021#sec-Language.Fields
+[7]: https://spec.graphql.org/October2021#sec-Response
+[8]: https://graphql.org/learn/schema
+[9]: https://spec.graphql.org/October2021#sec-Introspection
+[11]: https://doc.rust-lang.org/book/ch09-00-error-handling.html
+[12]: https://doc.rust-lang.org/stable/std/result/enum.Result.html
+[13]: https://doc.rust-lang.org/stable/std/macro.panic.html
+[14]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator
+[15]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
+[21]: https://docs.rs/juniper/latest/juniper/executor/type.FieldResult.html
+[22]: https://docs.rs/juniper/latest/juniper/executor/struct.FieldError.html
+[23]: https://docs.rs/juniper/latest/juniper/executor/trait.IntoFieldError.html
diff --git a/book/src/types/objects/error/index.md b/book/src/types/objects/error/index.md
new file mode 100644
index 000000000..c4c4dd262
--- /dev/null
+++ b/book/src/types/objects/error/index.md
@@ -0,0 +1,26 @@
+Error handling
+==============
+
+Error handling in [GraphQL] can be done in multiple ways. We will cover the two different error handling models mostly used: 
+1. [Implicit field results](field.md). 
+2. [Explicit errors backend by GraphQL schema](schema.md). 
+
+Choosing the right error handling method depends on the requirements of the application and the concrete error happening. Investigating both approaches is beneficial.
+
+
+
+
+## Comparison
+
+The [first approach](field.md) (where every error is a [field error][1]) is easier to implement. However, clients won't know what errors may occur and instead will have to infer what happens from the [error message][2]. This is brittle and could change over time due to either clients or server changing. Therefore, extensive integration testing between clients and server is required to maintain the implicit contract between the two.
+
+[Encoding non-critical errors in a GraphQL schema](schema.md) makes the contract between clients and the server explicit. This allows clients to understand and handle these errors correctly and the server to know when changes are potentially breaking clients. However, encoding this error information into a [GraphQL schema][8] requires additional code and up-front definition of non-critical errors.
+
+
+
+
+[GraphQL]: https://graphql.org
+
+[1]: https://spec.graphql.org/October2021#sec-Errors.Field-errors
+[2]: https://spec.graphql.org/October2021/#sel-GAPHRPDCAACCyD57Z
+[8]: https://graphql.org/learn/schema
diff --git a/book/src/types/objects/error/schema.md b/book/src/types/objects/error/schema.md
new file mode 100644
index 000000000..8c4666c5d
--- /dev/null
+++ b/book/src/types/objects/error/schema.md
@@ -0,0 +1,336 @@
+Schema errors
+=============
+
+[Rust]'s model of errors can be adapted for [GraphQL]. [Rust]'s panic is similar to a [field error][1] - the whole query is aborted and nothing can be extracted (except for error related information).
+
+Not all errors require this strict handling. Recoverable or partial errors can be put into a [GraphQL schema][8], so the client can intelligently handle them.
+
+To implement this approach, all errors must be partitioned into two classes:
+- _Critical_ errors that cannot be fixed by clients (e.g. a database error).
+- _Recoverable_ errors that can be fixed by clients (e.g. invalid input data).
+
+Critical errors are returned from resolvers as [field errors][1] (from the [previous chapter](field.md)). Recoverable errors are part of a [GraphQL schema][8] and can be handled gracefully by clients. Similar to [Rust], [GraphQL] allows similar error models with [unions][9] (see ["Unions" chapter](../../unions.md)).
+
+
+### Example: Simple
+
+In this example, basic input validation is implemented with [GraphQL types][7]. [Strings][5] are used to identify the problematic [field][6] name. Errors for a particular [field][6] are also returned as a [string][5].
+```rust
+# extern crate juniper;
+# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
+#
+#[derive(GraphQLObject)]
+pub struct Item {
+    name: String,
+    quantity: i32,
+}
+
+#[derive(GraphQLObject)]
+pub struct ValidationError {
+    field: String,
+    message: String,
+}
+
+#[derive(GraphQLObject)]
+pub struct ValidationErrors {
+    errors: Vec<ValidationError>,
+}
+
+#[derive(GraphQLUnion)]
+pub enum GraphQLResult {
+    Ok(Item),
+    Err(ValidationErrors),
+}
+
+pub struct Mutation;
+
+#[graphql_object]
+impl Mutation {
+    fn add_item(&self, name: String, quantity: i32) -> GraphQLResult {
+        let mut errors = Vec::new();
+
+        if !(10 <= name.len() && name.len() <= 100) {
+            errors.push(ValidationError {
+                field: "name".into(),
+                message: "between 10 and 100".into(),
+            });
+        }
+
+        if !(1 <= quantity && quantity <= 10) {
+            errors.push(ValidationError {
+                field: "quantity".into(),
+                message: "between 1 and 10".into(),
+            });
+        }
+
+        if errors.is_empty() {
+            GraphQLResult::Ok(Item { name, quantity })
+        } else {
+            GraphQLResult::Err(ValidationErrors { errors })
+        }
+    }
+}
+#
+# fn main() {}
+```
+
+Each function may have a different return type and depending on the input parameters a new result type may be required. For example, adding a `User` would require a new result type containing the variant `Ok(User)`instead of `Ok(Item)`.
+
+> **NOTE**: In this example the returned [string][5] contains a server-side localized error message. However, it is also
+possible to return a unique string identifier and have the client present a localized string to its users.
+
+The client can send a mutation request and handle the resulting errors in the following manner:
+```graphql
+{
+  mutation {
+    addItem(name: "", quantity: 0) {
+      ... on Item {
+        name
+      }
+      ... on ValidationErrors {
+        errors {
+          field
+          message
+        }
+      }
+    }
+  }
+}
+```
+
+> **NOTE**: A useful side effect of this approach is to have partially successful queries or mutations. If one resolver fails, the results of the successful resolvers are not discarded.
+
+
+### Example: Complex
+
+Instead of using [strings][5] to propagate errors, it is possible to use [GraphQL type system][7] to describe the errors more precisely.
+
+For each fallible [input argument][4] we create a [field][6] in a [GraphQL object][10]. The [field][6] is set if the validation for that particular [argument][4] fails.
+```rust
+# extern crate juniper;
+# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
+#
+#[derive(GraphQLObject)]
+pub struct Item {
+    name: String,
+    quantity: i32,
+}
+
+#[derive(GraphQLObject)]
+pub struct ValidationError {
+    name: Option<String>,
+    quantity: Option<String>,
+}
+
+#[derive(GraphQLUnion)]
+pub enum GraphQLResult {
+    Ok(Item),
+    Err(ValidationError),
+}
+
+pub struct Mutation;
+
+#[graphql_object]
+impl Mutation {
+    fn add_item(&self, name: String, quantity: i32) -> GraphQLResult {
+        let mut error = ValidationError {
+            name: None,
+            quantity: None,
+        };
+
+        if !(10 <= name.len() && name.len() <= 100) {
+            error.name = Some("between 10 and 100".into());
+        }
+
+        if !(1 <= quantity && quantity <= 10) {
+            error.quantity = Some("between 1 and 10".into());
+        }
+
+        if error.name.is_none() && error.quantity.is_none() {
+            GraphQLResult::Ok(Item { name, quantity })
+        } else {
+            GraphQLResult::Err(error)
+        }
+    }
+}
+#
+# fn main() {}
+```
+
+> **NOTE**: We will likely want some kind of code generation to reduce repetition as the number of types required is significantly larger than before. Each resolver function has a custom `ValidationResult` which contains only [fields][6] provided by the function.
+
+So, all the expected errors are handled directly inside the query. Additionally, all non-critical errors are known in advance by both the server and the client:
+```graphql
+{
+  mutation {
+    addItem {
+      ... on Item {
+        name
+      }
+      ... on ValidationErrorsItem {
+        name
+        quantity
+      }
+    }
+  }
+}
+```
+
+
+### Example: Complex with critical errors
+
+Our examples so far have only included non-critical errors. Providing errors inside a [GraphQL schema][8] still allows us to return unexpected critical errors when they occur.
+
+In the following example, a theoretical database could fail and would generate errors. Since it is not common for a database to fail, the corresponding error is returned as a [critical error][1]:
+```rust
+# extern crate juniper;
+# use juniper::{graphql_object, graphql_value, FieldError, GraphQLObject, GraphQLUnion, ScalarValue};
+#
+#[derive(GraphQLObject)]
+pub struct Item {
+    name: String,
+    quantity: i32,
+}
+
+#[derive(GraphQLObject)]
+pub struct ValidationErrorItem {
+    name: Option<String>,
+    quantity: Option<String>,
+}
+
+#[derive(GraphQLUnion)]
+pub enum GraphQLResult {
+    Ok(Item),
+    Err(ValidationErrorItem),
+}
+
+pub enum ApiError {
+    Database,
+}
+
+impl<S: ScalarValue> juniper::IntoFieldError<S> for ApiError {
+    fn into_field_error(self) -> FieldError<S> {
+        match self {
+            Self::Database => FieldError::new(
+                "Internal database error",
+                graphql_value!({"type": "DATABASE"}),
+            ),
+        }
+    }
+}
+
+pub struct Mutation;
+
+#[graphql_object]
+impl Mutation {
+    fn add_item(&self, name: String, quantity: i32) -> Result<GraphQLResult, ApiError> {
+        let mut error = ValidationErrorItem {
+            name: None,
+            quantity: None,
+        };
+
+        if !(10 <= name.len() && name.len() <= 100) {
+            error.name = Some("between 10 and 100".into());
+        }
+
+        if !(1 <= quantity && quantity <= 10) {
+            error.quantity = Some("between 1 and 10".into());
+        }
+
+        if error.name.is_none() && error.quantity.is_none() {
+            Ok(GraphQLResult::Ok(Item { name, quantity }))
+        } else {
+            Ok(GraphQLResult::Err(error))
+        }
+    }
+}
+#
+# fn main() {}
+```
+
+
+### Example: Shopify API
+
+The [Shopify API] implements a similar approach. Their API is a good reference to explore this approach in a real world application.
+
+
+### Example: Non-struct [objects][10]
+
+Up until now, we've only looked at mapping [structs][20] to [GraphQL objects][10]. However, any [Rust] type can be exposed a [GraphQL object][10]. 
+
+Using `Result`-like [enums][1] can be a useful way of reporting validation errors from a mutation:
+```rust
+# extern crate juniper;
+# use juniper::{graphql_object, GraphQLObject};
+#
+#[derive(GraphQLObject)] 
+struct User { 
+    name: String,
+}
+
+#[derive(GraphQLObject)]
+struct ValidationError {
+    field: String,
+    message: String,
+}
+
+enum SignUpResult {
+    Ok(User),
+    Error(Vec<ValidationError>),
+}
+
+#[graphql_object]
+impl SignUpResult {
+    fn user(&self) -> Option<&User> {
+        match self {
+            Self::Ok(user) => Some(user),
+            Self::Error(_) => None,
+        }
+    }
+
+    fn error(&self) -> Option<&[ValidationError]> {
+        match self {
+            Self::Ok(_) => None,
+            Self::Error(errs) => Some(errs.as_slice())
+        }
+    }
+}
+#
+# fn main() {}
+```
+
+Here, we use an [enum][21] to decide whether a client's input data is valid or not, and it could be used as the result of e.g. a `signUp` mutation:
+```graphql
+{
+  mutation {
+    signUp(name: "wrong") {
+      user {
+          name
+      }
+      error {
+          field
+          message
+      }
+    }
+  }
+}
+```
+
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[Shopify API]: https://shopify.dev/docs/admin-api/graphql/reference
+
+[1]: https://spec.graphql.org/October2021#sec-Errors.Field-errors
+[4]: https://spec.graphql.org/October2021#sec-Language.Arguments
+[5]: https://spec.graphql.org/October2021#sec-String
+[6]: https://spec.graphql.org/October2021#sec-Language.Fields
+[7]: https://spec.graphql.org/October2021#sec-Types
+[8]: https://graphql.org/learn/schema
+[9]: https://spec.graphql.org/October2021#sec-Unions
+[10]: https://spec.graphql.org/October2021#sec-Objects
+[20]: https://doc.rust-lang.org/reference/items/structs.html
+[21]: https://doc.rust-lang.org/reference/items/enumerations.html
diff --git a/book/src/types/objects/error_handling.md b/book/src/types/objects/error_handling.md
deleted file mode 100644
index 5404c4bf0..000000000
--- a/book/src/types/objects/error_handling.md
+++ /dev/null
@@ -1,467 +0,0 @@
-# Error handling
-
-Error handling in GraphQL can be done in multiple ways. In the
-following two different error handling models are discussed: field
-results and GraphQL schema backed errors. Each approach has its
-advantages. Choosing the right error handling method depends on the
-requirements of the application--investigating both approaches is
-beneficial.
-
-## Field Results
-
-Rust
-[provides](https://doc.rust-lang.org/book/second-edition/ch09-00-error-handling.html)
-two ways of dealing with errors: `Result<T, E>` for recoverable errors and
-`panic!` for unrecoverable errors. Juniper does not do anything about panicking;
-it will bubble up to the surrounding framework and hopefully be dealt with
-there.
-
-For recoverable errors, Juniper works well with the built-in `Result` type, you
-can use the `?` operator and things will generally just work as you expect them to:
-
-```rust
-# extern crate juniper;
-use std::{
-    str,
-    path::PathBuf,
-    fs::{File},
-    io::{Read},
-};
-use juniper::{graphql_object, FieldResult};
-
-struct Example {
-    filename: PathBuf,
-}
-
-#[graphql_object]
-impl Example {
-    fn contents(&self) -> FieldResult<String> {
-        let mut file = File::open(&self.filename)?;
-        let mut contents = String::new();
-        file.read_to_string(&mut contents)?;
-        Ok(contents)
-    }
-
-    fn foo() -> FieldResult<Option<String>> {
-        // Some invalid bytes.
-        let invalid = vec![128, 223];
-
-        Ok(Some(str::from_utf8(&invalid)?.to_string()))
-    }
-}
-#
-# fn main() {}
-```
-
-`FieldResult<T>` is an alias for `Result<T, FieldError>`, which is the error
-type all fields must return. By using the `?` operator or `try!` macro, any type
-that implements the `Display` trait - which are most of the error types out
-there - those errors are automatically converted into `FieldError`.
-
-## Error payloads, `null`, and partial errors
-
-Juniper's error behavior conforms to the [GraphQL specification](https://spec.graphql.org/October2021#sec-Handling-Field-Errors).
-
-When a field returns an error, the field's result is replaced by `null`, an
-additional `errors` object is created at the top level of the response, and the
-execution is resumed. For example, with the previous example and the following
-query:
-
-```graphql
-{
-  example {
-    contents
-    foo
-  }
-}
-```
-
-If `str::from_utf8` resulted in a `std::str::Utf8Error`, the following would be
-returned:
-
-!FILENAME Response for nullable field with error
-
-```json
-{
-  "data": {
-    "example": {
-      contents: "<Contents of the file>",
-      foo: null
-    }
-  },
-  "errors": [
-    "message": "invalid utf-8 sequence of 2 bytes from index 0",
-    "locations": [{ "line": 2, "column": 4 }])
-  ]
-}
-```
-
-If an error is returned from a non-null field, such as the
-example above, the `null` value is propagated up to the first nullable parent
-field, or the root `data` object if there are no nullable fields.
-
-For example, with the following query:
-
-```graphql
-{
-  example {
-    contents
-  }
-}
-```
-
-If `File::open()` above resulted in `std::io::ErrorKind::PermissionDenied`, the
-following would be returned:
-
-!FILENAME Response for non-null field with error and no nullable parent
-
-```json
-{
-  "errors": [
-    "message": "Permission denied (os error 13)",
-    "locations": [{ "line": 2, "column": 4 }])
-  ]
-}
-```
-
-
-### Structured errors
-
-Sometimes it is desirable to return additional structured error information
-to clients. This can be accomplished by implementing [`IntoFieldError`](https://docs.rs/juniper/latest/juniper/trait.IntoFieldError.html):
-
-```rust
-# #[macro_use] extern crate juniper;
-# use juniper::{graphql_object, FieldError, IntoFieldError, ScalarValue};
-#
-enum CustomError {
-    WhateverNotSet,
-}
-
-impl<S: ScalarValue> IntoFieldError<S> for CustomError {
-    fn into_field_error(self) -> FieldError<S> {
-        match self {
-            CustomError::WhateverNotSet => FieldError::new(
-                "Whatever does not exist",
-                graphql_value!({
-                    "type": "NO_WHATEVER"
-                }),
-            ),
-        }
-    }
-}
-
-struct Example {
-    whatever: Option<bool>,
-}
-
-#[graphql_object]
-impl Example {
-    fn whatever(&self) -> Result<bool, CustomError> {
-        if let Some(value) = self.whatever {
-            return Ok(value);
-        }
-        Err(CustomError::WhateverNotSet)
-    }
-}
-#
-# fn main() {}
-```
-
-The specified structured error information is included in the [`extensions`](https://spec.graphql.org/October2021#sec-Errors) key:
-
-```json
-{
-  "errors": [{
-    "message": "Whatever does not exist",
-    "locations": [{"line": 2, "column": 4}],
-    "extensions": {
-      "type": "NO_WHATEVER"
-    }
-  }]
-}
-```
-
-## Errors Backed by GraphQL's Schema
-
-Rust's model of errors can be adapted for GraphQL. Rust's panic is
-similar to a `FieldError`--the whole query is aborted and nothing can
-be extracted (except for error related information).
-
-Not all errors require this strict handling. Recoverable or partial errors can be put
-into the GraphQL schema so the client can intelligently handle them.
-
-To implement this approach, all errors must be partitioned into two error classes:
-
-* Critical errors that cannot be fixed by the user (e.g. a database error).
-* Recoverable errors that can be fixed by the user (e.g. invalid input data).
-
-Critical errors are returned from resolvers as `FieldErrors` (from the previous section). Non-critical errors are part of the GraphQL schema and can be handled gracefully by clients. Similar to Rust, GraphQL allows similar error models with unions (see Unions).
-
-### Example Input Validation (simple)
-
-In this example, basic input validation is implemented with GraphQL
-types. Strings are used to identify the problematic field name. Errors
-for a particular field are also returned as a string. In this example
-the string contains a server-side localized error message. However, it is also
-possible to return a unique string identifier and have the client present a localized string to the user.
-
-```rust
-# extern crate juniper;
-# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
-#
-#[derive(GraphQLObject)]
-pub struct Item {
-    name: String,
-    quantity: i32,
-}
-
-#[derive(GraphQLObject)]
-pub struct ValidationError {
-    field: String,
-    message: String,
-}
-
-#[derive(GraphQLObject)]
-pub struct ValidationErrors {
-    errors: Vec<ValidationError>,
-}
-
-#[derive(GraphQLUnion)]
-pub enum GraphQLResult {
-    Ok(Item),
-    Err(ValidationErrors),
-}
-
-pub struct Mutation;
-
-#[graphql_object]
-impl Mutation {
-    fn addItem(&self, name: String, quantity: i32) -> GraphQLResult {
-        let mut errors = Vec::new();
-
-        if !(10 <= name.len() && name.len() <= 100) {
-            errors.push(ValidationError {
-                field: "name".into(),
-                message: "between 10 and 100".into(),
-            });
-        }
-
-        if !(1 <= quantity && quantity <= 10) {
-            errors.push(ValidationError {
-                field: "quantity".into(),
-                message: "between 1 and 10".into(),
-            });
-        }
-
-        if errors.is_empty() {
-            GraphQLResult::Ok(Item { name, quantity })
-        } else {
-            GraphQLResult::Err(ValidationErrors { errors })
-        }
-    }
-}
-#
-# fn main() {}
-```
-
-Each function may have a different return type and depending on the input
-parameters a new result type is required. For example, adding a user
-requires a new result type which contains the variant `Ok(User)`
-instead of `Ok(Item)`.
-
-The client can send a mutation request and handle the
-resulting errors as shown in the following example:
-
-```graphql
-{
-  mutation {
-    addItem(name: "", quantity: 0) {
-      ... on Item {
-        name
-      }
-      ... on ValidationErrors {
-        errors {
-          field
-          message
-        }
-      }
-    }
-  }
-}
-```
-
-A useful side effect of this approach is to have partially successful
-queries or mutations. If one resolver fails, the results of the
-successful resolvers are not discarded.
-
-### Example Input Validation (complex)
-
-Instead of using strings to propagate errors, it is possible to use
-GraphQL's type system to describe the errors more precisely.
-
-For each fallible input variable a field in a GraphQL object is created. The
-field is set if the validation for that particular field fails. You will likely want some kind of code generation to reduce repetition as the number of types required is significantly larger than
-before. Each resolver function has a custom `ValidationResult` which
-contains only fields provided by the function.
-
-```rust
-# extern crate juniper;
-# use juniper::{graphql_object, GraphQLObject, GraphQLUnion};
-#
-#[derive(GraphQLObject)]
-pub struct Item {
-    name: String,
-    quantity: i32,
-}
-
-#[derive(GraphQLObject)]
-pub struct ValidationError {
-    name: Option<String>,
-    quantity: Option<String>,
-}
-
-#[derive(GraphQLUnion)]
-pub enum GraphQLResult {
-    Ok(Item),
-    Err(ValidationError),
-}
-
-pub struct Mutation;
-
-#[graphql_object]
-impl Mutation {
-    fn addItem(&self, name: String, quantity: i32) -> GraphQLResult {
-        let mut error = ValidationError {
-            name: None,
-            quantity: None,
-        };
-
-        if !(10 <= name.len() && name.len() <= 100) {
-            error.name = Some("between 10 and 100".into());
-        }
-
-        if !(1 <= quantity && quantity <= 10) {
-            error.quantity = Some("between 1 and 10".into());
-        }
-
-        if error.name.is_none() && error.quantity.is_none() {
-            GraphQLResult::Ok(Item { name, quantity })
-        } else {
-            GraphQLResult::Err(error)
-        }
-    }
-}
-#
-# fn main() {}
-```
-
-```graphql
-{
-  mutation {
-    addItem {
-      ... on Item {
-        name
-      }
-      ... on ValidationErrorsItem {
-        name
-        quantity
-      }
-    }
-  }
-}
-```
-
-Expected errors are handled directly inside the query. Additionally, all
-non-critical errors are known in advance by both the server and the client.
-
-### Example Input Validation (complex with critical error)
-
-Our examples so far have only included non-critical errors. Providing
-errors inside the GraphQL schema still allows you to return unexpected critical
-errors when they occur.
-
-In the following example, a theoretical database could fail
-and would generate errors. Since it is not common for the database to
-fail, the corresponding error is returned as a critical error:
-
-```rust
-# extern crate juniper;
-#
-use juniper::{graphql_object, graphql_value, FieldError, GraphQLObject, GraphQLUnion, ScalarValue};
-
-#[derive(GraphQLObject)]
-pub struct Item {
-    name: String,
-    quantity: i32,
-}
-
-#[derive(GraphQLObject)]
-pub struct ValidationErrorItem {
-    name: Option<String>,
-    quantity: Option<String>,
-}
-
-#[derive(GraphQLUnion)]
-pub enum GraphQLResult {
-    Ok(Item),
-    Err(ValidationErrorItem),
-}
-
-pub enum ApiError {
-    Database,
-}
-
-impl<S: ScalarValue> juniper::IntoFieldError<S> for ApiError {
-    fn into_field_error(self) -> FieldError<S> {
-        match self {
-            ApiError::Database => FieldError::new(
-                "Internal database error",
-                graphql_value!({
-                    "type": "DATABASE"
-                }),
-            ),
-        }
-    }
-}
-
-pub struct Mutation;
-
-#[graphql_object]
-impl Mutation {
-    fn addItem(&self, name: String, quantity: i32) -> Result<GraphQLResult, ApiError> {
-        let mut error = ValidationErrorItem {
-            name: None,
-            quantity: None,
-        };
-
-        if !(10 <= name.len() && name.len() <= 100) {
-            error.name = Some("between 10 and 100".into());
-        }
-
-        if !(1 <= quantity && quantity <= 10) {
-            error.quantity = Some("between 1 and 10".into());
-        }
-
-        if error.name.is_none() && error.quantity.is_none() {
-            Ok(GraphQLResult::Ok(Item { name, quantity }))
-        } else {
-            Ok(GraphQLResult::Err(error))
-        }
-    }
-}
-#
-# fn main() {}
-```
-
-## Additional Material
-
-The [Shopify API](https://shopify.dev/docs/admin-api/graphql/reference)
-implements a similar approach. Their API is a good reference to
-explore this approach in a real world application.
-
-# Comparison
-
-The first approach discussed above--where every error is a critical error defined by `FieldResult` --is easier to implement. However, the client does not know what errors may occur and must instead infer what happened from the error string. This is brittle and could change over time due to either the client or server changing. Therefore, extensive integration testing between the client and server is required to maintain the implicit contract between the two.
-
-Encoding non-critical errors in the GraphQL schema makes the contract between the client and the server explicit. This allows the client to understand and handle these errors correctly and the server to know when changes are potentially breaking clients. However, encoding this error information into the GraphQL schema requires additional code and up-front definition of non-critical errors.
diff --git a/book/src/types/objects/generics.md b/book/src/types/objects/generics.md
new file mode 100644
index 000000000..2c14ccca6
--- /dev/null
+++ b/book/src/types/objects/generics.md
@@ -0,0 +1,78 @@
+Generics
+========
+
+Yet another point where [GraphQL] and [Rust] differs is in how generics work:
+- In [Rust], almost any type could be generic - that is, take type parameters. 
+- In [GraphQL], there are only two generic types: [lists][1] and [non-`null`ables][2].
+
+This poses a restriction on what we can expose in [GraphQL] from [Rust]: no generic structs can be exposed - all type parameters must be bound. For example, we cannot expose `Result<T, E>` as a [GraphQL type][0], but we _can_ expose `Result<User, String>` as a [GraphQL type][0].
+
+Let's make a slightly more compact but generic implementation of [the last schema error example](error/schema.md#example-non-struct-objects):
+```rust
+# extern crate juniper;
+# use juniper::{graphql_object, GraphQLObject};
+#
+#[derive(GraphQLObject)] 
+struct User { 
+    name: String, 
+}
+
+#[derive(GraphQLObject)] 
+struct ForumPost { 
+    title: String,
+}
+
+#[derive(GraphQLObject)]
+struct ValidationError {
+    field: String,
+    message: String,
+}
+
+struct MutationResult<T>(Result<T, Vec<ValidationError>>);
+
+#[graphql_object]
+#[graphql(name = "UserResult")]
+impl MutationResult<User> {
+    fn user(&self) -> Option<&User> {
+        self.0.as_ref().ok()
+    }
+
+    fn error(&self) -> Option<&[ValidationError]> {
+        self.0.as_ref().err().map(Vec::as_slice)
+    }
+}
+
+#[graphql_object]
+#[graphql(name = "ForumPostResult")]
+impl MutationResult<ForumPost> {
+    fn forum_post(&self) -> Option<&ForumPost> {
+        self.0.as_ref().ok()
+    }
+
+    fn error(&self) -> Option<&[ValidationError]> {
+        self.0.as_ref().err().map(Vec::as_slice)
+    }
+}
+#
+# fn main() {}
+```
+
+Here, we've made a wrapper around a `Result` and exposed some concrete instantiations of `Result<T, E>` as distinct [GraphQL objects][3]. 
+
+> **NOTE**: The reason we needed the wrapper is of [Rust]'s [orphan rules][10] (both the `Result` and [Juniper]'s internal traits are from third-party sources).
+
+> **NOTE**: Because we're using generics, we also need to specify a `name` for our instantiated [GraphQL types][0]. Even if [Juniper] _could_ figure out the name, `MutationResult<User>` wouldn't be a [valid GraphQL type name][4]. And, also, two different [GraphQL types][0] cannot have the same `MutationResult` name, inferred by default.
+
+
+
+
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+
+[0]: https://spec.graphql.org/October2021#sec-Types
+[1]: https://spec.graphql.org/October2021#sec-List
+[2]: https://spec.graphql.org/October2021#sec-Non-Null
+[3]: https://spec.graphql.org/October2021#sec-Objects
+[4]: https://spec.graphql.org/October2021#sec-Names
+[10]: https://doc.rust-lang.org/reference/items/implementations.html#trait-implementation-coherence
diff --git a/book/src/types/objects/index.md b/book/src/types/objects/index.md
new file mode 100644
index 000000000..deeefefbe
--- /dev/null
+++ b/book/src/types/objects/index.md
@@ -0,0 +1,228 @@
+Objects
+=======
+
+> [GraphQL objects][0] represent a list of named fields, each of which yield a value of a specific type.
+
+When declaring a [GraphQL schema][schema], most of the time we deal with [GraphQL objects][0], because they are the only place where we actually define the behavior once [schema] gets [executed][1].
+
+There are two ways to define a [GraphQL object][0] in [Juniper]:
+1. The easiest way, suitable for trivial cases, is to use the [`#[derive(GraphQLObject)]` attribute][2] on a [struct], as described below.
+2. The other way, using the [`#[graphql_object]` attribute][3], is described in the ["Complex fields" chapter](complex_fields.md).
+
+
+
+
+## Trivial
+
+While any type in [Rust] can be exposed as a [GraphQL object][0], the most common one is a [struct]:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+#[derive(GraphQLObject)]
+struct Person {
+    name: String,
+    age: i32,
+}
+#
+# fn main() {}
+```
+This creates a [GraphQL object][0] type called `Person`, with two fields: `name` of type `String!`, and `age` of type `Int!`. Because of [Rust]'s type system, everything is exported as [non-`null`][4] by default.
+
+> **TIP**: If a `null`able field is required, the most obvious way is to use `Option`. Or [`Nullable`] for distinguishing between [explicit and implicit `null`s][14].
+
+
+### Documentation
+
+We should take advantage of the fact that [GraphQL] is [self-documenting][5] and add descriptions to the defined [GraphQL object][0] type and its fields. [Juniper] will automatically use associated [Rust doc comments][6] as [GraphQL descriptions][7]:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+/// Information about a person.
+#[derive(GraphQLObject)]
+struct Person {
+    /// The person's full name, including both first and last names.
+    name: String,
+
+    /// The person's age in years, rounded down.
+    age: i32,
+}
+#
+# fn main() {}
+```
+
+If using [Rust doc comments][6] is not desired (for example, when we want to keep [Rust] API docs and GraphQL schema descriptions different), the `#[graphql(description = "...")]` attribute can be used instead, which takes precedence over [Rust doc comments][6]:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+/// This doc comment is visible only in Rust API docs.
+#[derive(GraphQLObject)]
+#[graphql(description = "This description is visible only in GraphQL schema.")]
+struct Person {
+    /// This doc comment is visible only in Rust API docs.
+    #[graphql(desc = "This description is visible only in GraphQL schema.")]
+    //        ^^^^ shortcut for a `description` argument
+    name: String,
+
+    /// This doc comment is visible in both Rust API docs and GraphQL schema 
+    /// descriptions.
+    age: i32,
+}
+#
+# fn main() {}
+```
+
+
+### Renaming
+
+By default, [struct] fields are converted from [Rust]'s standard `snake_case` naming convention into [GraphQL]'s `camelCase` convention:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+#[derive(GraphQLObject)]
+struct Person {
+    first_name: String, // exposed as `firstName` in GraphQL schema
+    last_name: String,  // exposed as `lastName` in GraphQL schema
+}
+#
+# fn main() {}
+```
+
+We can override the name by using the `#[graphql(name = "...")]` attribute:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+#[derive(GraphQLObject)]
+#[graphql(name = "WebPerson")] // now exposed as `WebPerson` in GraphQL schema
+struct Person {
+    name: String,
+    age: i32,
+    #[graphql(name = "websiteURL")]
+    website_url: Option<String>, // now exposed as `websiteURL` in GraphQL schema
+}
+#
+# fn main() {}
+```
+
+Or provide a different renaming policy for all the [struct] fields:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+#[derive(GraphQLObject)]
+#[graphql(rename_all = "none")] // disables any renaming
+struct Person {
+    name: String,
+    age: i32,
+    website_url: Option<String>, // exposed as `website_url` in GraphQL schema
+}
+#
+# fn main() {}
+```
+> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
+
+
+### Deprecation
+
+To [deprecate][9] a [GraphQL object][0] field, either the `#[graphql(deprecated = "...")]` attribute, or [Rust's `#[deprecated]` attribute][13], should be used:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+#[derive(GraphQLObject)]
+struct Person {
+    name: String,
+    age: i32,
+    #[graphql(deprecated = "Please use the `name` field instead.")]
+    first_name: String,
+    #[deprecated(note = "Please use the `name` field instead.")]
+    last_name: String,
+}
+#
+# fn main() {}
+```
+> **NOTE**: Only [GraphQL object][0]/[interface][11] fields and [GraphQL enum][10] values can be [deprecated][9].
+
+
+### Ignoring
+
+By default, all [struct] fields are included into the generated [GraphQL object][0] type. To prevent inclusion of a specific field annotate it with the `#[graphql(ignore)]` attribute:
+```rust
+# #![allow(dead_code)]
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+#[derive(GraphQLObject)]
+struct Person {
+    name: String,
+    age: i32,
+    #[graphql(ignore)]
+    password_hash: String, // cannot be queried from GraphQL
+    #[graphql(skip)]
+    //        ^^^^ alternative naming, up to your preference
+    is_banned: bool,       // cannot be queried from GraphQL
+}
+#
+# fn main() {}
+```
+
+> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLObject)]`][2] attribute.
+
+
+
+
+## Relationships
+
+[GraphQL object][0] fields can be of any [GraphQL] type, except [input objects][8].
+
+Let's see what it means to build relationships between [objects][0]:
+```rust
+# extern crate juniper;
+# use juniper::GraphQLObject;
+#
+#[derive(GraphQLObject)]
+struct Person {
+    name: String,
+    age: i32,
+}
+
+#[derive(GraphQLObject)]
+struct House {
+    address: Option<String>,  // converted into `String` (`null`able)
+    inhabitants: Vec<Person>, // converted into `[Person!]!`
+}
+#
+# fn main() {}
+```
+
+Because `Person` is a valid [GraphQL] type, we can have a `Vec<Person>` in a [struct], and it'll be automatically converted into a [list][12] of [non-`null`able][4] `Person` [objects][0].
+
+
+
+
+[`Nullable`]: https://docs.rs/juniper/latest/juniper/enum.Nullable.html
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
+[schema]: https://graphql.org/learn/schema
+[struct]: https://doc.rust-lang.org/reference/items/structs.html
+
+[0]: https://spec.graphql.org/October2021#sec-Objects
+[1]: https://spec.graphql.org/October2021#sec-Execution
+[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLObject.html
+[3]: https://docs.rs/juniper/latest/juniper/attr.graphql_object.html
+[4]: https://spec.graphql.org/October2021#sec-Non-Null
+[5]: https://spec.graphql.org/October2021#sec-Introspection
+[6]: https://doc.rust-lang.org/reference/comments.html#doc-comments
+[7]: https://spec.graphql.org/October2021#sec-Descriptions
+[8]: https://spec.graphql.org/October2021#sec-Input-Objects
+[9]: https://spec.graphql.org/October2021#sec--deprecated
+[10]: https://spec.graphql.org/October2021#sec-Enums
+[11]: https://spec.graphql.org/October2021#sec-Interfaces
+[12]: https://spec.graphql.org/October2021#sec-List
+[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
+[14]: https://spec.graphql.org/October2021#sel-EAFdRDHAAEJDAoBxzT
diff --git a/book/src/types/objects/using_contexts.md b/book/src/types/objects/using_contexts.md
deleted file mode 100644
index b63f90b80..000000000
--- a/book/src/types/objects/using_contexts.md
+++ /dev/null
@@ -1,150 +0,0 @@
-# Using contexts
-
-The context type is a feature in Juniper that lets field resolvers access global
-data, most commonly database connections or authentication information. The
-context is usually created from a _context factory_. How this is defined is
-specific to the framework integration you're using, so check out the
-documentation for [Rocket](../../servers/rocket.md) integration.
-
-In this chapter, we'll show you how to define a context type and use it in field
-resolvers. Let's say that we have a simple user database in a `HashMap`:
-
-```rust
-# #![allow(dead_code)]
-# use std::collections::HashMap;
-#
-struct Database {
-    users: HashMap<i32, User>,
-}
-
-struct User {
-    id: i32,
-    name: String,
-    friend_ids: Vec<i32>,
-}
-#
-# fn main() { }
-```
-
-We would like a `friends` field on `User` that returns a list of `User` objects.
-In order to write such a field though, the database must be queried.
-
-To solve this, we mark the `Database` as a valid context type and assign it to
-the user object. 
-
-To gain access to the context, we need to specify an argument with the same 
-type as the specified `Context` for the type:
-
-
-```rust
-# extern crate juniper;
-# use std::collections::HashMap;
-# use juniper::graphql_object;
-#
-// This struct represents our context.
-struct Database {
-    users: HashMap<i32, User>,
-}
-
-// Mark the Database as a valid context type for Juniper
-impl juniper::Context for Database {}
-
-struct User {
-    id: i32,
-    name: String,
-    friend_ids: Vec<i32>,
-}
-
-// Assign Database as the context type for User
-#[graphql_object(context = Database)]
-impl User {
-    // Inject the context by specifying an argument with the context type.
-    // Note: 
-    //   - the type must be a reference
-    //   - the name of the argument SHOULD be `context`
-    fn friends<'db>(&self, context: &'db Database) -> Vec<&'db User> {
-        // Use the database to lookup users
-        self.friend_ids.iter()
-            .map(|id| context.users.get(id).expect("Could not find user with ID"))
-            .collect()
-    }
-
-    fn name(&self) -> &str { 
-        self.name.as_str() 
-    }
-
-    fn id(&self) -> i32 { 
-        self.id 
-    }
-}
-#
-# fn main() { }
-```
-
-You only get an immutable reference to the context, so if you want to affect
-change to the execution, you'll need to use [interior
-mutability](https://doc.rust-lang.org/book/first-edition/mutability.html#interior-vs-exterior-mutability)
-using e.g. `RwLock` or `RefCell`.
-
-
-
-
-## Dealing with mutable references
-
-Context cannot be specified by a mutable reference, because concurrent fields resolving may be performed. If you have something in your context that requires access by mutable reference, then you need to leverage the [interior mutability][1] for that.
-
-For example, when using async runtime with [work stealing][2] (like `tokio`), which obviously requires thread safety in addition, you will need to use a corresponding async version of `RwLock`:
-```rust
-# extern crate juniper;
-# extern crate tokio;
-# use std::collections::HashMap;
-# use juniper::graphql_object;
-use tokio::sync::RwLock;
-
-struct Database {
-    requested_count: HashMap<i32, i32>,
-}
-
-// Since we cannot directly implement juniper::Context
-// for RwLock we use the newtype idiom
-struct DatabaseContext(RwLock<Database>);
-
-impl juniper::Context for DatabaseContext {}
-
-struct User {
-    id: i32,
-    name: String
-}
-
-#[graphql_object(context=DatabaseContext)]
-impl User {
-    async fn times_requested<'db>(&self, context: &'db DatabaseContext) -> i32 {
-        // Acquire a mutable reference and await if async RwLock is used,
-        // which is necessary if context consists async operations like 
-        // querying remote databases.
-        // Obtain base type
-        let DatabaseContext(context) = context;
-        // If context is immutable use .read() on RwLock.
-        let mut context = context.write().await;
-        // Perform a mutable operation.
-        context.requested_count.entry(self.id).and_modify(|e| { *e += 1 }).or_insert(1).clone()
-    }
-
-    fn name(&self) -> &str { 
-        self.name.as_str() 
-    }
-
-    fn id(&self) -> i32 { 
-        self.id 
-    }
-}
-#
-# fn main() { }
-```
-Replace `tokio::sync::RwLock` with `std::sync::RwLock` (or similar) if you don't intend to use async resolving.
-
-
-
-
-[1]: https://doc.rust-lang.org/book/ch15-05-interior-mutability.html
-[2]: https://en.wikipedia.org/wiki/Work_stealing
diff --git a/book/src/types/other-index.md b/book/src/types/other-index.md
deleted file mode 100644
index 83be17d7e..000000000
--- a/book/src/types/other-index.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Other Types
-
-The GraphQL type system provides several types in addition to objects.
-
-Find out more about each type below:
-
-- [Enums](enums.md)
-- [Interfaces](interfaces.md)
-- [Input objects](input_objects.md)
-- [Scalars](scalars.md)
-- [Unions](unions.md)
diff --git a/book/src/types/scalars.md b/book/src/types/scalars.md
index 8fbe88ede..92f539e8f 100644
--- a/book/src/types/scalars.md
+++ b/book/src/types/scalars.md
@@ -1,118 +1,88 @@
-# Scalars
+Scalars
+=======
 
-Scalars are the primitive types at the leaves of a GraphQL query: numbers,
-strings, and booleans. You can create custom scalars to other primitive values,
-but this often requires coordination with the client library intended to consume
-the API you're building.
+[GraphQL scalars][0] represent primitive leaf values in a GraphQL type system: numbers, strings, and booleans.
 
-Since any value going over the wire is eventually transformed into JSON, you're
-also limited in the data types you can use.
 
-There are two ways to define custom scalars.
-* For simple scalars that just wrap a primitive type, you can use the newtype pattern with
-a custom derive.
-* For more advanced use cases with custom validation, you can use
-the `graphql_scalar` proc macro.
 
 
-## Built-in scalars
+## Built-in
 
-Juniper has built-in support for:
+[Juniper] provides support for all the [built-in scalars][5].
 
-* `i32` as `Int`
-* `f64` as `Float`
-* `String` and `&str` as `String`
-* `bool` as `Boolean`
-* `juniper::ID` as `ID`. This type is defined [in the
-  spec](https://spec.graphql.org/October2021#sec-ID) as a type that is serialized
-  as a string but can be parsed from both a string and an integer.
+| [Rust] types     | [GraphQL] scalar |
+|------------------|------------------|
+| `bool`           | `Boolean`        |
+| `i32`            | `Int`            |
+| `f64`            | `Float`          |
+| `String`, `&str` | `String`         |
+| `juniper::ID`    | [`ID`]           |
 
-Note that there is no built-in support for `i64`/`u64`, as the GraphQL spec [doesn't define any built-in scalars for `i64`/`u64` by default](https://spec.graphql.org/October2021#sec-Int). You may wish to leverage a [custom GraphQL scalar](#custom-scalars) in your schema to support them.
+> **NOTE**: [`ID`] scalar is [defined in the GraphQL spec][`ID`] as a type that is serialized as a string, but can be parsed from both a string and an integer.
 
-**Third party types**:
+> **TIP**: There is no built-in support for `i64`, `u64`, or other [Rust] integer types, as the [GraphQL spec doesn't define any built-in scalars for them][1] by default. Instead, to be supported, they should be defined as [custom scalars](#custom) in a [GraphQL schema][schema].
 
-Juniper has built-in support for a few additional types from common third party
-crates. They are enabled via features that are on by default.
 
-* uuid::Uuid
-* chrono::{DateTime, NaiveDate, NaiveDateTime, NaiveTime}
-* chrono_tz::Tz;
-* time::{Date, OffsetDateTime, PrimitiveDateTime, Time, UtcOffset}
-* url::Url
-* bson::oid::ObjectId
 
 
+## Custom
 
+We can create [custom scalars][2] for other primitive values, but they are still [limited in the data types for representation][1], and only introduce additional semantic meaning. This, also, often requires coordination with the client library, intended to consume the API we're building.
 
-## Custom scalars
+[Custom scalars][2] can be defined in [Juniper] by using either [`#[derive(GraphQLScalar)]`][8] or [`#[graphql_scalar]`][9] attributes, which do work pretty much the same way (except, [`#[derive(GraphQLScalar)]`][8] cannot be used on [type aliases][4]).
 
-### `#[graphql(transparent)]` attribute
 
-Often, you might need a custom scalar that just wraps an existing type.
-
-This can be done with the newtype pattern and a custom derive, similar to how
-serde supports this pattern with `#[serde(transparent)]`.
+### Transparent delegation
 
+Quite often, we want to create a [custom GraphQL scalar][2] type by just wrapping an existing one, inheriting all its behavior. In [Rust], this is often called as ["newtype pattern"][3]. This may be achieved by providing a `#[graphql(transparent)]` attribute to the definition:
 ```rust
 # extern crate juniper;
+# use juniper::{graphql_scalar, GraphQLScalar};
 #
-#[derive(juniper::GraphQLScalar)]
+#[derive(GraphQLScalar)]
 #[graphql(transparent)]
 pub struct UserId(i32);
 
-#[derive(juniper::GraphQLObject)]
-struct User {
-    id: UserId,
-}
-#
-# fn main() {}
-```
-
-`#[derive(GraphQLScalar)]` is mostly interchangeable with `#[graphql_scalar]` 
-attribute:
-
-```rust
-# extern crate juniper;
-# use juniper::graphql_scalar;
-#
-#[graphql_scalar(transparent)]
-pub struct UserId {
+// Using `#[graphql_scalar]` attribute here makes no difference, and is fully
+// interchangeable with `#[derive(GraphQLScalar)]`. It's only up to the 
+// personal preference - which one to use.
+#[graphql_scalar]
+#[graphql(transparent)]
+pub struct MessageId {
   value: i32,
 }
-
-#[derive(juniper::GraphQLObject)]
-struct User {
-    id: UserId,
-}
 #
 # fn main() {}
 ```
+That's it, now the `UserId` and `MessageId` [scalars][0] can be used in [GraphQL schema][schema].
 
-That's it, you can now use `UserId` in your schema.
-
-The macro also allows for more customization:
-
+We may also customize the definition, to provide more information about our [custom scalar][2] in [GraphQL schema][schema]:
 ```rust
 # extern crate juniper;
-/// You can use a doc comment to specify a description.
-#[derive(juniper::GraphQLScalar)]
+# use juniper::GraphQLScalar;
+#
+/// You can use a Rust doc comment to specify a description in GraphQL schema.
+#[derive(GraphQLScalar)]
 #[graphql(
     transparent,
-    // Overwrite the GraphQL type name.
+    // Overwrite the name of this type in the GraphQL schema.
     name = "MyUserId",
-    // Specify a custom description.
-    // A description in the attribute will overwrite a doc comment.
-    description = "My user id description",
+    // Specifying a type description via attribute takes precedence over the
+    // Rust doc comment, which allows to separate Rust API docs from GraphQL 
+    // schema descriptions, if required.
+    description = "Actual description.",
+    // Optional specification URL.
+    specified_by_url = "https://tools.ietf.org/html/rfc4122",
 )]
-pub struct UserId(i32);
+pub struct UserId(String);
 #
 # fn main() {}
 ```
 
-All the methods used from newtype's field can be replaced with attributes:
 
-### `#[graphql(to_output_with = <fn>)]` attribute
+### Resolving
 
+In case we need to customize [resolving][7] of a [custom GraphQL scalar][2] value (change the way it gets executed), the `#[graphql(to_output_with = <fn path>)]` attribute is the way to do so:
 ```rust
 # extern crate juniper;
 # use juniper::{GraphQLScalar, ScalarValue, Value};
@@ -123,14 +93,17 @@ struct Incremented(i32);
 
 /// Increments [`Incremented`] before converting into a [`Value`].
 fn to_output<S: ScalarValue>(v: &Incremented) -> Value<S> {
-    Value::from(v.0 + 1)
+    let inc = v.0 + 1;
+    Value::from(inc)
 }
-# 
+#
 # fn main() {}
 ```
 
-### `#[graphql(from_input_with = <fn>)]` attribute
 
+### Input value parsing
+
+Customization of a [custom GraphQL scalar][2] value parsing is possible via `#[graphql(from_input_with = <fn path>)]` attribute:
 ```rust
 # extern crate juniper;
 # use juniper::{GraphQLScalar, InputValue, ScalarValue};
@@ -140,8 +113,8 @@ fn to_output<S: ScalarValue>(v: &Incremented) -> Value<S> {
 struct UserId(String);
 
 impl UserId {
-    /// Checks whether [`InputValue`] is `String` beginning with `id: ` and
-    /// strips it.
+    /// Checks whether the [`InputValue`] is a [`String`] beginning with `id: ` 
+    /// and strips it.
     fn from_input<S>(input: &InputValue<S>) -> Result<Self, String> 
     where
         S: ScalarValue
@@ -164,13 +137,15 @@ impl UserId {
 # fn main() {}
 ```
 
-### `#[graphql(parse_token_with = <fn>]` or `#[graphql(parse_token(<types>)]` attributes
 
+### Token parsing
+
+Customization of which tokens a [custom GraphQL scalar][0] type should be parsed from, is possible via `#[graphql(parse_token_with = <fn path>)]` or `#[graphql(parse_token(<types>)]` attributes:
 ```rust
 # extern crate juniper;
 # use juniper::{
-#     GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue, 
-#     ScalarValue, ScalarToken, Value
+#     GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue,
+#     ScalarValue, ScalarToken, Value,
 # };
 #
 #[derive(GraphQLScalar)]
@@ -178,32 +153,26 @@ impl UserId {
     to_output_with = to_output,
     from_input_with = from_input,
     parse_token_with = parse_token,
-//  ^^^^^^^^^^^^^^^^ Can be replaced with `parse_token(String, i32)`
-//                   which tries to parse as `String` and then as `i32`
-//                   if prior fails.
 )]
+//  ^^^^^^^^^^^^^^^^ Can be replaced with `parse_token(String, i32)`, which
+//                   tries to parse as `String` first, and then as `i32` if
+//                   prior fails.
 enum StringOrInt {
     String(String),
     Int(i32),
 }
 
-fn to_output<S>(v: &StringOrInt) -> Value<S> 
-where
-    S: ScalarValue
-{
+fn to_output<S: ScalarValue>(v: &StringOrInt) -> Value<S> {
     match v {
         StringOrInt::String(s) => Value::scalar(s.to_owned()),
         StringOrInt::Int(i) => Value::scalar(*i),
     }
 }
 
-fn from_input<S>(v: &InputValue<S>) -> Result<StringOrInt, String> 
-where
-    S: ScalarValue
-{
+fn from_input<S: ScalarValue>(v: &InputValue<S>) -> Result<StringOrInt, String> {
     v.as_string_value()
         .map(|s| StringOrInt::String(s.into()))
-        .or_else(|| v.as_int_value().map(|i| StringOrInt::Int(i)))
+        .or_else(|| v.as_int_value().map(StringOrInt::Int))
         .ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
 }
 
@@ -214,27 +183,62 @@ fn parse_token<S: ScalarValue>(value: ScalarToken<'_>) -> ParseScalarResult<S> {
 #
 # fn main() {}
 ```
+> **NOTE**: Once we provide all 3 custom functions, there is no sense to follow [newtype pattern][3] anymore, as nothing left to inherit.
+
+
+### Full behavior
+
+Instead of providing all custom functions separately, it's possible to provide a module holding the appropriate `to_output()`, `from_input()` and `parse_token()` functions via `#[graphql(with = <module path>)]` attribute:
+```rust
+# extern crate juniper;
+# use juniper::{
+#     GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue,
+#     ScalarValue, ScalarToken, Value,
+# };
+#
+#[derive(GraphQLScalar)]
+#[graphql(with = string_or_int)]
+enum StringOrInt {
+    String(String),
+    Int(i32),
+}
 
-> __NOTE:__ As you can see, once you provide all 3 custom resolvers, there
->           is no need to follow `newtype` pattern.
+mod string_or_int {
+    use super::*;
 
-### `#[graphql(with = <path>)]` attribute
+    pub(super) fn to_output<S: ScalarValue>(v: &StringOrInt) -> Value<S> {
+        match v {
+            StringOrInt::String(s) => Value::scalar(s.to_owned()),
+            StringOrInt::Int(i) => Value::scalar(*i),
+        }
+    }
 
-Instead of providing all custom resolvers, you can provide path to the `to_output`, 
-`from_input`, `parse_token` functions.
+    pub(super) fn from_input<S: ScalarValue>(v: &InputValue<S>) -> Result<StringOrInt, String> {
+        v.as_string_value()
+            .map(|s| StringOrInt::String(s.into()))
+            .or_else(|| v.as_int_value().map(StringOrInt::Int))
+            .ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
+    }
 
-Path can be simply `with = Self` (default path where macro expects resolvers to be), 
-in case there is an impl block with custom resolvers:
+    pub(super) fn parse_token<S: ScalarValue>(t: ScalarToken<'_>) -> ParseScalarResult<S> {
+        <String as ParseScalarValue<S>>::from_str(t)
+            .or_else(|_| <i32 as ParseScalarValue<S>>::from_str(t))
+    }
+}
+#
+# fn main() {}
+```
 
+A regular `impl` block is also suitable for that:
 ```rust
 # extern crate juniper;
 # use juniper::{
 #     GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue,
-#     ScalarValue, ScalarToken, Value
+#     ScalarValue, ScalarToken, Value,
 # };
 #
 #[derive(GraphQLScalar)]
-// #[graphql(with = Self)] <- default behaviour
+// #[graphql(with = Self)] <- default behaviour, so can be omitted
 enum StringOrInt {
     String(String),
     Int(i32),
@@ -247,20 +251,20 @@ impl StringOrInt {
             Self::Int(i) => Value::scalar(*i),
         }
     }
-  
+
     fn from_input<S>(v: &InputValue<S>) -> Result<Self, String>
     where
-        S: ScalarValue,
+        S: ScalarValue
     {
         v.as_string_value()
             .map(|s| Self::String(s.into()))
             .or_else(|| v.as_int_value().map(Self::Int))
             .ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
     }
-  
+
     fn parse_token<S>(value: ScalarToken<'_>) -> ParseScalarResult<S>
     where
-        S: ScalarValue,
+        S: ScalarValue
     {
         <String as ParseScalarValue<S>>::from_str(value)
             .or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
@@ -270,17 +274,19 @@ impl StringOrInt {
 # fn main() {}
 ```
 
-Or it can be path to a module, where custom resolvers are located.
-
+At the same time, any custom function still may be specified separately, if required:
 ```rust
 # extern crate juniper;
 # use juniper::{
-#     GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue, 
-#     ScalarValue, ScalarToken, Value
+#     GraphQLScalar, InputValue, ParseScalarResult, ScalarValue,
+#     ScalarToken, Value
 # };
 #
 #[derive(GraphQLScalar)]
-#[graphql(with = string_or_int)]
+#[graphql(
+    with = string_or_int,
+    parse_token(String, i32)
+)]
 enum StringOrInt {
     String(String),
     Int(i32),
@@ -298,7 +304,7 @@ mod string_or_int {
             StringOrInt::Int(i) => Value::scalar(*i),
         }
     }
-  
+
     pub(super) fn from_input<S>(v: &InputValue<S>) -> Result<StringOrInt, String>
     where
         S: ScalarValue,
@@ -308,62 +314,23 @@ mod string_or_int {
             .or_else(|| v.as_int_value().map(StringOrInt::Int))
             .ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
     }
-  
-    pub(super) fn parse_token<S>(value: ScalarToken<'_>) -> ParseScalarResult<S>
-    where
-        S: ScalarValue,
-    {
-        <String as ParseScalarValue<S>>::from_str(value)
-            .or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
-    }
+
+    // No need in `parse_token()` function.
 }
 #
 # fn main() {}
 ```
 
-Also, you can partially override `#[graphql(with)]` attribute with other custom scalars.
+> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLScalar)]`][8] and [`#[graphql_scalar]`][9] attributes.
+
 
-```rust
-# extern crate juniper;
-# use juniper::{GraphQLScalar, InputValue, ParseScalarResult, ScalarValue, ScalarToken, Value};
-#
-#[derive(GraphQLScalar)]
-#[graphql(parse_token(String, i32))]
-enum StringOrInt {
-    String(String),
-    Int(i32),
-}
 
-impl StringOrInt {
-    fn to_output<S>(&self) -> Value<S>
-    where
-        S: ScalarValue,
-    {
-        match self {
-            Self::String(s) => Value::scalar(s.to_owned()),
-            Self::Int(i) => Value::scalar(*i),
-        }
-    }
-  
-    fn from_input<S>(v: &InputValue<S>) -> Result<Self, String>
-    where
-        S: ScalarValue,
-    {
-        v.as_string_value()
-            .map(|s| Self::String(s.into()))
-            .or_else(|| v.as_int_value().map(Self::Int))
-            .ok_or_else(|| format!("Expected `String` or `Int`, found: {v}"))
-    }
-}
-#
-# fn main() {}
-```
 
-### Using foreign types as scalars
+## Foreign
 
-For implementing custom scalars on foreign types there is `#[graphql_scalar]` attribute macro.
+For implementing [custom scalars][2] on foreign types there is [`#[graphql_scalar]`][9] attribute.
 
-> __NOTE:__ To satisfy [orphan rules] you should provide local [`ScalarValue`] implementation.
+> **NOTE**: To satisfy [orphan rules], we should provide a local [`ScalarValue`] implementation.
 
 ```rust
 # extern crate juniper;
@@ -391,10 +358,10 @@ use juniper::{graphql_scalar, InputValue, ScalarValue, Value};
     with = date_scalar, 
     parse_token(String),
     scalar = CustomScalarValue,
-//           ^^^^^^^^^^^^^^^^^ Local `ScalarValue` implementation.
 )]
+//           ^^^^^^^^^^^^^^^^^ local `ScalarValue` implementation
 type Date = date::Date;
-//          ^^^^^^^^^^ Type from another crate.
+//          ^^^^^^^^^^ type from another crate
 
 mod date_scalar {
     use super::*;
@@ -413,5 +380,78 @@ mod date_scalar {
 # fn main() {}
 ```
 
-[orphan rules]: https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
+
+### Supported out-of-the-box
+
+[Juniper] provides out-of-the-box [GraphQL scalar][0] implementations for some very common [Rust] crates. The types from these crates will be usable in your schemas automatically after enabling the correspondent self-titled [Cargo feature].
+
+| [Rust] type                 | [GraphQL] scalar | [Cargo feature]  |
+|-----------------------------|------------------|------------------|
+| [`BigDecimal`]              | `BigDecimal`     | [`bigdecimal`]   |
+| [`bson::oid::ObjectId`]     | `ObjectId`       | [`bson`]         |
+| [`bson::DateTime`]          | `UtcDateTime`    | [`bson`]         |
+| [`chrono::NaiveDate`]       | [`Date`]         | [`chrono`]       |
+| [`chrono::NaiveTime`]       | [`LocalTime`]    | [`chrono`]       |
+| [`chrono::NaiveDateTime`]   | `LocalDateTime`  | [`chrono`]       |
+| [`chrono::DateTime`]        | [`DateTime`]     | [`chrono`]       |
+| [`chrono_tz::Tz`]           | `TimeZone`       | [`chrono-tz`]    |
+| [`Decimal`]                 | `Decimal`        | [`rust_decimal`] |
+| [`time::Date`]              | [`Date`]         | [`time`]         |
+| [`time::Time`]              | [`LocalTime`]    | [`time`]         |
+| [`time::PrimitiveDateTime`] | `LocalDateTime`  | [`time`]         |
+| [`time::OffsetDateTime`]    | [`DateTime`]     | [`time`]         |
+| [`time::UtcOffset`]         | [`UtcOffset`]    | [`time`]         |
+| [`Url`]                     | `Url`            | [`url`]          |
+| [`Uuid`]                    | `Uuid`           | [`uuid`]         |
+
+
+
+
+[`bigdecimal`]: https://docs.rs/bigdecimal
+[`BigDecimal`]: https://docs.rs/bigdecimal/latest/bigdecimal/struct.BigDecimal.html
+[`bson`]: https://docs.rs/bson
+[`bson::DateTime`]: https://docs.rs/bson/latest/bson/struct.DateTime.html
+[`bson::oid::ObjectId`]: https://docs.rs/bson/latest/bson/oid/struct.ObjectId.html
+[`chrono`]: https://docs.rs/chrono
+[`chrono::DateTime`]: https://docs.rs/chrono/latest/chrono/struct.DateTime.html
+[`chrono::NaiveDate`]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveDate.html
+[`chrono::NaiveDateTime`]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveDateTime.html
+[`chrono::NaiveTime`]: https://docs.rs/chrono/latest/chrono/naive/struct.NaiveTime.html
+[`chrono-tz`]: https://docs.rs/chrono-tz
+[`chrono_tz::Tz`]: https://docs.rs/chrono-tz/latest/chrono_tz/enum.Tz.html
+[`Date`]: https://graphql-scalars.dev/docs/scalars/date
+[`DateTime`]: https://graphql-scalars.dev/docs/scalars/date-time
+[`Decimal`]: https://docs.rs/rust_decimal/latest/rust_decimal/struct.Decimal.html
+[`ID`]: https://spec.graphql.org/October2021#sec-ID
+[`LocalTime`]: https://graphql-scalars.dev/docs/scalars/local-time
+[`rust_decimal`]: https://docs.rs/rust_decimal
 [`ScalarValue`]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
+[`serde`]: https://docs.rs/serde
+[`time`]: https://docs.rs/time
+[`time::Date`]: https://docs.rs/time/latest/time/struct.Date.html
+[`time::PrimitiveDateTime`]: https://docs.rs/time/latest/time/struct.PrimitiveDateTime.html
+[`time::Time`]: https://docs.rs/time/latest/time/struct.Time.html
+[`time::UtcOffset`]: https://docs.rs/time/latest/time/struct.UtcOffset.html
+[`time::OffsetDateTime`]: https://docs.rs/time/latest/time/struct.OffsetDateTime.html
+[`url`]: https://docs.rs/url
+[`Url`]: https://docs.rs/url/latest/url/struct.Url.html
+[`UtcOffset`]: https://graphql-scalars.dev/docs/scalars/utc-offset
+[`uuid`]: https://docs.rs/uuid
+[`Uuid`]: https://docs.rs/uuid/latest/uuid/struct.Uuid.html
+[Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[orphan rules]: https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
+[Rust]: https://www.rust-lang.org
+[schema]: https://graphql.org/learn/schema
+
+[0]: https://spec.graphql.org/October2021#sec-Scalars
+[1]: https://spec.graphql.org/October2021#sel-FAHXJDCAACKB1qb
+[2]: https://spec.graphql.org/October2021#sec-Scalars.Custom-Scalars
+[3]: https://rust-unofficial.github.io/patterns/patterns/behavioural/newtype.html
+[4]: https://doc.rust-lang.org/reference/items/type-aliases.html
+[5]: https://spec.graphql.org/October2021/#sec-Scalars.Built-in-Scalars
+[6]: https://serde.rs/container-attrs.html#transparent
+[7]: https://spec.graphql.org/October2021#sec-Value-Resolution
+[8]: https://docs.rs/juniper/latest/juniper/derive.GraphQLScalar.html
+[9]: https://docs.rs/juniper/latest/juniper/attr.graphql_scalar.html
diff --git a/book/src/types/unions.md b/book/src/types/unions.md
index bfce7f777..0f2ae68cf 100644
--- a/book/src/types/unions.md
+++ b/book/src/types/unions.md
@@ -1,25 +1,17 @@
 Unions
 ======
 
-From the server's point of view, [GraphQL unions][1] are somewhat similar to [interfaces][5] - the main difference is that they don't contain fields on their own.
+> [GraphQL unions][0] represent an object that could be one of a list of [GraphQL object][10] types, but provides for no guaranteed fields between those types. They also differ from [interfaces][12] in that [object][10] types declare what [interfaces][12] they implement, but are not aware of what [unions][0] contain them.
 
-The most obvious and straightforward way to represent a [GraphQL union][1] in Rust is enum. However, we also can do so either with trait or a regular struct. That's why, for implementing [GraphQL unions][1] Juniper provides:
-- `#[derive(GraphQLUnion)]` macro for enums and structs.
-- `#[graphql_union]` for traits.
-
-
-
-
-## Enums
-
-Most of the time, we just need a trivial and straightforward Rust enum to represent a [GraphQL union][1].
+From the server's point of view, [GraphQL unions][0] are somewhat similar to [interfaces][12]: the main difference is that they don't contain fields on their own, and so, we only need to represent a value, _dispatchable_ into concrete [objects][10].
 
+Obviously, the most straightforward approach to express [GraphQL unions][0] in [Rust] is to use [enums][22]. In [Juniper] this may be done by using [`#[derive(GraphQLInterface)]`][2] attribute on them:
 ```rust
-# extern crate juniper;
 # extern crate derive_more;
-use derive_more::From;
-use juniper::{GraphQLObject, GraphQLUnion};
-
+# extern crate juniper;
+# use derive_more::From;
+# use juniper::{GraphQLObject, GraphQLUnion};
+# 
 #[derive(GraphQLObject)]
 struct Human {
     id: String,
@@ -33,6 +25,7 @@ struct Droid {
 }
 
 #[derive(From, GraphQLUnion)]
+//       ^^^^ only for convenience, and may be omitted
 enum Character {
     Human(Human),
     Droid(Droid),
@@ -42,424 +35,94 @@ enum Character {
 ```
 
 
-### Ignoring enum variants
-
-In some rare situations we may want to omit exposing an enum variant in the GraphQL schema.
-
-As an example, let's consider the situation where we need to bind some type parameter `T` for doing interesting type-level stuff in our resolvers. To achieve this we need to have `PhantomData<T>`, but we don't want it exposed in the GraphQL schema.
-
-> __WARNING__:  
-> It's the _library user's responsibility_ to ensure that ignored enum variant is _never_ returned from resolvers, otherwise resolving the GraphQL query will __panic at runtime__.
+### Renaming
 
+Just as with [renaming GraphQL objects](objects/index.md#renaming), we can override the default [union][0] name by using the `#[graphql(name = "...")]` attribute:
 ```rust
 # extern crate juniper;
-# extern crate derive_more;
-# use std::marker::PhantomData;
-use derive_more::From;
-use juniper::{GraphQLObject, GraphQLUnion};
-
-#[derive(GraphQLObject)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-#[derive(From, GraphQLUnion)]
-enum Character<S> {
-    Human(Human),
-    Droid(Droid),
-    #[from(ignore)]
-    #[graphql(ignore)]  // or `#[graphql(skip)]`, your choice
-    _State(PhantomData<S>),
-}
+# use juniper::{GraphQLObject, GraphQLUnion};
+# 
+# #[derive(GraphQLObject)]
+# struct Human {
+#     id: String,
+#     home_planet: String,
+# }
+#
+# #[derive(GraphQLObject)]
+# struct Droid {
+#     id: String,
+#     primary_function: String,
+# }
 #
-# fn main() {}
-```
-
-
-### External resolver functions
-
-If some custom logic is needed to resolve a [GraphQL union][1] variant, you may specify an external function to do so:
-
-```rust
-# #![allow(dead_code)]
-# extern crate juniper;
-use juniper::{GraphQLObject, GraphQLUnion};
-
-#[derive(GraphQLObject)]
-#[graphql(Context = CustomContext)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-#[graphql(Context = CustomContext)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-pub struct CustomContext {
-    droid: Droid,
-}
-impl juniper::Context for CustomContext {}
-
 #[derive(GraphQLUnion)]
-#[graphql(Context = CustomContext)]
-enum Character {
+#[graphql(name = "CharacterUnion")]
+enum Character { // exposed as `CharacterUnion` in GraphQL schema
     Human(Human),
-    #[graphql(with = Character::droid_from_context)]
     Droid(Droid),
 }
-
-impl Character {
-    // NOTICE: The function signature must contain `&self` and `&Context`,
-    //         and return `Option<&VariantType>`.
-    fn droid_from_context<'c>(&self, ctx: &'c CustomContext) -> Option<&'c Droid> {
-        Some(&ctx.droid)
-    }
-}
 #
 # fn main() {}
 ```
+> **NOTE**: Unlike [Rust enum variants][22], [GraphQL union members][0] don't have any special names aside from the ones provided by [objects][10] themselves, and so, obviously, **cannot be renamed**.
+
 
-With an external resolver function we can even declare a new [GraphQL union][1] variant where the Rust type is absent in the initial enum definition. The attribute syntax `#[graphql(on VariantType = resolver_fn)]` follows the [GraphQL syntax for dispatching union variants](https://spec.graphql.org/October2021#example-f8163).
+### Documentation
 
+Similarly to [documenting GraphQL objects](objects/index.md#documentation), we can [document][7] a [GraphQL union][0] via `#[graphql(description = "...")]` attribute or [Rust doc comments][6]:
 ```rust
-# #![allow(dead_code)]
 # extern crate juniper;
-use juniper::{GraphQLObject, GraphQLUnion};
-
-#[derive(GraphQLObject)]
-#[graphql(Context = CustomContext)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-#[graphql(Context = CustomContext)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-#[derive(GraphQLObject)]
-#[graphql(Context = CustomContext)]
-struct Ewok {
-    id: String,
-    is_funny: bool,
-}
-
-pub struct CustomContext {
-    ewok: Ewok,
-}
-impl juniper::Context for CustomContext {}
-
+# use juniper::{GraphQLObject, GraphQLUnion};
+# 
+# #[derive(GraphQLObject)]
+# struct Human {
+#     id: String,
+#     home_planet: String,
+# }
+#
+# #[derive(GraphQLObject)]
+# struct Droid {
+#     id: String,
+#     primary_function: String,
+# }
+#
+/// This doc comment is visible in both Rust API docs and GraphQL schema 
+/// descriptions.
 #[derive(GraphQLUnion)]
-#[graphql(Context = CustomContext)]
-#[graphql(on Ewok = Character::ewok_from_context)]
 enum Character {
+    /// This doc comment is visible only in Rust API docs.
     Human(Human),
+    /// This doc comment is visible only in Rust API docs.
     Droid(Droid),
-    #[graphql(ignore)]  // or `#[graphql(skip)]`, your choice
-    Ewok,
-}
-
-impl Character {
-    fn ewok_from_context<'c>(&self, ctx: &'c CustomContext) -> Option<&'c Ewok> {
-        if let Self::Ewok = self {
-            Some(&ctx.ewok)
-        } else {
-            None
-        }       
-    }
 }
-#
-# fn main() {}
-```
-
-
-
-
-## Structs
-
-Using Rust structs as [GraphQL unions][1] is very similar to using enums, with the nuance that specifying an external resolver function is the only way to declare a [GraphQL union][1] variant.
-
-```rust
-# extern crate juniper;
-# use std::collections::HashMap;
-use juniper::{GraphQLObject, GraphQLUnion};
-
-#[derive(GraphQLObject)]
-#[graphql(Context = Database)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-#[graphql(Context = Database)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-struct Database {
-    humans: HashMap<String, Human>,
-    droids: HashMap<String, Droid>,
-}
-impl juniper::Context for Database {}
 
+/// This doc comment is visible only in Rust API docs.
 #[derive(GraphQLUnion)]
-#[graphql(
-    Context = Database,
-    on Human = Character::get_human,
-    on Droid = Character::get_droid,
-)]
-struct Character {
-    id: String,
-}
-
-impl Character {
-    fn get_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human>{
-        ctx.humans.get(&self.id)
-    }
-
-    fn get_droid<'db>(&self, ctx: &'db Database) -> Option<&'db Droid>{
-        ctx.droids.get(&self.id)
-    }
-}
-#
-# fn main() {}
-```
-
-
-
-
-## Traits
-
-To use a Rust trait definition as a [GraphQL union][1] you need to use the `#[graphql_union]` macro. [Rust doesn't allow derive macros on traits](https://doc.rust-lang.org/stable/reference/procedural-macros.html#derive-macros), so using `#[derive(GraphQLUnion)]` on traits doesn't work.
-
-> __NOTICE__:  
-> A __trait has to be [object safe](https://doc.rust-lang.org/stable/reference/items/traits.html#object-safety)__, because schema resolvers will need to return a [trait object](https://doc.rust-lang.org/stable/reference/types/trait-object.html) to specify a [GraphQL union][1] behind it.
-
-```rust
-# extern crate juniper;
-use juniper::{graphql_union, GraphQLObject};
-
-#[derive(GraphQLObject)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-#[graphql_union]
-trait Character {
-    // NOTICE: The method signature must contain `&self` and return `Option<&VariantType>`.
-    fn as_human(&self) -> Option<&Human> { None }
-    fn as_droid(&self) -> Option<&Droid> { None }
-}
-
-impl Character for Human {
-    fn as_human(&self) -> Option<&Human> { Some(&self) }
-}
-
-impl Character for Droid {
-    fn as_droid(&self) -> Option<&Droid> { Some(&self) }
-}
-#
-# fn main() {}
-```
-
-
-### Custom context
-
-If a [`Context`][6] is required in a trait method to resolve a [GraphQL union][1] variant, specify it as an argument.
-
-```rust
-# #![allow(unused_variables)]
-# extern crate juniper;
-# use std::collections::HashMap;
-use juniper::{graphql_union, GraphQLObject};
-
-#[derive(GraphQLObject)]
-#[graphql(Context = Database)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-#[graphql(Context = Database)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-struct Database {
-    humans: HashMap<String, Human>,
-    droids: HashMap<String, Droid>,
-}
-impl juniper::Context for Database {}
-
-#[graphql_union(context = Database)]
-trait Character {
-    // NOTICE: The method signature may optionally contain `&Context`.
-    fn as_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human> { None }
-    fn as_droid<'db>(&self, ctx: &'db Database) -> Option<&'db Droid> { None }
-}
-
-impl Character for Human {
-    fn as_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human> {
-        ctx.humans.get(&self.id)
-    }
-}
-
-impl Character for Droid {
-    fn as_droid<'db>(&self, ctx: &'db Database) -> Option<&'db Droid> {
-        ctx.droids.get(&self.id)
-    }
+#[graphql(description = "This description overwrites the one from doc comment.")]
+//        ^^^^^^^^^^^ or `desc` shortcut, up to your preference
+enum Person {
+    /// This doc comment is visible only in Rust API docs.
+    Human(Human),
 }
 #
 # fn main() {}
 ```
+> **NOTE**: Unlike [Rust enum variants][22], [GraphQL union members][0] don't have any special constructors aside from the provided [objects][10] directly, and so, **cannot be [documented][7]**, but rather reuse [object descriptions][7] "as is".
 
 
-### Ignoring trait methods
+### Ignoring
 
-As with enums, we may want to omit some trait methods to be assumed as [GraphQL union][1] variants and ignore them.
+In some rare situations we may want to omit exposing an [enum][22] variant in a [GraphQL schema][1]. [Similarly to GraphQL enums](enums.md#ignoring), we can just annotate the variant with the `#[graphql(ignore)]` attribute.
 
-```rust
-# extern crate juniper;
-use juniper::{graphql_union, GraphQLObject};
-
-#[derive(GraphQLObject)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-#[graphql_union]
-trait Character {
-    fn as_human(&self) -> Option<&Human> { None }
-    fn as_droid(&self) -> Option<&Droid> { None }
-    #[graphql(ignore)]  // or `#[graphql(skip)]`, your choice
-    fn id(&self) -> &str;
-}
-
-impl Character for Human {
-    fn as_human(&self) -> Option<&Human> { Some(&self) }
-    fn id(&self) -> &str { self.id.as_str() }
-}
-
-impl Character for Droid {
-    fn as_droid(&self) -> Option<&Droid> { Some(&self) }
-    fn id(&self) -> &str { self.id.as_str() }
-}
-#
-# fn main() {}
-```
-
-
-### External resolver functions
-
-Similarly to enums and structs, it's not mandatory to use trait methods as [GraphQL union][1] variant resolvers. Instead, custom functions may be specified:
+As an example, let's consider the situation where we need to bind some type parameter `T` for doing interesting type-level stuff in our resolvers. To achieve this we need to have `PhantomData<T>`, but we don't want it exposed in the GraphQL schema.
 
 ```rust
+# extern crate derive_more;
 # extern crate juniper;
-# use std::collections::HashMap;
-use juniper::{graphql_union, GraphQLObject};
-
-#[derive(GraphQLObject)]
-#[graphql(Context = Database)]
-struct Human {
-    id: String,
-    home_planet: String,
-}
-
-#[derive(GraphQLObject)]
-#[graphql(Context = Database)]
-struct Droid {
-    id: String,
-    primary_function: String,
-}
-
-struct Database {
-    humans: HashMap<String, Human>,
-    droids: HashMap<String, Droid>,
-}
-impl juniper::Context for Database {}
-
-#[graphql_union(context = Database)]
-#[graphql_union(
-    on Human = DynCharacter::get_human,
-    on Droid = get_droid,
-)]
-trait Character {
-    #[graphql(ignore)]  // or `#[graphql(skip)]`, your choice
-    fn id(&self) -> &str;
-}
-
-impl Character for Human {
-    fn id(&self) -> &str { self.id.as_str() }
-}
-
-impl Character for Droid {
-    fn id(&self) -> &str { self.id.as_str() }
-}
-
-// The trait object is always `Send` and `Sync`.
-type DynCharacter<'a> = dyn Character + Send + Sync + 'a;
-
-impl<'a> DynCharacter<'a> {
-    fn get_human<'db>(&self, ctx: &'db Database) -> Option<&'db Human> {
-        ctx.humans.get(self.id())
-    }
-}
-
-// External resolver function doesn't have to be a method of a type.
-// It's only a matter of the function signature to match the requirements.
-fn get_droid<'db>(ch: &DynCharacter<'_>, ctx: &'db Database) -> Option<&'db Droid> {
-    ctx.droids.get(ch.id())
-}
+# use std::marker::PhantomData;
+# use derive_more::From;
+# use juniper::{GraphQLObject, GraphQLUnion};
 #
-# fn main() {}
-```
-
-
-
-
-## `ScalarValue` considerations
-
-By default, `#[derive(GraphQLUnion)]` and `#[graphql_union]` macros generate code, which is generic over a [`ScalarValue`][2] type. This may introduce a problem when at least one of [GraphQL union][1] variants is restricted to a concrete [`ScalarValue`][2] type in its implementation. To resolve such problem, a concrete [`ScalarValue`][2] type should be specified:
-
-```rust
-# #![allow(dead_code)]
-# extern crate juniper;
-use juniper::{DefaultScalarValue, GraphQLObject, GraphQLUnion};
-
 #[derive(GraphQLObject)]
-#[graphql(Scalar = DefaultScalarValue)]
 struct Human {
     id: String,
     home_planet: String,
@@ -471,21 +134,35 @@ struct Droid {
     primary_function: String,
 }
 
-#[derive(GraphQLUnion)]
-#[graphql(Scalar = DefaultScalarValue)]  // removing this line will fail compilation
-enum Character {
+#[derive(From, GraphQLUnion)]
+enum Character<S> {
     Human(Human),
     Droid(Droid),
+    #[from(ignore)]
+    #[graphql(ignore)]  
+    //        ^^^^^^ or `skip`, up to your preference
+    _State(PhantomData<S>),
 }
 #
 # fn main() {}
 ```
+> **WARNING**: It's the _library user's responsibility_ to ensure that ignored [enum][22] variant is **never** returned from resolvers, otherwise resolving the [GraphQL] query will **panic in runtime**.
+
+> **TIP**: See more available features in the API docs of the [`#[derive(GraphQLUnion)]`][2] attribute.
 
 
 
 
+[GraphQL]: https://graphql.org
+[Juniper]: https://docs.rs/juniper
+[Rust]: https://www.rust-lang.org
 
-[1]: https://spec.graphql.org/October2021#sec-Unions
-[2]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html
-[5]: https://spec.graphql.org/October2021#sec-Interfaces
-[6]: https://docs.rs/juniper/0.14.2/juniper/trait.Context.html
+[0]: https://spec.graphql.org/October2021#sec-Unions
+[1]: https://graphql.org/learn/schema
+[2]: https://docs.rs/juniper/latest/juniper/derive.GraphQLUnion.html
+[6]: https://doc.rust-lang.org/reference/comments.html#doc-comments
+[7]: https://spec.graphql.org/October2021#sec-Descriptions
+[10]: https://spec.graphql.org/October2021#sec-Objects
+[11]: https://spec.graphql.org/October2021#sec-Enums
+[12]: https://spec.graphql.org/October2021#sec-Interfaces
+[22]: https://doc.rust-lang.org/reference/items/enumerations.html#enumerations
diff --git a/juniper/CHANGELOG.md b/juniper/CHANGELOG.md
index f52db99b8..a87854e06 100644
--- a/juniper/CHANGELOG.md
+++ b/juniper/CHANGELOG.md
@@ -68,6 +68,7 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
         - Made `LookAheadSelection::arguments()` returning iterator over `LookAheadArgument`.
         - Made `LookAheadSelection::children()` returning `LookAheadChildren`.
     - Added `Span` to `Arguments` and `LookAheadArguments`. ([#1206], [#1209])
+- Disabled `bson`, `url`, `uuid` and `schema-language` [Cargo feature]s by default. ([#1230])
 
 ### Added
 
@@ -164,6 +165,7 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
 [#1215]: /../../pull/1215
 [#1227]: /../../pull/1227
 [#1228]: /../../pull/1228
+[#1230]: /../../pull/1230
 [#1237]: /../../pull/1237
 [#1239]: /../../pull/1239
 [#1246]: /../../pull/1246
diff --git a/juniper/Cargo.toml b/juniper/Cargo.toml
index cc709507c..6a510ede0 100644
--- a/juniper/Cargo.toml
+++ b/juniper/Cargo.toml
@@ -13,7 +13,7 @@ authors = [
     "Kai Ren <tyranron@gmail.com>",
 ]
 documentation = "https://docs.rs/juniper"
-homepage = "https://graphql-rust.github.io"
+homepage = "https://graphql-rust.github.io/juniper"
 repository = "https://github.com/graphql-rust/juniper"
 readme = "README.md"
 categories = ["asynchronous", "web-programming", "web-programming::http-server"]
@@ -25,12 +25,6 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
-default = [
-    "bson",
-    "schema-language",
-    "url",
-    "uuid",
-]
 anyhow = ["dep:anyhow"]
 backtrace = ["anyhow?/backtrace"]
 bigdecimal = ["dep:bigdecimal", "dep:num-bigint", "dep:ryu"]
diff --git a/juniper/README.md b/juniper/README.md
index 9f108d3dd..6db502ad0 100644
--- a/juniper/README.md
+++ b/juniper/README.md
@@ -42,20 +42,19 @@ As an exception to other [GraphQL] libraries for other languages, [Juniper] buil
 ## Integrations
 
 
-### Data types
+### Types
 
-[Juniper] has automatic integration with some very common [Rust] crates to make building schemas a breeze. The types from these crates will be usable in your schemas automatically:
-- [`bigdecimal`] (feature gated)
+[Juniper] provides out-of-the-box integration for some very common [Rust] crates to make building schemas a breeze. The types from these crates will be usable in your schemas automatically after enabling the correspondent self-titled [Cargo feature]:
+- [`bigdecimal`]
 - [`bson`]
-- [`chrono`] (feature gated)
-- [`chrono-tz`] (feature gated)
-- [`rust_decimal`] (feature gated)
-- [`time`] (feature gated)
+- [`chrono`], [`chrono-tz`]
+- [`rust_decimal`]
+- [`time`]
 - [`url`]
 - [`uuid`]
 
 
-### Web servers
+### Web server frameworks
 
 - [`actix-web`] ([`juniper_actix`] crate)
 - [`axum`] ([`juniper_axum`] crate)
@@ -66,7 +65,7 @@ As an exception to other [GraphQL] libraries for other languages, [Juniper] buil
 
 
 
-## API Stability
+## API stability
 
 [Juniper] has not reached 1.0 yet, thus some API instability should be expected.
 
@@ -98,13 +97,14 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
 [`url`]: https://docs.rs/url
 [`uuid`]: https://docs.rs/uuid
 [`warp`]: https://docs.rs/warp
+[Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
 [Facebook]: https://facebook.com
 [GraphiQL]: https://github.com/graphql/graphiql
 [GraphQL]: http://graphql.org
 [GraphQL Playground]: https://github.com/graphql/graphql-playground
 [Juniper]: https://docs.rs/juniper
-[Juniper Book]: https://graphql-rust.github.io
+[Juniper Book]: https://graphql-rust.github.io/juniper
 [Juniper Book edge]: https://graphql-rust.github.io/juniper/master
 [Rust]: https://www.rust-lang.org
 
-[1]: https://graphql-rust.github.io/quickstart.html
+[1]: https://graphql-rust.github.io/juniper/quickstart.html
diff --git a/juniper/release.toml b/juniper/release.toml
index 5da76ef0c..776ca1529 100644
--- a/juniper/release.toml
+++ b/juniper/release.toml
@@ -1,34 +1,3 @@
-[[pre-release-replacements]]
-file = "../book/src/advanced/dataloaders.md"
-exactly = 1
-search = "juniper = \"[^\"]+\""
-replace = "juniper = \"{{version}}\""
-[[pre-release-replacements]]
-file = "../book/src/advanced/subscriptions.md"
-exactly = 1
-search = "juniper = \"[^\"]+\""
-replace = "juniper = \"{{version}}\""
-[[pre-release-replacements]]
-file = "../book/src/quickstart.md"
-exactly = 1
-search = "juniper = \"[^\"]+\""
-replace = "juniper = \"{{version}}\""
-[[pre-release-replacements]]
-file = "../book/src/servers/hyper.md"
-exactly = 1
-search = "juniper = \"[^\"]+\""
-replace = "juniper = \"{{version}}\""
-[[pre-release-replacements]]
-file = "../book/src/servers/rocket.md"
-exactly = 1
-search = "juniper = \"[^\"]+\""
-replace = "juniper = \"{{version}}\""
-[[pre-release-replacements]]
-file = "../book/src/servers/warp.md"
-exactly = 1
-search = "juniper = \"[^\"]+\""
-replace = "juniper = \"{{version}}\""
-
 [[pre-release-replacements]]
 file = "../juniper_actix/Cargo.toml"
 exactly = 2
@@ -89,3 +58,79 @@ file = "README.md"
 exactly = 2
 search = "graphql-rust/juniper/blob/[^/]+/"
 replace = "graphql-rust/juniper/blob/{{crate_name}}-v{{version}}/"
+
+[[pre-release-replacements]]
+file = "../book/src/quickstart.md"
+exactly = 1
+search = "juniper = \"[^\"]+\""
+replace = "juniper = \"{{version}}\""
+[[pre-release-replacements]]
+file = "../book/src/quickstart.md"
+exactly = 1
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/advanced/implicit_and_explicit_null.md"
+exactly = 1
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/advanced/lookahead.md"
+exactly = 6
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/schema/index.md"
+exactly = 5
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/schema/introspection.md"
+exactly = 1
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/schema/subscriptions.md"
+exactly = 3
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/enums.md"
+exactly = 1
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/input_objects.md"
+exactly = 1
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/interfaces.md"
+exactly = 2
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/scalars.md"
+exactly = 3
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/unions.md"
+exactly = 1
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/objects/complex_fields.md"
+exactly = 2
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/objects/index.md"
+exactly = 3
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
+[[pre-release-replacements]]
+file = "../book/src/types/objects/error/field.md"
+exactly = 3
+search = "docs.rs/juniper/[^/]+/"
+replace = "docs.rs/juniper/{{version}}/"
diff --git a/juniper/src/executor/look_ahead.rs b/juniper/src/executor/look_ahead.rs
index 57a36308e..bc25c3c1a 100644
--- a/juniper/src/executor/look_ahead.rs
+++ b/juniper/src/executor/look_ahead.rs
@@ -441,6 +441,8 @@ impl<'a, S> LookAheadChildren<'a, S> {
     }
 
     /// Returns the possibly aliased names of the top-level children from the current [selection].
+    ///
+    /// [selection]: https://spec.graphql.org/October2021#sec-Selection-Sets
     pub fn names(&self) -> impl DoubleEndedIterator<Item = &'a str> + '_ {
         self.children.iter().map(|sel| sel.field_name())
     }
diff --git a/juniper/src/schema/model.rs b/juniper/src/schema/model.rs
index 61b119678..75b216a7a 100644
--- a/juniper/src/schema/model.rs
+++ b/juniper/src/schema/model.rs
@@ -184,7 +184,7 @@ where
     ///     }
     /// }
     ///
-    /// type Schema = RootNode<'static, Query, EmptyMutation<()>, EmptySubscription<()>>;
+    /// type Schema = RootNode<'static, Query, EmptyMutation, EmptySubscription>;
     ///
     /// let schema = Schema::new(Query, EmptyMutation::new(), EmptySubscription::new())
     ///     .disable_introspection();
diff --git a/juniper_actix/README.md b/juniper_actix/README.md
index 0df1dad66..078a2d132 100644
--- a/juniper_actix/README.md
+++ b/juniper_actix/README.md
@@ -43,7 +43,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
 [`juniper_actix`]: https://docs.rs/juniper_actix
 [`juniper_warp`]: https://docs.rs/juniper_warp
 [GraphQL]: http://graphql.org
-[Juniper Book]: https://graphql-rust.github.io
+[Juniper Book]: https://graphql-rust.github.io/juniper
 [Rust]: https://www.rust-lang.org
 
 [1]: https://github.com/graphql-rust/juniper/blob/master/juniper_actix/examples/subscription.rs
diff --git a/juniper_axum/README.md b/juniper_axum/README.md
index 7d59c60c4..1934fe86f 100644
--- a/juniper_axum/README.md
+++ b/juniper_axum/README.md
@@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
 [`juniper`]: https://docs.rs/juniper
 [`juniper_axum`]: https://docs.rs/juniper_axum
 [GraphQL]: http://graphql.org
-[Juniper Book]: https://graphql-rust.github.io
+[Juniper Book]: https://graphql-rust.github.io/juniper
 [Rust]: https://www.rust-lang.org
 
 [1]: https://github.com/graphql-rust/juniper/blob/master/juniper_axum/examples/simple.rs
diff --git a/juniper_codegen/src/lib.rs b/juniper_codegen/src/lib.rs
index d69cd714c..ed06faa34 100644
--- a/juniper_codegen/src/lib.rs
+++ b/juniper_codegen/src/lib.rs
@@ -200,13 +200,17 @@ use self::common::diagnostic::{self, ResultExt as _};
 /// struct Point2D {
 ///     x: f64,
 ///     y: f64,
-///     #[graphql(ignore)]
-///     shift: f64, // `Default::default()` impl is used.
-///     #[graphql(skip, default = System::Cartesian)]
-///     //              ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-///     // This attribute is required, as we need to be to construct `Point2D`
-///     // from `{ x: 0.0, y: 0.0 }` GraphQL input.
+///     #[graphql(ignore, default = System::Cartesian)]
+///     //                ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+///     // This attribute is required, as we need to be able to construct
+///     // a `Point2D` value from the `{ x: 0.0, y: 0.0 }` GraphQL input value,
+///     // received from client-side.
 ///     system: System,
+///     // `Default::default()` value is used, if no
+///     // `#[graphql(default = <expression>)]` is specified.
+///     #[graphql(skip)]
+///     //        ^^^^ alternative naming, up to your preference
+///     shift: f64,
 /// }
 /// ```
 ///
@@ -320,6 +324,9 @@ pub fn derive_input_object(input: TokenStream) -> TokenStream {
 ///     Jedi,
 ///     #[graphql(ignore)]
 ///     Legends(T),
+///     #[graphql(skip)]
+///     //        ^^^^ alternative naming, up to your preference
+///     CloneWars(T),
 /// }
 /// ```
 ///
@@ -358,10 +365,10 @@ pub fn derive_enum(input: TokenStream) -> TokenStream {
 ///
 /// # Transparent delegation
 ///
-/// Sometimes, you want to create a custom [GraphQL scalar][0] type by just
+/// Quite often we want to create a custom [GraphQL scalar][0] type by just
 /// wrapping an existing one, inheriting all its behavior. In Rust, this is
-/// often called as ["`Newtype` pattern"][1]. This may be achieved by providing
-/// a `#[graphql(transparent)]` attribute to the definition:
+/// often called as ["newtype pattern"][1]. This is achieved by annotating
+/// the definition with the `#[graphql(transparent)]` attribute:
 /// ```rust
 /// # use juniper::{GraphQLObject, GraphQLScalar};
 /// #
@@ -502,10 +509,10 @@ pub fn derive_enum(input: TokenStream) -> TokenStream {
 ///         .or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
 /// }
 /// ```
-/// > __NOTE:__ Once we provide all 3 custom functions, there is no sense to
-/// >           follow [`Newtype` pattern][1] anymore.
+/// > __NOTE:__ Once we provide all 3 custom functions, there is no sense in
+/// >           following the [newtype pattern][1] anymore.
 ///
-/// # All at once
+/// # Full behavior
 ///
 /// Instead of providing all custom functions separately, it's possible to
 /// provide a module holding the appropriate `to_output()`, `from_input()` and
@@ -693,7 +700,7 @@ pub fn derive_scalar(input: TokenStream) -> TokenStream {
 /// # Foreign types
 ///
 /// Additionally, `#[graphql_scalar]` can be used directly on foreign types via
-/// type alias, without using [`Newtype` pattern][1].
+/// type alias, without using the [newtype pattern][1].
 ///
 /// > __NOTE:__ To satisfy [orphan rules] you should provide local
 /// >           [`ScalarValue`] implementation.
@@ -746,7 +753,7 @@ pub fn derive_scalar(input: TokenStream) -> TokenStream {
 ///     }
 /// }
 /// #
-/// # fn main() { }
+/// # fn main() {}
 /// ```
 ///
 /// [0]: https://spec.graphql.org/October2021#sec-Scalars
@@ -1350,9 +1357,9 @@ pub fn graphql_interface(attr: TokenStream, body: TokenStream) -> TokenStream {
 /// }
 /// ```
 ///
-/// For more info and possibilities see [`#[graphql_interface]`] macro.
+/// For more info and possibilities see [`#[graphql_interface]`][0] macro.
 ///
-/// [`#[graphql_interface]`]: crate::graphql_interface
+/// [0]: crate::graphql_interface
 /// [1]: https://spec.graphql.org/October2021#sec-Interfaces
 #[proc_macro_derive(GraphQLInterface, attributes(graphql))]
 pub fn derive_interface(body: TokenStream) -> TokenStream {
@@ -1461,6 +1468,9 @@ pub fn derive_interface(body: TokenStream) -> TokenStream {
 ///     id: String,
 ///     #[graphql(ignore)]
 ///     home_planet: String,
+///     #[graphql(skip)]
+///     //        ^^^^ alternative naming, up to your preference
+///     password_hash: String,
 /// }
 /// ```
 ///
@@ -1576,7 +1586,7 @@ pub fn derive_object(body: TokenStream) -> TokenStream {
 ///
 ///     // This method is useful only to define GraphQL fields, but is not
 ///     // a field itself, so we ignore it in schema.
-///     #[graphql(ignore)]
+///     #[graphql(ignore)] // or `#[graphql(skip)]`, up to your preference
 ///     fn build_full_name(&self) -> String {
 ///         format!("{} {}", self.first_name, self.last_name)
 ///     }
diff --git a/juniper_hyper/README.md b/juniper_hyper/README.md
index bbe8fcc85..9a30b5c34 100644
--- a/juniper_hyper/README.md
+++ b/juniper_hyper/README.md
@@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
 [`juniper`]: https://docs.rs/juniper
 [`juniper_hyper`]: https://docs.rs/juniper_hyper
 [GraphQL]: http://graphql.org
-[Juniper Book]: https://graphql-rust.github.io
+[Juniper Book]: https://graphql-rust.github.io/juniper
 [Rust]: https://www.rust-lang.org
 
 [1]: https://github.com/graphql-rust/juniper/blob/master/juniper_hyper/examples/hyper_server.rs
diff --git a/juniper_hyper/release.toml b/juniper_hyper/release.toml
index 7a20c9f7d..0c8998261 100644
--- a/juniper_hyper/release.toml
+++ b/juniper_hyper/release.toml
@@ -1,9 +1,3 @@
-[[pre-release-replacements]]
-file = "../book/src/servers/hyper.md"
-exactly = 1
-search = "juniper_hyper = \"[^\"]+\""
-replace = "juniper_hyper = \"{{version}}\""
-
 [[pre-release-replacements]]
 file = "CHANGELOG.md"
 max = 1
diff --git a/juniper_rocket/README.md b/juniper_rocket/README.md
index 0ea4276e9..fef9f1b9c 100644
--- a/juniper_rocket/README.md
+++ b/juniper_rocket/README.md
@@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
 [`juniper_rocket`]: https://docs.rs/juniper_rocket
 [`rocket`]: https://docs.rs/rocket
 [GraphQL]: http://graphql.org
-[Juniper Book]: https://graphql-rust.github.io
+[Juniper Book]: https://graphql-rust.github.io/juniper
 [Rust]: https://www.rust-lang.org
 
 [1]: https://github.com/graphql-rust/juniper/blob/master/juniper_rocket/examples/simple.rs
diff --git a/juniper_rocket/release.toml b/juniper_rocket/release.toml
index 1a54940de..0c8998261 100644
--- a/juniper_rocket/release.toml
+++ b/juniper_rocket/release.toml
@@ -1,9 +1,3 @@
-[[pre-release-replacements]]
-file = "../book/src/servers/rocket.md"
-exactly = 1
-search = "juniper_rocket = \"[^\"]+\""
-replace = "juniper_rocket = \"{{version}}\""
-
 [[pre-release-replacements]]
 file = "CHANGELOG.md"
 max = 1
diff --git a/juniper_subscriptions/release.toml b/juniper_subscriptions/release.toml
index a12a90656..2a6bf859d 100644
--- a/juniper_subscriptions/release.toml
+++ b/juniper_subscriptions/release.toml
@@ -1,9 +1,3 @@
-[[pre-release-replacements]]
-file = "../book/src/advanced/subscriptions.md"
-exactly = 1
-search = "juniper_subscriptions = \"[^\"]+\""
-replace = "juniper_subscriptions = \"{{version}}\""
-
 [[pre-release-replacements]]
 file = "../juniper_graphql_ws/Cargo.toml"
 exactly = 1
@@ -22,3 +16,9 @@ file = "README.md"
 exactly = 3
 search = "graphql-rust/juniper/blob/[^/]+/"
 replace = "graphql-rust/juniper/blob/{{crate_name}}-v{{version}}/"
+
+[[pre-release-replacements]]
+file = "../book/src/schema/subscriptions.md"
+exactly = 2
+search = "docs.rs/juniper_subscriptions/[^/]+/"
+replace = "docs.rs/juniper_subscriptions/{{version}}/"
diff --git a/juniper_warp/README.md b/juniper_warp/README.md
index 0fb0e617b..03adfa65f 100644
--- a/juniper_warp/README.md
+++ b/juniper_warp/README.md
@@ -40,7 +40,7 @@ This project is licensed under [BSD 2-Clause License](https://github.com/graphql
 [`juniper_warp`]: https://docs.rs/juniper_warp
 [`warp`]: https://docs.rs/warp
 [GraphQL]: http://graphql.org
-[Juniper Book]: https://graphql-rust.github.io
+[Juniper Book]: https://graphql-rust.github.io/juniper
 [Rust]: https://www.rust-lang.org
 
 [1]: https://github.com/graphql-rust/juniper/blob/master/juniper_warp/examples/subscription.rs
diff --git a/juniper_warp/release.toml b/juniper_warp/release.toml
index e747c48bc..0c8998261 100644
--- a/juniper_warp/release.toml
+++ b/juniper_warp/release.toml
@@ -1,9 +1,3 @@
-[[pre-release-replacements]]
-file = "../book/src/servers/warp.md"
-exactly = 1
-search = "juniper_warp = \"[^\"]+\""
-replace = "juniper_warp = \"{{version}}\""
-
 [[pre-release-replacements]]
 file = "CHANGELOG.md"
 max = 1


Test patch:
diff --git a/tests/codegen/fail/input-object/derive_incompatible_field_type.stderr b/tests/codegen/fail/input-object/derive_incompatible_field_type.stderr
index 21bf40147..40ef4e904 100644
--- a/tests/codegen/fail/input-object/derive_incompatible_field_type.stderr
+++ b/tests/codegen/fail/input-object/derive_incompatible_field_type.stderr
@@ -10,9 +10,9 @@ error[E0277]: the trait bound `ObjectA: IsInputType<__S>` is not satisfied
              <f64 as IsInputType<__S>>
              <Object as IsInputType<__S>>
              <Box<T> as IsInputType<S>>
-             <uuid::Uuid as IsInputType<__S>>
-             <url::Url as IsInputType<__S>>
-             <bson::datetime::DateTime as IsInputType<__S>>
+             <juniper::schema::model::DirectiveLocation as IsInputType<__S>>
+             <Arc<T> as IsInputType<S>>
+             <Vec<T> as IsInputType<S>>
            and $N others
 
 error[E0277]: the trait bound `ObjectA: FromInputValue<__S>` is not satisfied
@@ -30,9 +30,9 @@ error[E0277]: the trait bound `ObjectA: FromInputValue<__S>` is not satisfied
              <f64 as FromInputValue<__S>>
              <Object as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
+             <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
            and $N others
 note: required by a bound in `Registry::<'r, S>::arg`
   --> $WORKSPACE/juniper/src/executor/mod.rs
@@ -55,9 +55,9 @@ error[E0277]: the trait bound `ObjectA: FromInputValue<__S>` is not satisfied
             <f64 as FromInputValue<__S>>
             <Object as FromInputValue<__S>>
             <Box<T> as FromInputValue<S>>
-            <uuid::Uuid as FromInputValue<__S>>
-            <url::Url as FromInputValue<__S>>
-            <bson::datetime::DateTime as FromInputValue<__S>>
+            <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+            <Arc<T> as FromInputValue<S>>
+            <Vec<T> as FromInputValue<S>>
           and $N others
   = note: this error originates in the derive macro `GraphQLInputObject` (in Nightly builds, run with -Z macro-backtrace for more info)
 
@@ -73,8 +73,8 @@ error[E0277]: the trait bound `ObjectA: ToInputValue<_>` is not satisfied
             <f64 as ToInputValue<__S>>
             <Object as ToInputValue<__S>>
             <Box<T> as ToInputValue<S>>
-            <uuid::Uuid as ToInputValue<__S>>
-            <url::Url as ToInputValue<__S>>
-            <bson::datetime::DateTime as ToInputValue<__S>>
+            <juniper::schema::model::DirectiveLocation as ToInputValue<__S>>
+            <Arc<T> as ToInputValue<S>>
+            <Vec<T> as ToInputValue<S>>
           and $N others
   = note: this error originates in the derive macro `GraphQLInputObject` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/tests/codegen/fail/interface/struct/attr_field_non_output_return_type.stderr b/tests/codegen/fail/interface/struct/attr_field_non_output_return_type.stderr
index cd32c75c9..df6701eb5 100644
--- a/tests/codegen/fail/interface/struct/attr_field_non_output_return_type.stderr
+++ b/tests/codegen/fail/interface/struct/attr_field_non_output_return_type.stderr
@@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
             <f64 as IsOutputType<__S>>
             <CharacterValueEnum as IsOutputType<__S>>
             <Box<T> as IsOutputType<S>>
-            <uuid::Uuid as IsOutputType<__S>>
-            <url::Url as IsOutputType<__S>>
-            <bson::datetime::DateTime as IsOutputType<__S>>
+            <juniper::meta::Field<'a, S> as IsOutputType<S>>
+            <Argument<'a, S> as IsOutputType<S>>
+            <EnumValue as IsOutputType<__S>>
           and $N others
diff --git a/tests/codegen/fail/interface/struct/derive_field_non_output_return_type.stderr b/tests/codegen/fail/interface/struct/derive_field_non_output_return_type.stderr
index d8b5b7333..9251365be 100644
--- a/tests/codegen/fail/interface/struct/derive_field_non_output_return_type.stderr
+++ b/tests/codegen/fail/interface/struct/derive_field_non_output_return_type.stderr
@@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
             <f64 as IsOutputType<__S>>
             <CharacterValueEnum as IsOutputType<__S>>
             <Box<T> as IsOutputType<S>>
-            <uuid::Uuid as IsOutputType<__S>>
-            <url::Url as IsOutputType<__S>>
-            <bson::datetime::DateTime as IsOutputType<__S>>
+            <juniper::meta::Field<'a, S> as IsOutputType<S>>
+            <Argument<'a, S> as IsOutputType<S>>
+            <EnumValue as IsOutputType<__S>>
           and $N others
diff --git a/tests/codegen/fail/interface/trait/argument_non_input_type.stderr b/tests/codegen/fail/interface/trait/argument_non_input_type.stderr
index a6af9595d..a72e3015a 100644
--- a/tests/codegen/fail/interface/trait/argument_non_input_type.stderr
+++ b/tests/codegen/fail/interface/trait/argument_non_input_type.stderr
@@ -9,10 +9,10 @@ error[E0277]: the trait bound `ObjA: IsInputType<__S>` is not satisfied
              <i32 as IsInputType<__S>>
              <f64 as IsInputType<__S>>
              <Box<T> as IsInputType<S>>
-             <uuid::Uuid as IsInputType<__S>>
-             <url::Url as IsInputType<__S>>
-             <bson::datetime::DateTime as IsInputType<__S>>
              <juniper::schema::model::DirectiveLocation as IsInputType<__S>>
+             <Arc<T> as IsInputType<S>>
+             <Vec<T> as IsInputType<S>>
+             <TypeKind as IsInputType<__S>>
            and $N others
 
 error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
@@ -29,10 +29,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
              <i32 as FromInputValue<__S>>
              <f64 as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
              <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
+             <TypeKind as FromInputValue<__S>>
            and $N others
 note: required by a bound in `Registry::<'r, S>::arg`
   --> $WORKSPACE/juniper/src/executor/mod.rs
diff --git a/tests/codegen/fail/interface/trait/argument_wrong_default_array.stderr b/tests/codegen/fail/interface/trait/argument_wrong_default_array.stderr
index b1fd5c1b8..7fac47df5 100644
--- a/tests/codegen/fail/interface/trait/argument_wrong_default_array.stderr
+++ b/tests/codegen/fail/interface/trait/argument_wrong_default_array.stderr
@@ -6,13 +6,13 @@ error[E0277]: the trait bound `[bool; 2]: From<[bool; 3]>` is not satisfied
   |
   = help: the following other types implement trait `From<T>`:
             <[bool; N] as From<Mask<T, N>>>
-            <[u32; 4] as From<ppv_lite86::x86_64::vec128_storage>>
-            <[u32; 8] as From<ppv_lite86::x86_64::vec256_storage>>
-            <[u32; 16] as From<ppv_lite86::x86_64::vec512_storage>>
-            <[u64; 2] as From<ppv_lite86::x86_64::vec128_storage>>
-            <[u64; 4] as From<ppv_lite86::x86_64::vec256_storage>>
-            <[u64; 8] as From<ppv_lite86::x86_64::vec512_storage>>
-            <[u128; 1] as From<ppv_lite86::x86_64::vec128_storage>>
+            <[T; N] as From<Simd<T, N>>>
+            <[T; 1] as From<(T,)>>
+            <[T; 2] as From<(T, T)>>
+            <[T; 3] as From<(T, T, T)>>
+            <[T; 4] as From<(T, T, T, T)>>
+            <[T; 5] as From<(T, T, T, T, T)>>
+            <[T; 6] as From<(T, T, T, T, T, T)>>
           and $N others
   = note: required for `[bool; 3]` to implement `Into<[bool; 2]>`
   = note: this error originates in the attribute macro `graphql_interface` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/tests/codegen/fail/interface/trait/field_non_output_return_type.stderr b/tests/codegen/fail/interface/trait/field_non_output_return_type.stderr
index ca0c5593d..f15bd4353 100644
--- a/tests/codegen/fail/interface/trait/field_non_output_return_type.stderr
+++ b/tests/codegen/fail/interface/trait/field_non_output_return_type.stderr
@@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
             <f64 as IsOutputType<__S>>
             <CharacterValueEnum as IsOutputType<__S>>
             <Box<T> as IsOutputType<S>>
-            <uuid::Uuid as IsOutputType<__S>>
-            <url::Url as IsOutputType<__S>>
-            <bson::datetime::DateTime as IsOutputType<__S>>
+            <juniper::meta::Field<'a, S> as IsOutputType<S>>
+            <Argument<'a, S> as IsOutputType<S>>
+            <EnumValue as IsOutputType<__S>>
           and $N others
diff --git a/tests/codegen/fail/object/argument_non_input_type.stderr b/tests/codegen/fail/object/argument_non_input_type.stderr
index 323928ff3..cb8c0e1d8 100644
--- a/tests/codegen/fail/object/argument_non_input_type.stderr
+++ b/tests/codegen/fail/object/argument_non_input_type.stderr
@@ -9,10 +9,10 @@ error[E0277]: the trait bound `ObjA: IsInputType<__S>` is not satisfied
              <i32 as IsInputType<__S>>
              <f64 as IsInputType<__S>>
              <Box<T> as IsInputType<S>>
-             <uuid::Uuid as IsInputType<__S>>
-             <url::Url as IsInputType<__S>>
-             <bson::datetime::DateTime as IsInputType<__S>>
              <juniper::schema::model::DirectiveLocation as IsInputType<__S>>
+             <Arc<T> as IsInputType<S>>
+             <Vec<T> as IsInputType<S>>
+             <TypeKind as IsInputType<__S>>
            and $N others
 
 error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
@@ -29,10 +29,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
              <i32 as FromInputValue<__S>>
              <f64 as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
              <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
+             <TypeKind as FromInputValue<__S>>
            and $N others
 note: required by a bound in `Registry::<'r, S>::arg`
   --> $WORKSPACE/juniper/src/executor/mod.rs
@@ -54,10 +54,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
              <i32 as FromInputValue<__S>>
              <f64 as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
              <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
+             <TypeKind as FromInputValue<__S>>
            and $N others
    = note: this error originates in the attribute macro `graphql_object` (in Nightly builds, run with -Z macro-backtrace for more info)
 
@@ -72,8 +72,8 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
              <i32 as FromInputValue<__S>>
              <f64 as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
              <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
+             <TypeKind as FromInputValue<__S>>
            and $N others
diff --git a/tests/codegen/fail/object/argument_wrong_default_array.stderr b/tests/codegen/fail/object/argument_wrong_default_array.stderr
index 1f5f2096c..4c02f956c 100644
--- a/tests/codegen/fail/object/argument_wrong_default_array.stderr
+++ b/tests/codegen/fail/object/argument_wrong_default_array.stderr
@@ -6,13 +6,13 @@ error[E0277]: the trait bound `[bool; 2]: From<[bool; 3]>` is not satisfied
   |
   = help: the following other types implement trait `From<T>`:
             <[bool; N] as From<Mask<T, N>>>
-            <[u32; 4] as From<ppv_lite86::x86_64::vec128_storage>>
-            <[u32; 8] as From<ppv_lite86::x86_64::vec256_storage>>
-            <[u32; 16] as From<ppv_lite86::x86_64::vec512_storage>>
-            <[u64; 2] as From<ppv_lite86::x86_64::vec128_storage>>
-            <[u64; 4] as From<ppv_lite86::x86_64::vec256_storage>>
-            <[u64; 8] as From<ppv_lite86::x86_64::vec512_storage>>
-            <[u128; 1] as From<ppv_lite86::x86_64::vec128_storage>>
+            <[T; N] as From<Simd<T, N>>>
+            <[T; 1] as From<(T,)>>
+            <[T; 2] as From<(T, T)>>
+            <[T; 3] as From<(T, T, T)>>
+            <[T; 4] as From<(T, T, T, T)>>
+            <[T; 5] as From<(T, T, T, T, T)>>
+            <[T; 6] as From<(T, T, T, T, T, T)>>
           and $N others
   = note: required for `[bool; 3]` to implement `Into<[bool; 2]>`
   = note: this error originates in the attribute macro `graphql_object` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/tests/codegen/fail/object/attr_field_non_output_return_type.stderr b/tests/codegen/fail/object/attr_field_non_output_return_type.stderr
index 1c775851b..df4b4c650 100644
--- a/tests/codegen/fail/object/attr_field_non_output_return_type.stderr
+++ b/tests/codegen/fail/object/attr_field_non_output_return_type.stderr
@@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
              <f64 as IsOutputType<__S>>
              <ObjA as IsOutputType<__S>>
              <Box<T> as IsOutputType<S>>
-             <uuid::Uuid as IsOutputType<__S>>
-             <url::Url as IsOutputType<__S>>
-             <bson::datetime::DateTime as IsOutputType<__S>>
+             <juniper::meta::Field<'a, S> as IsOutputType<S>>
+             <Argument<'a, S> as IsOutputType<S>>
+             <EnumValue as IsOutputType<__S>>
            and $N others
diff --git a/tests/codegen/fail/object/derive_field_non_output_return_type.stderr b/tests/codegen/fail/object/derive_field_non_output_return_type.stderr
index ad431c534..aa3628e71 100644
--- a/tests/codegen/fail/object/derive_field_non_output_return_type.stderr
+++ b/tests/codegen/fail/object/derive_field_non_output_return_type.stderr
@@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
             <f64 as IsOutputType<__S>>
             <ObjA as IsOutputType<__S>>
             <Box<T> as IsOutputType<S>>
-            <uuid::Uuid as IsOutputType<__S>>
-            <url::Url as IsOutputType<__S>>
-            <bson::datetime::DateTime as IsOutputType<__S>>
+            <juniper::meta::Field<'a, S> as IsOutputType<S>>
+            <Argument<'a, S> as IsOutputType<S>>
+            <EnumValue as IsOutputType<__S>>
           and $N others
diff --git a/tests/codegen/fail/subscription/argument_non_input_type.stderr b/tests/codegen/fail/subscription/argument_non_input_type.stderr
index 3022c6b4f..be23f0add 100644
--- a/tests/codegen/fail/subscription/argument_non_input_type.stderr
+++ b/tests/codegen/fail/subscription/argument_non_input_type.stderr
@@ -17,10 +17,10 @@ error[E0277]: the trait bound `ObjA: IsInputType<__S>` is not satisfied
              <i32 as IsInputType<__S>>
              <f64 as IsInputType<__S>>
              <Box<T> as IsInputType<S>>
-             <uuid::Uuid as IsInputType<__S>>
-             <url::Url as IsInputType<__S>>
-             <bson::datetime::DateTime as IsInputType<__S>>
              <juniper::schema::model::DirectiveLocation as IsInputType<__S>>
+             <Arc<T> as IsInputType<S>>
+             <Vec<T> as IsInputType<S>>
+             <TypeKind as IsInputType<__S>>
            and $N others
 
 error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
@@ -37,10 +37,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
              <i32 as FromInputValue<__S>>
              <f64 as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
              <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
+             <TypeKind as FromInputValue<__S>>
            and $N others
 note: required by a bound in `Registry::<'r, S>::arg`
   --> $WORKSPACE/juniper/src/executor/mod.rs
@@ -62,10 +62,10 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
              <i32 as FromInputValue<__S>>
              <f64 as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
              <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
+             <TypeKind as FromInputValue<__S>>
            and $N others
    = note: this error originates in the attribute macro `graphql_subscription` (in Nightly builds, run with -Z macro-backtrace for more info)
 
@@ -80,8 +80,8 @@ error[E0277]: the trait bound `ObjA: FromInputValue<__S>` is not satisfied
              <i32 as FromInputValue<__S>>
              <f64 as FromInputValue<__S>>
              <Box<T> as FromInputValue<S>>
-             <uuid::Uuid as FromInputValue<__S>>
-             <url::Url as FromInputValue<__S>>
-             <bson::datetime::DateTime as FromInputValue<__S>>
              <juniper::schema::model::DirectiveLocation as FromInputValue<__S>>
+             <Arc<T> as FromInputValue<S>>
+             <Vec<T> as FromInputValue<S>>
+             <TypeKind as FromInputValue<__S>>
            and $N others
diff --git a/tests/codegen/fail/subscription/argument_wrong_default_array.stderr b/tests/codegen/fail/subscription/argument_wrong_default_array.stderr
index fd4e13e77..c6f1b5eea 100644
--- a/tests/codegen/fail/subscription/argument_wrong_default_array.stderr
+++ b/tests/codegen/fail/subscription/argument_wrong_default_array.stderr
@@ -6,13 +6,13 @@ error[E0277]: the trait bound `[bool; 2]: From<[bool; 3]>` is not satisfied
    |
    = help: the following other types implement trait `From<T>`:
              <[bool; N] as From<Mask<T, N>>>
-             <[u32; 4] as From<ppv_lite86::x86_64::vec128_storage>>
-             <[u32; 8] as From<ppv_lite86::x86_64::vec256_storage>>
-             <[u32; 16] as From<ppv_lite86::x86_64::vec512_storage>>
-             <[u64; 2] as From<ppv_lite86::x86_64::vec128_storage>>
-             <[u64; 4] as From<ppv_lite86::x86_64::vec256_storage>>
-             <[u64; 8] as From<ppv_lite86::x86_64::vec512_storage>>
-             <[u128; 1] as From<ppv_lite86::x86_64::vec128_storage>>
+             <[T; N] as From<Simd<T, N>>>
+             <[T; 1] as From<(T,)>>
+             <[T; 2] as From<(T, T)>>
+             <[T; 3] as From<(T, T, T)>>
+             <[T; 4] as From<(T, T, T, T)>>
+             <[T; 5] as From<(T, T, T, T, T)>>
+             <[T; 6] as From<(T, T, T, T, T, T)>>
            and $N others
    = note: required for `[bool; 3]` to implement `Into<[bool; 2]>`
    = note: this error originates in the attribute macro `graphql_subscription` (in Nightly builds, run with -Z macro-backtrace for more info)
diff --git a/tests/codegen/fail/subscription/field_non_output_return_type.stderr b/tests/codegen/fail/subscription/field_non_output_return_type.stderr
index 5a47e2c7f..984db7003 100644
--- a/tests/codegen/fail/subscription/field_non_output_return_type.stderr
+++ b/tests/codegen/fail/subscription/field_non_output_return_type.stderr
@@ -10,7 +10,7 @@ error[E0277]: the trait bound `ObjB: IsOutputType<__S>` is not satisfied
              <f64 as IsOutputType<__S>>
              <ObjA as IsOutputType<__S>>
              <Box<T> as IsOutputType<S>>
-             <uuid::Uuid as IsOutputType<__S>>
-             <url::Url as IsOutputType<__S>>
-             <bson::datetime::DateTime as IsOutputType<__S>>
+             <juniper::meta::Field<'a, S> as IsOutputType<S>>
+             <Argument<'a, S> as IsOutputType<S>>
+             <EnumValue as IsOutputType<__S>>
            and $N others
diff --git a/tests/integration/Cargo.toml b/tests/integration/Cargo.toml
index d6cdb8bc1..e6d1ade65 100644
--- a/tests/integration/Cargo.toml
+++ b/tests/integration/Cargo.toml
@@ -11,7 +11,7 @@ derive_more = "0.99"
 fnv = "1.0"
 futures = "0.3"
 itertools = "0.12"
-juniper = { path = "../../juniper" }
+juniper = { path = "../../juniper", features = ["chrono"] }
 juniper_subscriptions = { path = "../../juniper_subscriptions" }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"