[2020-05-07] Update Input Union RFC after recent subcommittee meetings

[leebyron]

https://github.com/graphql/graphql-wg/blame/master/notes/2020-05-07.md#L104

[benjie]

Video of session: https://www.youtube.com/watch?v=4NSTbtXRCqY

[benjie]

Notes we took during session:

https://github.com/graphql/graphql-spec/blob/master/rfcs/InputUnion.md

Last months actions:

• Write up solution 6 (merged solutions 1-3) - @leebyron
• Write up how literal values would be reflected in introspection, and contemplate uniqueness requirements - @vince Foley
• What forms can @OneOf take? Can we express input unions in a similar way using oneOf? Can they apply to outputs? Arguments? - @benjie

@OneOf - https://gist.github.com/benjie/e45540ad25ce9c33c2a1552da38adb91

Solution 6:

Rough steps from previous Meeting:

• No immediate requirements for uniqueness. At a minimum, an order-based discriminant is used.
• __typename may be provided (for any input object), and this provides a discriminant.
  • If __typename is provided (for any input object) it MUST match the type name (and only that type name) expected for that input object type.
    • Schema validation requires all type names be unique
• Introduce literal types, these may become a discriminant

Type definition language

inputunion SomeInput = TypeA | TypeB | TypeC

Introspection addition

enum __TypeKind {
  + INPUT_UNION
}

Input object type restriction

Amends the "Input Object Field Names" validation rule

• Given an input object, the field __typename is always allowed. It must be a string.
• Given an input object, if the expected input type is an input object, if provided the field __typename must match the name of that input type.

input Test {
  field: String
}

# Legal input
{ "field": "foo" }

# Legal input
{ "field": "foo", "__typename": "Test" }

# Illegal input
{ "field": "foo", "__typename": "SomeOtherType" }

Discrimination of "ambiguous" Scalar types:

• ex: String vs Enum vs ID

  • Maximum one scalar (including enum) type in a union
  • Otherwise, only input objects allowed (no additional unions)
  • Possible Validation: a Scalar must be defined last

• Languages have mixed capabilities for determining types from eachother

• we want to allow possible futures that might look like { __typename: Int, __value: 12 }

Example of using a built-in scalar

{ "__typename": "Int", 24 }

inputunion TestUnionWScalar =
  | Int
  | SomeObjectType
  
# valid input
24
{ "some": "object" }
{ "some": "object", __typename: "SomeObjectType" }

Example of using a custom scalar

Disambiguation

inputunion TestUnionWCustomScalar =
  | RawJSON
  | SomeObjectType

Forward compatibility

How do new clients deal with old servers?

Clients could decide to include __typename in every input object.

• Clients should probably only provide __typename for input objects that need them
• The burden to provide __typename when necessary likely falls on the developer rather than the framework
• Clients that use introspection can look for the existence of INPUT_UNION in the TypeKind enum to determine if __typename is legal to include in an input object.

inputunion Pet = Cat | Dog
input Cat = { meowVolume: Int }

Nested input unions?

Is there a risk of runaway computational complexity if a field can be an inputunion as well?

• Yes, if there is a cycle in the input graph with an input union and other fields are not required.
  • Note: implementations may want to check required fields first

inputunion Deep = Deep1 | Deep2 | String
input Deep1 { field1: Deep }
input Deep2 { field2: Deep }

