-
Notifications
You must be signed in to change notification settings - Fork 1.1k
RFC: OneOf Input Objects #825
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.
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
base: main
Are you sure you want to change the base?
Changes from all commits
c385058
f6bd659
39e593c
b6741c3
d17d5ec
dca3826
7e02f5a
4111476
6754e0a
7c4c1a2
bb225f7
05fde06
e8f6145
08abf49
59cb12d
c470afb
99aa5d9
691087d
7109dbc
05ab541
6a6be52
de87d2f
57e2388
5a966f2
e78d2b5
c6cd857
d106233
87d0b22
d88d62a
a810aef
a1563a9
b45c0e4
0c9830e
c4d0b50
340594e
dbccf84
17f1304
d15f7bb
6310475
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -1568,6 +1568,28 @@ define arguments or contain 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. | ||
|
||
**OneOf Input Objects** | ||
|
||
OneOf Input Objects are a special variant of Input Objects where the type system | ||
asserts that exactly one of the fields must be set and non-null, all others | ||
being omitted. This is useful for representing situations where an input may be | ||
one of many different options. | ||
|
||
When using the type system definition language, the `@oneOf` directive is used | ||
to indicate that an Input Object is a OneOf Input Object (and thus requires | ||
exactly one of its field be provided): | ||
|
||
```graphql | ||
input UserUniqueCondition @oneOf { | ||
id: ID | ||
username: String | ||
organizationAndEmail: OrganizationAndEmailInput | ||
} | ||
``` | ||
|
||
In schema introspection, the `__Type.isOneOf` field will return {true} for OneOf | ||
Input Objects, and {false} for all other Input Objects. | ||
|
||
**Circular References** | ||
|
||
Input Objects are allowed to reference other Input Objects as field types. A | ||
|
@@ -1661,6 +1683,21 @@ is constructed with the following rules: | |
variable definition does not provide a default value, the input object field | ||
definition's default value should be used. | ||
|
||
Further, if the input object is a OneOf Input Object, the following additional | ||
rules apply: | ||
|
||
- If the input object literal or unordered map does not contain exactly one | ||
entry an _execution error_ must be raised. | ||
|
||
- Within the input object literal or unordered map, if the single entry is the | ||
{null} literal or {null} an _execution error_ must be raised. | ||
|
||
- If the coerced unordered map does not contain exactly one entry an _execution | ||
error_ must be raised. | ||
|
||
- If the value of the single entry in the coerced unordered map is {null} an | ||
_execution error_ must be raised. | ||
|
||
Following are examples of input coercion for an input object type with a | ||
`String` field `a` and a required (non-null) `Int!` field `b`: | ||
|
||
|
@@ -1690,6 +1727,46 @@ input ExampleInputObject { | |
| `{ b: $var }` | `{ var: null }` | Error: {b} must be non-null. | | ||
| `{ b: 123, c: "xyz" }` | `{}` | Error: Unexpected field {c} | | ||
|
||
Following are examples of input coercion for a OneOf Input Object type with a | ||
`String` member field `a` and an `Int` member field `b`: | ||
|
||
```graphql example | ||
input ExampleInputTagged @oneOf { | ||
a: String | ||
b: Int | ||
} | ||
``` | ||
|
||
| Literal Value | Variables | Coerced Value | | ||
| ------------------------ | -------------------------------- | --------------------------------------------------- | | ||
| `{ a: "abc", b: 123 }` | `{}` | Error: Exactly one key must be specified | | ||
| `{ a: null, b: 123 }` | `{}` | Error: Exactly one key must be specified | | ||
| `{ a: null, b: null }` | `{}` | Error: Exactly one key must be specified | | ||
| `{ a: null }` | `{}` | Error: Value for member field {a} must be non-null | | ||
| `{ b: 123 }` | `{}` | `{ b: 123 }` | | ||
| `{}` | `{}` | Error: Exactly one key must be specified | | ||
| `{ a: $a, b: 123 }` | `{ a: null }` | Error: Exactly one key must be specified | | ||
| `{ a: $a, b: 123 }` | `{}` | Error: Exactly one key must be specified | | ||
| `{ a: $a, b: $b }` | `{ a: "abc" }` | Error: Exactly one key must be specified | | ||
| `{ b: $b }` | `{ b: 123 }` | `{ b: 123 }` | | ||
| `$var` | `{ var: { b: 123 } }` | `{ b: 123 }` | | ||
| `$var` | `{ var: { a: "abc", b: 123 } }` | Error: Exactly one key must be specified | | ||
| `$var` | `{ var: { a: "abc", b: null } }` | Error: Exactly one key must be specified | | ||
| `$var` | `{ var: { a: null } }` | Error: Value for member field {a} must be non-null | | ||
| `$var` | `{ var: {} }` | Error: Exactly one key must be specified | | ||
| `"abc123"` | `{}` | Error: Incorrect value | | ||
| `$var` | `{ var: "abc123" } }` | Error: Incorrect value | | ||
| `{ a: "abc", b: "123" }` | `{}` | Error: Exactly one key must be specified | | ||
| `{ b: "123" }` | `{}` | Error: Incorrect value for member field {b} | | ||
| `$var` | `{ var: { b: "abc" } }` | Error: Incorrect value for member field {b} | | ||
| `{ a: "abc" }` | `{}` | `{ a: "abc" }` | | ||
| `{ b: $b }` | `{}` | Error: Value for member field {b} must be specified | | ||
| `$var` | `{ var: { a: "abc" } }` | `{ a: "abc" }` | | ||
| `{ a: "abc", b: null }` | `{}` | Error: Exactly one key must be specified | | ||
| `{ b: $b }` | `{ b: null }` | Error: Value for member field {b} must be non-null | | ||
| `{ b: 123, c: "xyz" }` | `{}` | Error: Unexpected field {c} | | ||
| `$var` | `{ var: { b: 123, c: "xyz" } }` | Error: Unexpected field {c} | | ||
|
||
benjie marked this conversation as resolved.
Show resolved
Hide resolved
|
||
**Type Validation** | ||
|
||
1. An Input Object type must define one or more input fields. | ||
michaelstaib marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
@@ -1702,6 +1779,9 @@ input ExampleInputObject { | |
returns {true}. | ||
4. If input field type is Non-Null and a default value is not defined: | ||
1. The `@deprecated` directive must not be applied to this input field. | ||
5. If the Input Object is a OneOf Input Object then: | ||
1. The type of the input field must be nullable. | ||
2. The input field must not have a default value. | ||
3. If an Input Object references itself either directly or through referenced | ||
Input Objects, at least one of the fields in the chain of references must be | ||
either a nullable or a List type. | ||
|
@@ -1729,6 +1809,12 @@ defined. | |
the previous Input Object. | ||
4. Any non-repeatable directives provided must not already apply to the previous | ||
Input Object type. | ||
5. The `@oneOf` directive must not be provided by an Input Object type | ||
extension. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Why is this the case? extend is useful for tooling to "create types" in a peicemeal fashion. Not everyone needs to know all the details but it needs to be validated at the end at actual schema creation time
and
The following once combined is valid surely? if we had an invalid combination say
and
then this can be validated at the time the actual runtime schema object is created. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Twofold: it’s because a ”OneOf Input Object” may be constructed in a different way to traditional input objects (might use a different class or similar), and because if this was not the case then when the directive was added you’d have to go back and validate all previously added fields since they have different “potential to be invalid” text. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hmm kinda feels like this is projecting an implementation into the spec situation.
I would argue that the spec should not care how its implemented - sure it could be a new OneOfInputType class at implementation time (I toyed with this in graphql-java but rejected it as too much impact) but the spec shouldn't care.
Again an implementation detail - not sure that the spec should care. Even merging them seems straightforward since they are a non repeating directive
And implementation can merge these easily enough. Right now the spec says about input types
in other words it allows you to put extra directives on the input types during extension I just feel like this is an unnecessary restriction There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I agree, I'd argue that implementing Input Objects and OneOf Input Objects as the same class in the implementation is an implementation detail that the spec doesn't need to worry about 😉 At one point, oneOf was going to be its own top-level type, like To me, a OneOf Input Object is a distinct type in GraphQL that happens to share a lot with Input Objects, but still has it's own distinct behaviors in many ways. As such, changing an Input Object into a OneOf Input Object would be like changing an Input Object into an Object for me - and that's not something I think the SDL should allow. This is one of the arguments against using the directive syntactical representation in my opinion, and encouraging using a keyword instead - to make the separation clearer.
This second point is not an implementation detail, it's a spec detail - specifically it relates to lines 1724-1726 in There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Along the same thoughts that @benjie is pointing out, I personally would say a different syntactical representation in the SDL would make it appear as a "distinct type", whereas since it is a directive, it is simply additional validation rules on top of the existing input object type. Keep in mind that directives are described as such:
I think this definition fits
So the way this PR is written, I see There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If directives were intended to merely annotate types, and not to modify their behavior, then perhaps There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Indeed, they are a special variant. In my opinion you wouldn't take a broad thing and then turn it into a special variant at a later stage - it needs to be a special variant from the start. But this is my opinion, I'm happy to test it against the broader working group. Imagine for a second that we didn't have input objects. You could imagine taking an object type and tagging it type UserInput @input {
id: ID!
name: String!
bio: String
} This syntactic change could indicate:
This is essentially the input object type at this point. But all we've done as annotated the existing object type with different validation logic and execution behaviors. Is the input object type really not distinct from the object type? Would turning an object type into an This, again, is one of the big issues that I have with using a directive to represent this distinct type. (I'm also in favour of using the directive because it's the smallest change, and allows it to be compatible with existing clients.) This constraint: that you can't add the directive in an extension, is my compromise - to allow us to leverage the benefits of using a directive without the footguns in terms of changing one thing into another at a later stage. |
||
6. If the original Input Object is a OneOf Input Object then: | ||
1. All fields of the Input Object type extension must be nullable. | ||
2. All fields of the Input Object type extension must not have default | ||
values. | ||
|
||
## List | ||
|
||
|
@@ -1954,6 +2040,9 @@ schema. | |
GraphQL implementations that support the type system definition language should | ||
provide the `@specifiedBy` directive if representing custom scalar definitions. | ||
|
||
GraphQL implementations that support the type system definition language should | ||
provide the `@oneOf` directive if representing OneOf Input Objects. | ||
|
||
When representing a GraphQL schema using the type system definition language any | ||
_built-in directive_ may be omitted for brevity. | ||
|
||
|
@@ -2168,3 +2257,20 @@ to the relevant IETF specification. | |
```graphql example | ||
scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") | ||
``` | ||
|
||
### @oneOf | ||
|
||
```graphql | ||
directive @oneOf on INPUT_OBJECT | ||
``` | ||
|
||
The `@oneOf` _built-in directive_ is used within the type system definition | ||
language to indicate an Input Object is a OneOf Input Object. | ||
|
||
```graphql example | ||
input UserUniqueCondition @oneOf { | ||
id: ID | ||
username: String | ||
organizationAndEmail: OrganizationAndEmailInput | ||
} | ||
``` |
Uh oh!
There was an error while loading. Please reload this page.