From dcabd09f1b9eb3f676ef3a28d7a65d6ba81ff25b Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Tue, 10 Dec 2019 14:39:13 +0000 Subject: [PATCH 1/3] @oneField evaluations --- rfcs/InputUnion.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/rfcs/InputUnion.md b/rfcs/InputUnion.md index f80132e51..6f3a46b45 100644 --- a/rfcs/InputUnion.md +++ b/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,7 +311,7 @@ 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 @@ -319,7 +319,7 @@ Common tools that parse GraphQL SDL should not fail when pointed at a schema whi | [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 @@ -327,7 +327,7 @@ For example, GraphiQL should successfully render when pointed at a schema which | [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 @@ -749,7 +749,14 @@ 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 # 🏆 Evaluation Overview @@ -767,7 +774,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) | ❔ | ❔ | ❔ | ❔ | ✅ | From bc0559f1e493b270a7cdbf56d5523be752affe80 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Tue, 10 Dec 2019 14:47:11 +0000 Subject: [PATCH 2/3] Add a 'summary of spec changes' section --- rfcs/InputUnion.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/rfcs/InputUnion.md b/rfcs/InputUnion.md index 6f3a46b45..dc1caa935 100644 --- a/rfcs/InputUnion.md +++ b/rfcs/InputUnion.md @@ -758,6 +758,15 @@ type Mutation { * [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 A quick glance at the evaluation results. Remember that passing or failing a specific criteria is NOT the final word. From 3210db77deaadb7608004f979e055866f1406792 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Tue, 10 Dec 2019 14:48:54 +0000 Subject: [PATCH 3/3] Add placeholder evaluations for other solutions --- rfcs/InputUnion.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/rfcs/InputUnion.md b/rfcs/InputUnion.md index dc1caa935..0217a0f2d 100644 --- a/rfcs/InputUnion.md +++ b/rfcs/InputUnion.md @@ -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)