Deprecation of input object fields and arguments (#1348, #864, #1347, graphql/graphql-spec#525, graphql/graphql-spec#805)

- allow `#[graphql(deprecated)]` and `#[deprecated]` attributes on struct fields in `#[derive(GraphQLInputObject)]` macro
- allow `#[graphql(deprecated)]` attribute on method arguments in `#[graphql_object]` and `#[graphql_interface]` macros
- allow `@deprecated` directive on arguments and input object fields
- add `__InputValue.isDeprecated` and `__InputValue.deprecationReason` fields
- add `includeDeprecated` argument to `__Type.inputFields`, `__Field.args` and `__Directive.args` fields
- make `includeDeprecated` argument of `__Type.fields`, `__Type.enumValues`, `__Type.inputFields`, `__Field.args` and `__Directive.args` fields non-`Null` (graphql/graphql-spec#1142)
- add `schema::meta::Argument::deprecation_status` field
- make `@deprecated(reason:)` argument non-`Null` (graphql/graphql-spec#1040)

Additionally:
- add `__Type.isOneOf` field (graphql/graphql-spec#825)
- add `SCHEMA`, `OBJECT`, `ARGUMENT_DEFINITION`, `INTERFACE`, `UNION`, `ENUM`, `INPUT_OBJECT` and `INPUT_FIELD_DEFINITION` values to `__DirectiveLocation` enum
- update canonical introspection query to 16.11.0 version of GraphQL.js
- fix incorrect `__Type.specifiedByUrl` field name to `__Type.specifiedByURL`
- fix missing `@specifiedBy(url:)` directive in SDL generated by `RootNode::as_sdl()` and `RootNode::as_document()` methods

Author: tyranron

book/src/types/enums.md

@@ -75,7 +75,7 @@ enum Episode {
 
 ### 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:
+Just like when [defining GraphQL objects](objects/index.md#documentation), the [GraphQL enum][0] type and its values could be [documented][4] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
 ```rust
 # extern crate juniper;
 # use juniper::GraphQLEnum;
@@ -105,7 +105,7 @@ enum StarWarsEpisode {
 #
 # fn main() {}
 ```
-> **NOTE**: Only [GraphQL object][6]/[interface][7] fields and [GraphQL enum][0] values can be [deprecated][5].
+> **NOTE**: Only [GraphQL object][6]/[interface][7]/[input object][8] fields, [arguments][5] and [GraphQL enum][0] values can be [deprecated][9].
 
 
 ### Ignoring
@@ -145,7 +145,9 @@ enum Episode<T> {
 [2]: https://docs.rs/juniper/0.17.0/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
+[5]: https://spec.graphql.org/October2021#sec-Language.Arguments
 [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
+[8]: https://spec.graphql.org/October2021#sec-Input-Objects
+[9]: https://spec.graphql.org/October2021#sec--deprecated
+[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute

book/src/types/input_objects.md

@@ -84,9 +84,9 @@ struct Person {
 > **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
 
 
-### Documentation
+### Documentation and deprecation
 
-Similarly, [GraphQL descriptions][7] may be provided by either using [Rust doc comments][6] or with the `#[graphql(description = "...")]` attribute:
+Similarly, [GraphQL input fields][1] may also be [documented][7] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
 ```rust
 # extern crate juniper;
 # use juniper::GraphQLInputObject;
@@ -102,12 +102,20 @@ struct Person {
 
     /// This doc comment is visible in both Rust API docs and GraphQL schema 
     /// descriptions.
+    // Only `Null`able input fields or non-`Null` input fields with default values
+    // can be deprecated.
+    #[graphql(default, deprecated = "Just because.")]
     age: i32,
+
+    // If no explicit deprecation reason is provided,
+    // then the default "No longer supported" one is used.
+    #[deprecated]
+    another: Option<f64>, // has no description in GraphQL schema
 }
 #
 # fn main() {}
 ```
-> **NOTE**: As of [October 2021 GraphQL specification][spec], [GraphQL input object][0]'s fields **cannot be** [deprecated][9].
+> **NOTE**: Only [GraphQL input object][0]/[object][8]/[interface][11] fields, [arguments][5] and [GraphQL enum][10] values can be [deprecated][9].
 
 
 ### Ignoring
@@ -150,14 +158,17 @@ struct Point2D {
 [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
+[1]: https://spec.graphql.org/October2021#InputFieldsDefinition
 [2]: https://docs.rs/juniper/0.17.0/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
+[8]: https://spec.graphql.org/October2021#sec-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-Scalars
+[13]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute

book/src/types/interfaces.md

@@ -317,7 +317,7 @@ trait Person {
 
 ### 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:
+Similarly, [GraphQL fields][4] (and their [arguments][5]) 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 juniper::graphql_interface;
@@ -340,16 +340,24 @@ trait Person {
     /// This doc comment is visible in both Rust API docs and GraphQL schema 
     /// descriptions.
     #[graphql(deprecated = "Just because.")]
-    fn deprecated_graphql() -> bool;
+    fn deprecated_graphql(
+        // Only `Null`able arguments or non-`Null` arguments with default values
+        // can be deprecated.
+        #[graphql(default, deprecated = "No need.")] arg: bool,
+    ) -> bool;
 
     // Standard Rust's `#[deprecated]` attribute works too!
     #[deprecated(note = "Reason is optional, btw!")]
-    fn deprecated_standard() -> bool; // has no description in GraphQL schema
+    fn deprecated_standard( // has no description in GraphQL schema
+        // If no explicit deprecation reason is provided,
+        // then the default "No longer supported" one is used.
+        #[graphql(deprecated)] arg: Option<bool>,
+    ) -> bool;
 }
 #
 # fn main() {}
 ```
-> **NOTE**: Only [GraphQL interface][0]/[object][10] fields and [GraphQL enum][11] values can be [deprecated][9].
+> **NOTE**: Only [GraphQL interface][0]/[object][10]/[input object][8] fields, [arguments][5] and [GraphQL enum][11] values can be [deprecated][9].
 
 
 ### Ignoring
@@ -403,6 +411,7 @@ trait Person {
 [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
+[8]: https://spec.graphql.org/October2021#sec-Input-Objects
 [9]: https://spec.graphql.org/October2021#sec--deprecated
 [10]: https://spec.graphql.org/October2021#sec-Objects
 [11]: https://spec.graphql.org/October2021#sec-Enums

book/src/types/objects/complex_fields.md

@@ -116,7 +116,7 @@ impl Person {
 
 ### Documentation and deprecation
 
-Similarly, [GraphQL fields][4] may also be [documented][7] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
+Similarly, [GraphQL fields][4] (and their [arguments][5]) 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;
@@ -145,20 +145,28 @@ impl Person {
     /// This doc comment is visible in both Rust API docs and GraphQL schema 
     /// descriptions.
     #[graphql(deprecated = "Just because.")]
-    fn deprecated_graphql() -> bool {
+    fn deprecated_graphql(
+        // Only `Null`able arguments or non-`Null` arguments with default values
+        // can be deprecated.
+        #[graphql(default, deprecated = "No need.")] arg: bool,
+    ) -> 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
+    fn deprecated_standard( // has no description in GraphQL schema
+        // If no explicit deprecation reason is provided,
+        // then the default "No longer supported" one is used.
+        #[graphql(deprecated)] arg: Option<bool>,
+    ) -> bool {
         false
     }
 }
 #
 # fn main() {}
 ```
-> **NOTE**: Only [GraphQL object][0]/[interface][11] fields and [GraphQL enum][10] values can be [deprecated][9].
+> **NOTE**: Only [GraphQL object][0]/[interface][11]/[input object][8] fields, [arguments][5] and [GraphQL enum][10] values can be [deprecated][9].
 
 
 ### Ignoring
@@ -223,6 +231,7 @@ impl Person {
 [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
+[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

book/src/types/objects/error/field.md

@@ -37,11 +37,11 @@ impl Example {
 # 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].
+[`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][19] (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.
+> **NOTE**: [`FieldError`][22]s are [GraphQL field errors][1] and are [not visible][15] in a [GraphQL schema][8] in any way.
 
 
 
@@ -172,12 +172,12 @@ And the specified structured error information will be included into the [error'
 [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
+[15]: https://spec.graphql.org/October2021#sec-Introspection
+[19]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
 [21]: https://docs.rs/juniper/0.17.0/juniper/executor/type.FieldResult.html
 [22]: https://docs.rs/juniper/0.17.0/juniper/executor/struct.FieldError.html
 [23]: https://docs.rs/juniper/0.17.0/juniper/executor/trait.IntoFieldError.html

book/src/types/objects/index.md

@@ -34,7 +34,7 @@ This creates a [GraphQL object][0] type called `Person`, with two fields: `name`
 
 ### 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]:
+We should take advantage of the fact that [GraphQL] is [self-documenting][15] 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;
@@ -145,7 +145,7 @@ struct Person {
 #
 # fn main() {}
 ```
-> **NOTE**: Only [GraphQL object][0]/[interface][11] fields and [GraphQL enum][10] values can be [deprecated][9].
+> **NOTE**: Only [GraphQL object][0]/[interface][11]/[input object][8] fields, [arguments][5] and [GraphQL enum][10] values can be [deprecated][9].
 
 
 ### Ignoring
@@ -216,7 +216,7 @@ Because `Person` is a valid [GraphQL] type, we can have a `Vec<Person>` in a [st
 [2]: https://docs.rs/juniper/0.17.0/juniper/derive.GraphQLObject.html
 [3]: https://docs.rs/juniper/0.17.0/juniper/attr.graphql_object.html
 [4]: https://spec.graphql.org/October2021#sec-Non-Null
-[5]: https://spec.graphql.org/October2021#sec-Introspection
+[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
 [8]: https://spec.graphql.org/October2021#sec-Input-Objects
@@ -226,3 +226,4 @@ Because `Person` is a valid [GraphQL] type, we can have a `Vec<Person>` in a [st
 [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
+[15]: https://spec.graphql.org/October2021#sec-Introspection

juniper/CHANGELOG.md

@@ -6,6 +6,51 @@ All user visible changes to `juniper` crate will be documented in this file. Thi
 
 
 
+## main
+
+[Diff](/../../compare/juniper-v0.17.0...main) | [Milestone](/../../milestone/9)
+
+### BC Breaks
+
+- [September 2025] GraphQL spec: ([#1347])
+    - Made `includeDeprecated` argument of `__Type.fields`, `__Type.enumValues`, `__Type.inputFields`, `__Field.args` and `__Directive.args` fields non-`Null`. ([#1348], [graphql/graphql-spec#1142])
+    - Made `@deprecated(reason:)` argument non-`Null`. ([#1348], [graphql/graphql-spec#1040])
+
+### Added
+
+- [September 2025] GraphQL spec: ([#1347])
+    - `__Type.isOneOf` field. ([#1348], [graphql/graphql-spec#825])
+    - `SCHEMA`, `OBJECT`, `ARGUMENT_DEFINITION`, `INTERFACE`, `UNION`, `ENUM`, `INPUT_OBJECT` and `INPUT_FIELD_DEFINITION` values to `__DirectiveLocation` enum. ([#1348])
+    - Arguments and input object fields deprecation: ([#1348], [#864], [graphql/graphql-spec#525], [graphql/graphql-spec#805]) 
+        - Placing `#[graphql(deprecated)]` and `#[deprecated]` attributes on struct fields in `#[derive(GraphQLInputObject)]` macro.
+        - Placing `#[graphql(deprecated)]` attribute on method arguments in `#[graphql_object]` and `#[graphql_interface]` macros.
+        - Placing `@deprecated` directive on arguments and input object fields.
+        - `includeDeprecated` argument to `__Type.inputFields`, `__Field.args` and `__Directive.args` fields.
+        - `__InputValue.isDeprecated` and `__InputValue.deprecationReason` fields.
+        - `schema::meta::Argument::deprecation_status` field.
+
+### Changed
+
+- [September 2025] GraphQL spec: ([#1347])
+    - Canonical introspection query to [16.11.0 version of GraphQL.js](https://github.com/graphql/graphql-js/blob/v16.11.0/src/utilities/getIntrospectionQuery.ts#L75). ([#1348])
+
+### Fixed
+
+- Incorrect `__Type.specifiedByUrl` field to `__Type.specifiedByURL`. ([#1348])
+- Missing `@specifiedBy(url:)` directive in [SDL] generated by `RootNode::as_sdl()` and `RootNode::as_document()` methods. ([#1348])
+
+[#864]: /../../issues/864
+[#1347]: /../../issues/1347
+[#1348]: /../../pull/1348
+[graphql/graphql-spec#525]: https://github.com/graphql/graphql-spec/pull/525
+[graphql/graphql-spec#805]: https://github.com/graphql/graphql-spec/pull/805
+[graphql/graphql-spec#825]: https://github.com/graphql/graphql-spec/pull/825
+[graphql/graphql-spec#1040]: https://github.com/graphql/graphql-spec/pull/1040
+[graphql/graphql-spec#1142]: https://github.com/graphql/graphql-spec/pull/1142
+
+
+
+
 ## [0.17.0] · 2025-09-08
 [0.17.0]: /../../tree/juniper-v0.17.0/juniper
 
@@ -398,3 +443,5 @@ See [old CHANGELOG](/../../blob/juniper-v0.15.12/juniper/CHANGELOG.md).
 [object safety]: https://doc.rust-lang.org/reference/items/traits.html#object-safety
 [orphan rules]: https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
 [Semantic Versioning 2.0.0]: https://semver.org
+[September 2025]: https://spec.graphql.org/September2025
+[SDL]: https://graphql.org/learn/schema#type-language