From d481d173749a03e342434070d14fb47116272dfa Mon Sep 17 00:00:00 2001
From: Lee Byron <lee@leebyron.com>
Date: Tue, 5 Apr 2016 19:38:48 -0700
Subject: [PATCH] RFC: Return type overlap validation

This alters the "Overlapping Fields Can Be Merged" validation rule to better express return type validation issues.

The existing rule has presented some false-positives in some schema where interfaces with co-variant types are commonly used. The "same return type" check doesn't remove any ambiguity.

Instead what that "same return type" check is attempting to prevent is spreading two fragments (or inline fragments) which have fields with return types where ambiguity would be introduced in the response.

In order to curb false-positives, we later changed this rule such that if two fields were known to never apply simultaneously, then we would skip the remainder of the rule.

```
{
  ... on Person {
    foo: fullName
  }
  ... on Pet {
    foo: petName
  }
}
```

However this can introduce false-negatives!

```
{
  ... on Person {
    foo: birthday {
      bar: year
    }
  }
  ... on Business {
    foo: location {
      bar: street
    }
  }
}
```

In the above example, `data.foo.bar` could be of type `Int` or type `String`, it's ambiguous!

This differing return type breaks some client model implementations (Fragment models) in addition to just being confusing.

For example this invalid query:

```
fragment A on Type {
  field: someIntField
}

fragment B on Type {
  ...A
  field: someStringField
}
```

Might produce the following illegal Java artifacts:

```
interface A {
  int getField()
}

interface B implements A {
  string getField()
}
```
---
 spec/Section 5 -- Validation.md | 47 +++++++++++++++++++++++++++++----
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md
index c58540d49..de36c5f72 100644
--- a/spec/Section 5 -- Validation.md	
+++ b/spec/Section 5 -- Validation.md	
@@ -286,15 +286,37 @@ FieldsInSetCanMerge(set) :
   * Let {fieldsForName} be the set of selections with a given response name in
     {set} including visiting fragments and inline fragments.
   * Given each pair of members {fieldA} and {fieldB} in {fieldsForName}:
+    * {SameResponseShape(fieldA, fieldB)} must be true.
     * If the parent types of {fieldA} and {fieldB} are equal or if either is not
       an Object Type:
       * {fieldA} and {fieldB} must have identical field names.
-      * {fieldA} and {fieldB} must have identical return type.
       * {fieldA} and {fieldB} must have identical sets of arguments.
       * Let {mergedSet} be the result of adding the selection set of {fieldA}
         and the selection set of {fieldB}.
       * {FieldsInSetCanMerge(mergedSet)} must be true.
 
+SameResponseShape(fieldA, fieldB) :
+  * Let {typeA} be the return type of {fieldA}.
+  * Let {typeB} be the return type of {fieldB}.
+  * If {typeA} or {typeB} is Non-Null.
+    * {typeA} and {typeB} must both be Non-Null.
+    * Let {typeA} be the nullable type of {typeA}
+    * Let {typeB} be the nullable type of {typeB}
+  * If {typeA} or {typeB} is List.
+    * {typeA} and {typeB} must both be List.
+    * Let {typeA} be the item type of {typeA}
+    * Let {typeB} be the item type of {typeB}
+    * Repeat from step 3.
+  * If {typeA} or {typeB} is Scalar or Enum.
+    * {typeA} and {typeB} must be the same type.
+  * Assert: {typeA} and {typeB} are both composite types.
+  * Let {mergedSet} be the result of adding the selection set of {fieldA} and
+    the selection set of {fieldB}.
+  * Let {fieldsForName} be the set of selections with a given response name in
+    {mergedSet} including visiting fragments and inline fragments.
+  * Given each pair of members {subfieldA} and {subfieldB} in {fieldsForName}:
+    * {SameResponseShape(subfieldA, subfieldB)} must be true.
+
 ** Explanatory Text **
 
 If multiple fields selections with the same response names are encountered
@@ -369,16 +391,16 @@ fragment differingArgs on Dog {
 }
 ```
 
-The following would not merge together, however both cannot be encountered
-against the same object:
+The following fields would not merge together, however both cannot be
+encountered against the same object, so they are safe:
 
 ```graphql
 fragment safeDifferingFields on Pet {
   ... on Dog {
-    name: nickname
+    volume: barkVolume
   }
   ... on Cat {
-    name
+    volume: meowVolume
   }
 }
 
@@ -392,6 +414,21 @@ fragment safeDifferingArgs on Pet {
 }
 ```
 
+However, the field responses must be shapes which can be merged. For example,
+scalar values must not differ. In this example, `someValue` might be a `String`
+or an `Int`:
+
+```!graphql
+fragment conflictingDifferingResponses on Pet {
+  ... on Dog {
+    someValue: nickname
+  }
+  ... on Cat {
+    someValue: meowVolume
+  }
+}
+```
+
 
 ### Leaf Field Selections