Skip to content

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

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

Merged
merged 3 commits into from
Dec 11, 2019
Merged

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dcabd09
@oneField evaluations
benjie Dec 10, 2019
bc0559f
Add a 'summary of spec changes' section
benjie Dec 10, 2019
3210db7
Add placeholder evaluations for other solutions
benjie Dec 10, 2019
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
64 changes: 56 additions & 8 deletions rfcs/InputUnion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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

Expand All @@ -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) | ❔ | ❔ | ❔ | ❔ | ✅ |