Input Objects
Fields can define arguments that the client passes up with the query, to configure their behavior. These inputs can be Strings or Enums, but they sometimes need to be more complex than this.
TheObjecttype defined above is inappropriate for re‐use here, becauseObjects can contain fields that express circular references or references to interfaces and unions, neither of which is appropriate for use as an input argument. For this reason, input objects have a separate type in the system.
AnInput Objectdefines a set of input fields; the input fields are either scalars, enums, or other input objects. This allows arguments to accept arbitrarily complex structs.
Result Coercion
An input object is never a valid result.
Input Coercion
The value for an input object should be an input object literal or an unordered map, otherwise an error should be thrown. This unordered map should not contain any entries with names not defined by a field of this input object type, otherwise an error should be thrown.
If any non‐nullable fields defined by the input object do not have corresponding entries in the original value, were provided a variable for which a value was not provided, or for which the valuenullwas provided, an error should be thrown.
The result of coercion is an environment‐specific unordered map defining slots for each field both defined by the input object type and provided by the original value.
For each field of the input object type, if the original value has an entry with the same name, and the value at that entry is a literal value or a variable which was provided a runtime value, an entry is added to the result with the name of the field.
The value of that entry in the result is the outcome of input coercing the original entry value according to the input coercion rules of the type declared by the input field.
Following are examples of Input Object coercion for the type:
input ExampleInputObject {
a: String
b: Int!
}
| Original Value | Variables | Coerced Value |
|---|---|---|
{ a: "abc", b: 123 } |
null | { a: "abc", b: 123 } |
{ a: 123, b: "123" } |
null | { a: "123", b: 123 } |
{ a: "abc" } |
null | Error: Missing required fieldb |
{ a: "abc", b: null } |
null | Error:bmust be non‐null. |
{ a: null, b: 1 } |
null | { a: null, b: 1 } |
{ b: $var } |
{ var: 123 } |
{ b: 123 } |
{ b: $var } |
{} |
Error: Missing required fieldb. |
{ b: $var } |
{ var: null } |
Error:bmust be non‐null. |
{ a: $var, b: 1 } |
{ var: null } |
{ a: null, b: 1 } |
{ a: $var, b: 1 } |
{} |
{ b: 1 } |
there is a semantic difference between the input value explicitly declaring an input field’s value as the value
null
vs having not declared the input field at all.