InputUnion: K, L, M, N evaluations and spec summary for @oneOf (#660)

* @onefield evaluations

* Add a 'summary of spec changes' section

* Add placeholder evaluations for other solutions

Author: benjie

rfcs/InputUnion.md

@@ -301,7 +301,7 @@ The less typing and fewer bytes transmitted, the better.
 
 | [1](#-1-explicit-__typename-discriminator-field) | [2](#-2-explicit-configurable-discriminator-field) | [3](#-3-order-based-discrimination) | [4](#-4-structural-uniqueness) | [5](#-5-one-of-tagged-union) |
 |----|----|----|----|----|
-| ❔ | ❔ | ❔ | ❔ | ❔ |
+| ❔ | ❔ | ❔ | ❔ | ✅ |
 
 ## 🎯 L. Input unions should be performant for servers
 
@@ -311,23 +311,23 @@ Ideally a server does not have to do much computation to determine which concret
 
 | [1](#-1-explicit-__typename-discriminator-field) | [2](#-2-explicit-configurable-discriminator-field) | [3](#-3-order-based-discrimination) | [4](#-4-structural-uniqueness) | [5](#-5-one-of-tagged-union) |
 |----|----|----|----|----|
-| ❔ | ❔ | ❔ | ❔ | ❔ |
+| ❔ | ❔ | ❔ | ❔ | ✅ |
 
 ## 🎯 M. Existing SDL parsers are backwards compatible with SDL additions
 
 Common tools that parse GraphQL SDL should not fail when pointed at a schema which supports polymorphic input types.
 
 | [1](#-1-explicit-__typename-discriminator-field) | [2](#-2-explicit-configurable-discriminator-field) | [3](#-3-order-based-discrimination) | [4](#-4-structural-uniqueness) | [5](#-5-one-of-tagged-union) |
 |----|----|----|----|----|
-| ❔ | ❔ | ❔ | ❔ | ❔ |
+| ❔ | ❔ | ❔ | ❔ | ✅ |
 
 ## 🎯 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](#-1-explicit-__typename-discriminator-field) | [2](#-2-explicit-configurable-discriminator-field) | [3](#-3-order-based-discrimination) | [4](#-4-structural-uniqueness) | [5](#-5-one-of-tagged-union) |
 |----|----|----|----|----|
-| ❔ | ❔ | ❔ | ❔ | ❔ |
+| ❔ | ❔ | ❔ | ❔ | ✅ |
 
 # 🚧 Possible Solutions
 
@@ -398,6 +398,14 @@ type Mutation {
   * ✅ Defaulting to the previous input type enables upgrading
 * [J. A GraphQL schema that supports input unions can be queried by older GraphQL clients](#-j-a-graphql-schema-that-supports-input-unions-can-be-queried-by-older-graphql-clients)
   * ✅ Changes are additive only
+* [K. Input unions should be expressed efficiently in the query and on the wire](#-k-input-unions-should-be-expressed-efficiently-in-the-query-and-on-the-wire)
+  * ❔ Not evaluated
+* [L. Input unions should be performant for servers](#-l-input-unions-should-be-performant-for-servers)
+  * ❔ Not evaluated
+* [M. Existing SDL parsers are backwards compatible with SDL additions](#-m-existing-sdl-parsers-are-backwards-compatible-with-sdl-additions)
+  * ❔ Not evaluated
+* [N. Existing code generated tooling is backwards compatible with Introspection additions](#-n-existing-code-generated-tooling-is-backwards-compatible-with-introspection-additions)
+  * ❔ Not evaluated
 
 ## 💡 2. Explicit configurable Discriminator field
 
@@ -526,6 +534,14 @@ input DogInput {
   * ✅ Defaulting to the previous input type enables upgrading
 * [J. A GraphQL schema that supports input unions can be queried by older GraphQL clients](#-j-a-graphql-schema-that-supports-input-unions-can-be-queried-by-older-graphql-clients)
   * ✅ Changes are additive only
+* [K. Input unions should be expressed efficiently in the query and on the wire](#-k-input-unions-should-be-expressed-efficiently-in-the-query-and-on-the-wire)
+  * ❔ Not evaluated
+* [L. Input unions should be performant for servers](#-l-input-unions-should-be-performant-for-servers)
+  * ❔ Not evaluated
+* [M. Existing SDL parsers are backwards compatible with SDL additions](#-m-existing-sdl-parsers-are-backwards-compatible-with-sdl-additions)
+  * ❔ Not evaluated
+* [N. Existing code generated tooling is backwards compatible with Introspection additions](#-n-existing-code-generated-tooling-is-backwards-compatible-with-introspection-additions)
+  * ❔ Not evaluated
 
 ## 💡 3. Order based discrimination
 
@@ -603,6 +619,14 @@ type Mutation {
   * ✅ Listing the old input type first enables enables upgrading
 * [J. A GraphQL schema that supports input unions can be queried by older GraphQL clients](#-j-a-graphql-schema-that-supports-input-unions-can-be-queried-by-older-graphql-clients)
   * ✅ Changes are additive only
+* [K. Input unions should be expressed efficiently in the query and on the wire](#-k-input-unions-should-be-expressed-efficiently-in-the-query-and-on-the-wire)
+  * ❔ Not evaluated
+* [L. Input unions should be performant for servers](#-l-input-unions-should-be-performant-for-servers)
+  * ❔ Not evaluated
+* [M. Existing SDL parsers are backwards compatible with SDL additions](#-m-existing-sdl-parsers-are-backwards-compatible-with-sdl-additions)
+  * ❔ Not evaluated
+* [N. Existing code generated tooling is backwards compatible with Introspection additions](#-n-existing-code-generated-tooling-is-backwards-compatible-with-introspection-additions)
+  * ❔ Not evaluated
 
 ## 💡 4. Structural uniqueness
 
@@ -685,6 +709,14 @@ input DogInput {
   * ⚠️ All new types added to the union must differ structurally from the previous type
 * [J. A GraphQL schema that supports input unions can be queried by older GraphQL clients](#-j-a-graphql-schema-that-supports-input-unions-can-be-queried-by-older-graphql-clients)
   * ✅ Changes are additive only
+* [K. Input unions should be expressed efficiently in the query and on the wire](#-k-input-unions-should-be-expressed-efficiently-in-the-query-and-on-the-wire)
+  * ❔ Not evaluated
+* [L. Input unions should be performant for servers](#-l-input-unions-should-be-performant-for-servers)
+  * ❔ Not evaluated
+* [M. Existing SDL parsers are backwards compatible with SDL additions](#-m-existing-sdl-parsers-are-backwards-compatible-with-sdl-additions)
+  * ❔ Not evaluated
+* [N. Existing code generated tooling is backwards compatible with Introspection additions](#-n-existing-code-generated-tooling-is-backwards-compatible-with-introspection-additions)
+  * ❔ Not evaluated
 
 ## 💡 5. One Of (Tagged Union)
 
@@ -749,7 +781,23 @@ type Mutation {
   * ✅ No migration required, as this pattern is already possible
 * [J. A GraphQL schema that supports input unions can be queried by older GraphQL clients](#-j-a-graphql-schema-that-supports-input-unions-can-be-queried-by-older-graphql-clients)
   * ✅ Changes are additive only
+* [K. Input unions should be expressed efficiently in the query and on the wire](#-k-input-unions-should-be-expressed-efficiently-in-the-query-and-on-the-wire)
+  * ✅ 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](#-l-input-unions-should-be-performant-for-servers)
+  * ✅ Type is easily determined by looking up the specified field name
+* [M. Existing SDL parsers are backwards compatible with SDL additions](#-m-existing-sdl-parsers-are-backwards-compatible-with-sdl-additions)
+  * ✅ Proposal uses a simple directive; directive parsing is widely supported
+* [N. Existing code generated tooling is backwards compatible with Introspection additions](#-n-existing-code-generated-tooling-is-backwards-compatible-with-introspection-additions)
+  * ✅ Existing code generation tools will degrade gracefully to a regular input object
+
+### Summary of spec changes
+
+- **SDL**: enable use of `@oneOf` directive on input object type definitions
+- **Introspection**: add `requiresExactlyOneField: Boolean` field to `__Type` type
+- **Schema validation**: all fields on a `@oneOf` input type must be nullable, and must not have defaults
+- **Operation validation**: when validating a `@oneOf` input object, assert that exactly one field was specified
 
+[The full spec changes can be seen here](https://github.com/graphql/graphql-spec/pull/586/files).
 
 # 🏆 Evaluation Overview
 
@@ -767,7 +815,7 @@ A quick glance at the evaluation results. Remember that passing or failing a spe
 | [H](#-h-input-unions-should-accept-plain-data) | ⚠️ | ⚠️ | ✅ | ✅ | ⚠️ |
 | [I](#-i-input-unions-should-be-easy-to-upgrade-from-existing-solutions) | ✅⚠️ | ✅⚠️ | ✅ | ⚠️ | ✅ |
 | [J](#-j-a-graphql-schema-that-supports-input-unions-can-be-queried-by-older-graphql-clients) | ✅ | ✅ | ✅ | ✅ | ✅ |
-| [K](#-k-input-unions-should-be-expressed-efficiently-in-the-query-and-on-the-wire) | ❔ | ❔ | ❔ | ❔ | ❔ |
-| [L](#-l-input-unions-should-be-performant-for-servers) | ❔ | ❔ | ❔ | ❔ | ❔ |
-| [M](#-m-existing-sdl-parsers-are-backwards-compatible-with-sdl-additions) | ❔ | ❔ | ❔ | ❔ | ❔ |
-| [N](#-n-existing-code-generated-tooling-is-backwards-compatible-with-introspection-additions) | ❔ | ❔ | ❔ | ❔ | ❔ |
+| [K](#-k-input-unions-should-be-expressed-efficiently-in-the-query-and-on-the-wire) | ❔ | ❔ | ❔ | ❔ | ✅ |
+| [L](#-l-input-unions-should-be-performant-for-servers) | ❔ | ❔ | ❔ | ❔ | ✅ |
+| [M](#-m-existing-sdl-parsers-are-backwards-compatible-with-sdl-additions) | ❔ | ❔ | ❔ | ❔ | ✅ |
+| [N](#-n-existing-code-generated-tooling-is-backwards-compatible-with-introspection-additions) | ❔ | ❔ | ❔ | ❔ | ✅ |