Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify execution section. #221

Merged
merged 5 commits into from
Oct 24, 2016
Merged

Clarify execution section. #221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d193f58
Clarify execution section.
leebyron Oct 21, 2016
237a9cf
Follow up improvements thanks to @jjergus feedback
leebyron Oct 22, 2016
7352f04
Another pass at further improvements to describing these operations. …
leebyron Oct 22, 2016
6147aef
Note about the purpose of initial value
leebyron Oct 22, 2016
a82434f
Add default value rules, further error throwing spots
leebyron Oct 24, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 42 additions & 7 deletions spec/Section 3 -- Type System.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -775,15 +775,50 @@ An input object is never a valid result.

**Input Coercion**

The input to an input object should be an unordered map, otherwise an error
should be thrown. The result of the coercion is an unordered map, with an
entry for each input field, whose key is the name of the input field.
The value of an entry in the coerced map is the result of input coercing the
value of the entry in the input with the same key; if the input does not have a
corresponding entry, the value is the result of coercing null. The input
coercion above should be performed according to the input coercion rules of the
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 value {null} was provided, an error should
be thrown.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the introduction of a null literal, do we need a separate concept of "non-nullable" and "required"? For example, should it be possible to declare an input object field which must be provided, but its value may be null?

{ required_field: 42 } # valid
{ required_field: null } # valid
{ } # invalid
{ required_field: $var } # valid if $var is required but $var may be nullable...I guess?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll make sure to specifically address this point in the null literal proposal.

I think it's actually not worth separating these notions. I think there probably isn't a ton of value beyond fairly pedantic specificity in the cases of required but nullable and optional but non-nullable.


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.
Copy link
Contributor

@jjergus jjergus Oct 21, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I understand it correctly

{ optional_field: $var }

coerces to

{ optional_field: 42 } # if $var == 42
{ optional_field: null } # if $var is explicitly null
{ } # if $var was not provided

I guess that makes sense but we should probably have some examples here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although the case where a field that was explicitly included in the input object literal can "disappear" if its value is an optional variable feels non-intuitive to me, I'm not sure if that's the right call.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's the current behavior at least :/ - I'll definitely include examples, that's a great idea.

If the behavior seems wrong we can discuss proposing to change it.


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:

```graphql
input ExampleInputObject {
a: String
b: Int!
}
```

Original Value | Variables | Coerced Value
-------------------------------------------------------------------------------
`{ a: "abc", b: 123 }` | `{}` | `{ a: "abc", b: 123 }`
`{ a: 123, b: "123" }` | `{}` | `{ a: "123", b: 123 }`
`{ a: "abc" }` | `{}` | Error: Missing required field {b}
`{ b: $var }` | `{ var: 123 }` | `{ b: 123 }`
`{ b: $var }` | `{ var: null }` | Error: {b} must be non-null.
`{ b: $var }` | `{}` | Error: {b} must be non-null.
`{ b: $var }` | `{}` | Error: {b} must be non-null.
`{ a: $var, b: 1 }` | `{ var: null }` | `{ a: null, b: 1 }`
`{ a: $var, b: 1 }` | `{}` | `{ b: 1 }`

#### Input Object type validation

1. An Input Object type must define one or more fields.
Expand Down
Loading