RFC: OneOf Input Objects

cspell.yml

@@ -21,3 +21,5 @@ words:
   - tatooine
   - zuck
   - zuckerberg
+  - brontie
+  - oneOf

spec/Section 3 -- Type System.md

@@ -1520,6 +1520,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.oneOf` 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
@@ -1613,6 +1635,21 @@ is constructed with the following rules:
   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 error must be thrown.
+
+- If the single entry in the input object literal or unordered map is {null}, an
+  error must be thrown.
+
+- If the coerced unordered map does not contain exactly one entry, an error must
+  be thrown.
+
+- If the value of the single entry in the coerced unordered map is {null}, an
+  error must be thrown.
+
 Following are examples of input coercion for an input object type with a
 `String` field `a` and a required (non-null) `Int!` field `b`:
 
@@ -1642,6 +1679,37 @@ 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            |
+| `{ b: 123 }`             | `{}`                    | `{ b: 123 }`                                        |
+| `{ a: $var, b: 123 }`    | `{ var: null }`         | Error: Exactly one key must be specified            |
+| `{ a: $var, b: 123 }`    | `{}`                    | Error: Exactly one key must be specified            |
+| `{ b: $var }`            | `{ var: 123 }`          | `{ b: 123 }`                                        |
+| `$var`                   | `{ var: { b: 123 } }`   | `{ b: 123 }`                                        |
+| `"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}         |
+| `{ a: "abc" }`           | `{}`                    | `{ a: "abc" }`                                      |
+| `{ b: $var }`            | `{}`                    | 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: $var }`            | `{ var: null }`         | Error: Value for member field {b} must be non-null  |
+| `{ b: 123, c: "xyz" }`   | `{}`                    | Error: Unexpected field {c}                         |
+| `{ a: $a, b: $b }`       | `{ a: "abc" }`          | Error: Exactly one key must be specified            |
+
 **Type Validation**
 
 1. An Input Object type must define one or more input fields.
@@ -1652,6 +1720,9 @@ input ExampleInputObject {
       {"\_\_"} (two underscores).
    3. The input field must accept a type where {IsInputType(inputFieldType)}
       returns {true}.
+   4. 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.
@@ -1679,6 +1750,10 @@ defined.
    the original Input Object.
 4. Any non-repeatable directives provided must not already apply to the original
    Input Object type.
+5. 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
 
@@ -1898,6 +1973,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.
 
@@ -2085,3 +2163,31 @@ 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` 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
+}
+```
+
+```graphql example
+type Query {
+  findUser(
+    byID: ID
+    byUsername: String
+    byEmail: String
+    byRegistrationNumber: Int
+  ): User @oneOf
+}
+```

spec/Section 4 -- Introspection.md

@@ -150,6 +150,8 @@ type __Type {
   ofType: __Type
   # may be non-null for custom SCALAR, otherwise null.
   specifiedByURL: String
+  # should be non-null for INPUT_OBJECT only
+  oneOf: Boolean
 }
 
 enum __TypeKind {
@@ -367,6 +369,8 @@ Fields\:
 - `name` must return a String.
 - `description` may return a String or {null}.
 - `inputFields` must return the set of input fields as a list of `__InputValue`.
+- `oneOf` must return {true} when representing a OneOf Input Object, {false}
+  otherwise.
 - All other fields must return {null}.
 
 **List**

spec/Section 5 -- Validation.md

@@ -40,6 +40,10 @@ type Query {
   dog: Dog
 }
 
+type Mutation {
+  addPet(pet: PetInput): Pet
+}
+
 enum DogCommand {
   SIT
   DOWN
@@ -87,6 +91,23 @@ type Cat implements Pet {
 union CatOrDog = Cat | Dog
 union DogOrHuman = Dog | Human
 union HumanOrAlien = Human | Alien
+
+input CatInput {
+  name: String!
+  nickname: String
+  meowVolume: Int
+}
+
+input DogInput {
+  name: String!
+  nickname: String
+  barkVolume: Int
+}
+
+input PetInput @oneOf {
+  cat: CatInput
+  dog: DogInput
+}
 ```
 
 ## Documents
@@ -1406,6 +1427,103 @@ arguments, an input object may have required fields. An input field is required
 if it has a non-null type and does not have a default value. Otherwise, the
 input object field is optional.
 
+### OneOf Input Objects Have Exactly One Field
+
+**Formal Specification**
+
+- For each {operation} in {document}:
+  - Let {oneofInputObjects} be all OneOf Input Objects transitively included in
+    the {operation}.
+  - For each {oneofInputObject} in {oneofInputObjects}:
+    - Let {fields} be the fields provided by {oneofInputObject}.
+    - {fields} must contain exactly one entry.
+    - Let {field} be the sole entry in {fields}.
+    - Let {value} be the value of {field}.
+    - {value} must not be the {null} literal.
+    - If {value} is a variable:
+      - Let {variableName} be the name of {variable}.
+      - Let {variableDefinition} be the {VariableDefinition} named
+        {variableName} defined within {operation}.
+      - Let {variableType} be the expected type of {variableDefinition}.
+      - {variableType} must be a non-null type.
+
+**Explanatory Text**
+
+OneOf Input Objects require that exactly one field must be supplied and that
+field must not be {null}.
+
+An empty OneOf Input Object is invalid.
+
+```graphql counter-example
+mutation addPet {
+  addPet(pet: {}) {
+    name
+  }
+}
+```
+
+Multiple fields are not allowed.
+
+```graphql counter-example
+mutation addPet($cat: CatInput, $dog: DogInput) {
+  addPet(pet: { cat: $cat, dog: $dog }) {
+    name
+  }
+}
+```
+
+```graphql counter-example
+mutation addPet($dog: DogInput) {
+  addPet(pet: { cat: { name: "Brontie" }, dog: $dog }) {
+    name
+  }
+}
+```
+
+```graphql counter-example
+mutation addPet {
+  addPet(pet: { cat: { name: "Brontie" }, dog: null }) {
+    name
+  }
+}
+```
+
+Variables used for OneOf Input Object fields must be non-nullable.
+
+```graphql example
+mutation addPet($cat: CatInput!) {
+  addPet(pet: { cat: $cat }) {
+    name
+  }
+}
+```
+
+```graphql counter-example
+mutation addPet($cat: CatInput) {
+  addPet(pet: { cat: $cat }) {
+    name
+  }
+}
+```
+
+If a field with a literal value is present then the value must not be {null}.
+
+```graphql example
+mutation addPet {
+  addPet(pet: { cat: { name: "Brontie" } }) {
+    name
+  }
+}
+```
+
+```graphql counter-example
+mutation addPet {
+  addPet(pet: { cat: null }) {
+    name
+  }
+}
+```
+
 ## Directives
 
 ### Directives Are Defined