Update Input Unions RFC (#790)

Author: benjie

rfcs/InputUnion.md

@@ -232,9 +232,9 @@ Criteria have been given a "score" according to their relative importance in sol
 
 The premise of this RFC - GraphQL should contain a polymorphic Input type.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅ | ✅ | ✅ | ✅ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅ | ✅ | ✅ | ✅ | ✅ | ❔ | ✅ |
 
 Criteria score: 🥇
 
@@ -244,9 +244,9 @@ Any data structure that can be modeled with output type polymorphism should be a
 
 * ✂️ Objection: composite input types and composite output types are distinct. Fields on composite output types support aliases and arguments whereas fields on composite input types do not. Marking an output field as non-nullable is a non-breaking change, but marking an input field as non-nullable is a breaking change.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅⚠️ | ✅ | ✅ | ✅⚠️ | 🚫 |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅⚠️ | ✅ | ✅ | ✅⚠️ | 🚫 | ❔ | ✅⚠️ |
 
 Criteria score: 🥇
 
@@ -257,19 +257,19 @@ https://graphql.github.io/graphql-spec/draft/#sec-Validation.Type-system-evoluti
 
 Adding a new member type to an Input Union or doing any non-breaking change to existing member types does not result in breaking change. For example, adding a new optional field to member type or changing a field from non-nullable to nullable does not break previously valid client operations.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅ | ✅⚠️ | 🚫 | ⚠️ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅ | ✅⚠️ | 🚫 | ⚠️ | ✅ | ❔ | ✅ |
 
 Criteria score: 🥇
 
 ## 🎯 D. Any member type restrictions are validated in schema
 
 If a solution places any restrictions on member types, compliance with these restrictions should be fully validated during schema building (analagous to how interfaces enforce restrictions on member types).
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅ | ✅ | ✅ | ✅ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅ | ✅ | ✅ | ✅ | ✅ | ❔ | ✅ |
 
 Criteria score: 🥇
 
@@ -281,9 +281,9 @@ In addition to containing Input types, member type may also contain Leaf types l
   * Potential solution: only allow a single built-in leaf type per input union.
 * ✂️ Objection: Output polymorphism is restricted to Object types only. Supporting Leaf types in Input polymorphism would create a new inconsistency.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| 🚫 | 🚫 | ✅⚠️ | 🚫 | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| 🚫 | 🚫 | ✅⚠️ | 🚫 | ✅ | ❔ | ✅ |
 
 Criteria score: 🥉
 
@@ -303,9 +303,9 @@ input union IU = I | { y: Int }
 * ✂️ Objection: achieving this by indicating the default in the union (either explicitly or implicitly via the order) is undesirable as it may require multiple equivalent unions being created where only the default differs.
 * ✂️ Objection: Numerous changes to a schema currently introduce breaking changes. The possibility of a breaking change isn't a breaking change and shouldn't prevent a polymorphic input type from existing.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅⚠️ | ✅⚠️ | ✅ | ⚠️ | 🚫 |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅⚠️ | ✅⚠️ | ✅ | ⚠️ | 🚫 | ❔ | 🚫 |
 
 Criteria score: 🥉
 
@@ -315,9 +315,9 @@ To ease development.
 
 * ✂️ Objection: Adds complexity without enabling any new use cases.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ❔ | ❔ | ❔ | ❔ | ❔ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ❔ | ❔ | ❔ | ❔ | ✅ | ❔ | ✅ |
 
 Criteria score: X (not considered)
 
@@ -329,9 +329,9 @@ In other words: data should require minimal or no transformation and metadata ov
 
 * ✂️ Objection: This is a matter of taste - legitimate [Prior Art](#-prior-art) exists that require formatting / extra metadata.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ⚠️ | ⚠️ | ✅ | ✅ | ⚠️ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ⚠️ | ⚠️ | ✅ | ✅ | ⚠️ | ❔ | ⚠️ |
 
 Criteria score: 🥉
 
@@ -352,19 +352,19 @@ input union IU = { x: String } | { y: Int }
 * ✂️ Objection: May break variable names? Only avoided with care
 * ✂️ Objection: There are different ways people are working around the lack of input unions so it likely won't be feasible to come up with a non-breaking migration path for all of them.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅ | ✅ | ✅ | ⚠️ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅ | ✅ | ✅ | ⚠️ | ✅ | ❔ | ✅ |
 
 Criteria score: 🥉
 
 ## 🎯 J. A GraphQL schema that supports input unions can be queried by older GraphQL clients
 
 Preferably without a loss of or change in previously supported functionality.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅ | ✅ | ✅ | ✅ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅ | ✅ | ✅ | ✅ | ✅ | ❔ | ✅ |
 
 Criteria score: 🥇
 
@@ -377,19 +377,19 @@ The less typing and fewer bytes transmitted, the better.
 * ✂️ Objection: The quantity of "typing" isn't a worthwhile metric, most interactions with an API are programmatic.
 * ✂️ Objection: Simply compressing an HTTP request will reduce the bytes transmitted more than anything having to do with the structure of a Schema.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅ | ⚠️ | ✅ | ✅ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 Criteria score: 🥉
 
 ## 🎯 L. Input unions should be performant for servers
 
 Ideally a server does not have to do much computation to determine which concrete type is represented by an input.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅ | ✅ | ⚠️ | ⚠️ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅ | ✅ | ⚠️ | ⚠️ | ✅ | ❔ | ✅ |
 
 Criteria score: 🥉
 
@@ -400,19 +400,19 @@ Common tools that parse GraphQL SDL should not fail when pointed at a schema whi
 * ✂️ Objection: Evolution of the SDL is expected with new features.
 * ✂️ Objection: SDL syntax error can be a positive as a "fail fast" if a system doesn't know about input unions.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| 🚫 | 🚫 | 🚫 | 🚫 | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| 🚫 | 🚫 | 🚫 | 🚫 | ✅ | ❔ | 🚫 |
 
 Criteria score: X (rejected)
 
 ## 🎯 N. Existing code generated tooling is backwards compatible with Introspection additions
 
 For example, GraphiQL should successfully render when pointed at a schema which contains polymorphic input types. It should continue to function even if it can't support the polymorphic input type.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅ | ❔ | ✅⚠️ |
 
 Criteria score: 🥈
 
@@ -421,9 +421,9 @@ Criteria score: 🥈
 It should be possible to combine existing or new input types to unions freely and with ease.
 Adding an input to one or more unions should not require extraneous changes, constrain or be constrained by schema design.
 
-| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-|----|----|----|----|----|
-| ✅️ | 🚫️ | ❔ | 🚫 | ✅ |
+| [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7]
+|----|----|----|----|----|----|----|
+| ✅️ | 🚫️ | ❔ | 🚫 | ✅ | ❔ | ✅ |
 
 Criteria score: 🥇
 
@@ -865,6 +865,8 @@ type Mutation {
   * ✅ Any GraphQL type may be used
 * [F. Migrating a field to a polymorphic input type is non-breaking][criteria-f]
   * 🚫 Previously-valid inputs now need to be wrapped in a container object
+* [G. Input unions may include other input unions][criteria-g]
+  * ✅ Any GraphQL type may be used, including other tagged types and wrapper types such as list
 * [H. Input unions should accept plain data][criteria-h]
   * ⚠️ The data is wrapped in a (simple) container type
 * [I. Input unions should be easy to upgrade from existing solutions][criteria-i]
@@ -891,27 +893,152 @@ type Mutation {
 
 [The full spec changes can be seen here](https://github.com/graphql/graphql-spec/pull/586/files).
 
+## 💡 6. Pending
+
+Calls within the Input Union working group proposed a new solution, solution 6,
+which is a combination of features from solutions 1-4. It has not been fully
+formalized yet as the working group felt that the Tagged Type was more
+promising at this stage. This section is left as a placeholder for solution 6
+to be formally evaluated at a later time.
+
+For some of the notes we took during the calls, see:
+https://github.com/graphql/graphql-wg/issues/426#issuecomment-685636596
+
+For the calls themselves, see:
+https://www.youtube.com/watch?v=u2dnnpKEHZM&list=PLP1igyLx8foH4M0YAbVqpSo2fS1ElvNVD
+
+## 💡 7. Tagged Type
+
+**Champion:** @benjie
+
+This solution was presented in:
+
+* https://github.com/graphql/graphql-spec/pull/733
+
+It's the spiritual successor of [Solution 5 - the @oneOf
+directive](#solution-5) after extensive feedback from the Input Unions working
+group.
+
+In this solution, a new type is introduced to the GraphQL type system: the
+tagged type. The tagged type has two forms: a `tagged input` (valid only in
+inputs) and a `tagged output` (valid only in outputs), but the definitions look
+identical otherwise.
+
+These tagged types define a list of member fields, exactly one of which must be
+present.
+
+```graphql
+input CatInput {
+  name: String!
+  age: Int!
+  livesLeft: Int
+}
+input DogInput {
+  name: String!
+  age: Int!
+  breed: DogBreed
+}
+
+tagged input AnimalInput {
+  cat: CatInput!
+  dog: DogInput!
+}
+
+type Mutation {
+  logAnimalDropOff(location: String, animals: [AnimalInput!]!): Int
+}
+
+# Variables:
+{
+  location: "Portland, OR",
+  animals: [
+    {
+      cat: {
+        name: "Buster",
+        livesLeft: 7
+      }
+    }
+  ]
+}
+```
+
+There's controversy over whether the `tagged output` should be introduced or
+not, more details on this can be read in
+https://github.com/graphql/graphql-spec/pull/733
+
+### ⚖️ Evaluation
+
+* [A. GraphQL should contain a polymorphic Input type][criteria-a]
+  * ✅ Tagged is a valid version of a polymorphic type
+* [B. Input polymorphism matches output polymorphism][criteria-b]
+  * ✅ When `tagged input` and `tagged output` are both included into the
+    spec, a `tagged output` can have a mirrored `tagged input` in a similar way
+    that a `type` can have a mirrored `input`
+  * ⚠️ There's controversy over whether `tagged output` should be included in
+    the spec as it causes confusion as to when to use union, interface, or
+    tagged
+* [C. Doesn't inhibit schema evolution][criteria-c]
+  * ✅ This technique is an evolution of a technique already in use in many schemas
+* [D. Any member type restrictions are validated in schema][criteria-d]
+  * ✅ Tagged member fields are well defined
+* [E. A member type may be a Leaf type][criteria-e]
+  * ✅ Any GraphQL type may be used, including other tagged types and wrapper types such as list
+* [F. Migrating a field to a polymorphic input type is non-breaking][criteria-f]
+  * 🚫 Previously-valid inputs now need to be wrapped in a container object
+* [G. Input unions may include other input unions][criteria-g]
+  * ✅ Any GraphQL type may be used, including other tagged types and wrapper types such as list
+* [H. Input unions should accept plain data][criteria-h]
+  * ⚠️ The data is wrapped in a (simple) container type
+* [I. Input unions should be easy to upgrade from existing solutions][criteria-i]
+  * ✅ This pattern is already possible, existing tagged inputs can be converted to Tagged type
+* [J. A GraphQL schema that supports input unions can be queried by older GraphQL clients][criteria-j]
+  * ✅ Changes are additive only
+* [K. Input unions should be expressed efficiently in the query and on the wire][criteria-k]
+  * ✅ Indication of the type can be done in 6 additional JSON characters per value (e.g. `{"a":VALUE_HERE}`) and would compress easily.
+* [L. Input unions should be performant for servers][criteria-l]
+  * ✅ Type is easily determined by looking up the specified field name
+* [M. Existing SDL parsers are backwards compatible with SDL additions][criteria-m]
+  * 🚫 New keywords are introduced
+* [N. Existing code generated tooling is backwards compatible with Introspection additions][criteria-n]
+  * ✅⚠️
+* [O. Unconstrained combination of input types to unions][criteria-o]
+  * ✅ Adding or removing member fields to a tagged type requires no extraneous effort and has no non-local consequences
+
+### Summary of spec changes
+
+- **SDL**: introduce new `tagged input` and `tagged output` definitions,
+  including member fields
+- **Introspection**: add new type and `__Type.memberFields` field to relate to
+  these fields, and `__Type.isInputType`/`__Type.isOutputType` fields to
+  differentiate input versus output tagged types
+- **Schema validation**: tagged types must contain only types that are
+  compatible (matching input or output) and must contain at least one field
+- **Operation validation**: when validating a tagged input type, assert that
+  exactly one field was specified
+
+[The full spec changes can be seen here](https://github.com/graphql/graphql-spec/pull/733/files).
+
 # 🏆 Evaluation Overview
 
 A quick glance at the evaluation results. Remember that passing or failing a specific criteria is NOT the final word.
 
-|    | [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] |
-| -- | -- | -- | -- | -- | -- |
-| [A][criteria-a] 🥇 | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [B][criteria-b] 🥇 | ✅⚠️ | ✅ | ✅ | ✅⚠️ | 🚫 |
-| [C][criteria-c] 🥇 | ✅ | ✅⚠️ | 🚫 | ⚠️ | ✅ |
-| [D][criteria-d] 🥇 | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [E][criteria-e] 🥉 | 🚫 | 🚫 | ✅⚠️ | 🚫 | ✅ |
-| [F][criteria-f] 🥉 | ✅⚠️ | ✅⚠️ | ✅ | ⚠️ | 🚫 |
-| [G][criteria-g] 🥉 | ❔ | ❔ | ❔ | ❔ | ❔ |
-| [H][criteria-h] 🥉 | ⚠️ | ⚠️ | ✅ | ✅ | ⚠️ |
-| [I][criteria-i] 🥉 | ✅ | ✅ | ✅ | ⚠️ | ✅ |
-| [J][criteria-j] 🥇 | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [K][criteria-k] 🥉 | ✅ | ⚠️ | ✅ | ✅ | ✅ |
-| [L][criteria-l] 🥉 | ✅ | ✅ | ⚠️ | ⚠️ | ✅ |
-| [M][criteria-m] 🥈 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ |
-| [N][criteria-n] 🥈 | ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅ |
-| [O][criteria-o] 🥈 | ✅️ | 🚫️ | ❔ | 🚫 | ✅ |
+|    | [1][solution-1] | [2][solution-2] | [3][solution-3] | [4][solution-4] | [5][solution-5] | [6][solution-6] | [7][solution-7] |
+| -- | -- | -- | -- | -- | -- | -- | -- |
+| [A][criteria-a] 🥇 | ✅ | ✅ | ✅ | ✅ | ✅ | ? | ✅ |
+| [B][criteria-b] 🥇 | ✅⚠️ | ✅ | ✅ | ✅⚠️ | 🚫 | ? | ✅⚠️ |
+| [C][criteria-c] 🥇 | ✅ | ✅⚠️ | 🚫 | ⚠️ | ✅ | ? | ✅ |
+| [D][criteria-d] 🥇 | ✅ | ✅ | ✅ | ✅ | ✅ | ? | ✅ |
+| [E][criteria-e] 🥉 | 🚫 | 🚫 | ✅⚠️ | 🚫 | ✅ | ? | ✅ |
+| [F][criteria-f] 🥉 | ✅⚠️ | ✅⚠️ | ✅ | ⚠️ | 🚫 | ? | 🚫 |
+| [G][criteria-g] 🥉 | ❔ | ❔ | ❔ | ❔ | ❔ | ? | ✅ |
+| [H][criteria-h] 🥉 | ⚠️ | ⚠️ | ✅ | ✅ | ⚠️ | ? | ⚠️ |
+| [I][criteria-i] 🥉 | ✅ | ✅ | ✅ | ⚠️ | ✅ | ? | ✅ |
+| [J][criteria-j] 🥇 | ✅ | ✅ | ✅ | ✅ | ✅ | ? | ✅ |
+| [K][criteria-k] 🥉 | ✅ | ⚠️ | ✅ | ✅ | ✅ | ? | ✅ |
+| [L][criteria-l] 🥉 | ✅ | ✅ | ⚠️ | ⚠️ | ✅ | ? | ✅ |
+| [M][criteria-m] 🥈 | 🚫 | 🚫 | 🚫 | 🚫 | ✅ | ? | 🚫 |
+| [N][criteria-n] 🥈 | ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅⚠️ | ✅ | ? | ✅⚠️ |
+| [O][criteria-o] 🥈 | ✅️ | 🚫️ | ❔ | 🚫 | ✅ | ? | ✅ |
 
 [criteria-a]: #-a-graphql-should-contain-a-polymorphic-input-type
 [criteria-b]: #-b-input-polymorphism-matches-output-polymorphism
@@ -934,12 +1061,17 @@ A quick glance at the evaluation results. Remember that passing or failing a spe
 [solution-3]: #-3-order-based-discrimination
 [solution-4]: #-4-structural-uniqueness
 [solution-5]: #-5-one-of-tagged-union
+[solution-6]: #-6-pending
+[solution-7]: #-7-tagged-type
 
 # ☑️ Decision Time!
 
-According to a simple [weight ranking](https://docs.google.com/spreadsheets/d/1ymKqI6BSTHGGHkf9IDjo0EJmOqMryS-uQRwDV77OF5g/edit?usp=sharing), here are the solutions in order:
+Following meetings of the GraphQL Input Unions working group, [Solution 7][solution-7] was
+proposed as an evolution of Solution 5, and is currently the leading solution.
+
+~~According to a simple [weight ranking](https://docs.google.com/spreadsheets/d/1ymKqI6BSTHGGHkf9IDjo0EJmOqMryS-uQRwDV77OF5g/edit?usp=sharing), here are the solutions in order:~~
 
-* [5][solution-5]
-* [1][solution-1]
-* [2][solution-2]
-* [3][solution-3] / [4][solution-4]
+* ~~[5][solution-5]~~
+* ~~[1][solution-1]~~
+* ~~[2][solution-2]~~
+* ~~[3][solution-3] / [4][solution-4]~~