{ field1: { field1: { field1: { field3: "somethingelse" } }

inputunion Many = T1 | T2 | T3 | T4
input Base { a: Int, b: Int, c: Int, field: Many }
input T1 { field: Many, a: Int }
input T2 { field: Many, b: Int }
input T3 { field: Many, c: Int }
input T4 { field: Many, d: Int }

{ field: {field: {field: {field: {field: {field: {field: {field: { error: "whoops" }}}}}}}} }

depth d
union of n types
O(n^d) complexity
O(d) if we do field-names-only discrimination

inputunion T = T1 | T2
T1 {a: Int}
T2 {a: String}
{ a: "FOO" }

apparent options:

• complex spec/implementation to cover all these edge cases
• small spec/implementation with footguns or slowness in edge cases
• no implicit/structural discrimination; explicit only

"One of" grammatical approach

taggedinputunion PetInput {
taggedinput PetInput {
inputunion PetInput {
  cat: CatInput
  dog: DogInput
  colony: ColonyType
  integer: Int
  rational: Float
}

tagged Scalar {
  str: String
  int: Int
  loop: Scalar
}

query ($arg: Scalar) {
  foo(arg: $arg) {
    field {#  Scalar
      __typename 
    }
  }
}

oneof Pet {
tagged Pet {
taggedtype Pet {
taggedunion Pet {
  cat: Cat
  dog: Dog
  colony: Colony
  integer: Int
  rational: Float
}

enum TypeKind {
  + INPUT_UNION # input one of unions
  + TAGGED_UNION # output one of unions
}

Open questions:

• Can a tagged union type be used as a member of a traditional union?

• Should it be a different name?

• __typename on the result?

  • __typename can always be requested on an object?
  • but right now __typename is always

• Should the taggedUnion be "ambidexterous"?

• Nullability / required?

  • Should all fields be required to be non-null by validation rule? (Or vice versa?)

• Arguments? Nope

• Directives on tagged type or fields?

  • Need to be added to https://spec.graphql.org/draft/#TypeSystemDirectiveLocation
  • Do we allow this at all?
    • No real obvious reason why not
  • TAGGED_UNION and TAGGED_UNION_FIELD_DEFINITION or TAGGED_UNION_MEMBER something

type Cat {
  bestBud: Cat!
}

tagged Pet @canIPutADirectiveHere {
  cat: Cat @orCanIPutADirectiveHere # The name of this needs to be different for directive locations
}

type Query {
  pet: Pet
}

{ pet { cat { bestBud { name }}}}

{ pet: { cat: null } }

{ pet: null }

• Should non-matching fields be included in the result?

tagged Pet { cat: Cat, dog: Dog }
query { pet: Pet }

{
  pet {
    cat {
      name
    }
    dog {
      name
    }
  }
}

# If using existing object type query rules:
{
  "pet": {
    "cat": { "name": "Scratchy" }
    "dog": null
  }
}

# New rule added: Only one field, and "exactly one field returned"?
{
  "pet": {
    "cat": { "name": "Scratchy" }
  }
}



{
  pet(name: "Whiskers") {
    __taggedfield
    dog {
      name
    }
  }
}



# A: Similar to existing behavior:
# Problem: impossible to tell what type it was (since __typename is "Pet")
{
 "pet": {}
}

# B: New rule?: always include the result type, but have an empty obj for no fields queried?
{
 "pet": {"cat": {}}
}

# C: New rule? always include the result type, but have it be null
# Problem: implies the cat was null! DEFINITELY WRONG!
{
 "pet": {"cat": null}
}

# D: Raises an error if not requested
# Problem: Backwards breaking
{
 "pet": null # with error
}




# Existing union case:
{
  pet(name: "Whiskers") {
    __typename
    ... on Dog {
      name
    }
  }
}

{
 "pet": { "__typename": "Cat" }
}

• When should you use tagged vs union for output?
  • Tagged:
    • Can't query across all types that implement an interface
    • Can't get the __typename of the resulting type
    • Can get the structure of the result without having to use __typename

ACTION - @benjie: rename all "OneOf" / "OneField" to "tagged union" in InputUnions RFC doc.

What does tagged give us?

• dealing with boxed scalar input and output
• _lt and _gt are both Int
• symmetry between input and output

What doesn't tagged output give us that union does?

• __typename of unknown type
• spreading unions

[benjie]

I've updated a PR adding Solution 7 (tagged type) to Input Unions RFC: graphql/graphql-spec#790 (this link also explains why "Solution 7" rather than replacing "Solution 5")

[eapache]

Thanks Benjie, that's great. I think that probably is enough to close out this action item? There were other parts to it initially, but since Tagged Type seems to be the leading solution now I don't know if it's worth e.g. doing more investigation into solution 6?

[benjie]

I think if someone wants to champion it, that would be stellar. But I think you're right that this can be closed. Scheduled it for review at the next WG.