allow unions to include interfaces and unions

Author: yaacovCR

spec/Section 3 -- Type System.md

@@ -923,8 +923,8 @@ IsValidImplementationFieldType(fieldType, implementedFieldType):
    3. Return {IsValidImplementationFieldType(itemType, implementedItemType)}.
 3. If {fieldType} is the same type as {implementedFieldType} then return {true}.
 4. If {fieldType} is an Object type and {implementedFieldType} is a Union type
-   and {fieldType} is a possible type of {implementedFieldType} then return
-   {true}.
+   and {fieldType} is a possible type or member type of {implementedFieldType}
+   then return {true}.
 5. If {fieldType} is an Object or Interface type and {implementedFieldType} is
    an Interface type and {fieldType} declares it implements
    {implementedFieldType} then return {true}.
@@ -1302,8 +1302,8 @@ UnionMemberTypes :
 - = `|`? NamedType
 
 GraphQL Unions represent an object that could be one of a list of GraphQL Object
-types, but provides for no guaranteed fields between those types. They also
-differ from interfaces in that Object types declare what interfaces they
+types, providing for no guaranteed fields between those types. They differ from
+interfaces in that Object and Interface types declare what interfaces they
 implement, but are not aware of what unions contain them.
 
 With interfaces and objects, only those fields defined on the type can be
@@ -1370,6 +1370,61 @@ union SearchResult =
   | Person
 ```
 
+**Unions of Interfaces and Unions**
+
+A Union may declare interfaces or other unions as member types. The parent
+Union's possible types transitively include all the possible types of any
+abstract member types. For example, the following types are valid:
+
+```graphql example
+union SearchResult = Photo | Named
+
+interface Named {
+  name: String
+}
+
+type Person {
+  name: String
+  age: Int
+}
+
+union Item = Photo | Video
+
+type Photo {
+  height: Int
+  width: Int
+}
+
+type Video {
+  codec: String
+}
+
+type SearchQuery {
+  firstSearchResult: SearchResult
+}
+```
+
+And, given the above, the following operation is valid:
+
+```graphql example
+{
+  firstSearchResult {
+    ... on Named {
+      name
+    }
+    ... on Person {
+      age
+    }
+    ... on Photo {
+      height
+    }
+    ... on Video {
+      codec
+    }
+  }
+}
+```
+
 **Result Coercion**
 
 The union type should have some way of determining which object a given result
@@ -1385,8 +1440,8 @@ Unions are never valid inputs.
 Union types have the potential to be invalid if incorrectly defined.
 
 1. A Union type must include one or more unique member types.
-2. The member types of a Union type must all be Object base types; Scalar,
-   Interface and Union types must not be member types of a Union. Similarly,
+2. The member types of a Union type must all be Object, Interface or Union
+   types; Scalar and Enum types must not be member types of a Union. Similarly,
    wrapping types must not be member types of a Union.
 
 ### Union Extensions
@@ -1406,9 +1461,9 @@ another GraphQL service.
 Union type extensions have the potential to be invalid if incorrectly defined.
 
 1. The named type must already be defined and must be a Union type.
-2. The member types of a Union type extension must all be Object base types;
-   Scalar, Interface and Union types must not be member types of a Union.
-   Similarly, wrapping types must not be member types of a Union.
+2. The member types of a Union type must all be Object, Interface or Union
+   types; Scalar and Enum types must not be member types of a Union. Similarly,
+   wrapping types must not be member types of a Union.
 3. All member types of a Union type extension must be unique.
 4. All member types of a Union type extension must not already be a member of
    the original Union type.

spec/Section 4 -- Introspection.md

@@ -140,6 +140,8 @@ type __Type {
   fields(includeDeprecated: Boolean = false): [__Field!]
   # must be non-null for OBJECT and INTERFACE, otherwise null.
   interfaces: [__Type!]
+  # must be non-null for UNION, otherwise null.
+  memberTypes: [__Type!]
   # must be non-null for INTERFACE and UNION, otherwise null.
   possibleTypes: [__Type!]
   # must be non-null for ENUM, otherwise null.
@@ -297,7 +299,8 @@ Fields\:
 
 **Union**
 
-Unions are an abstract type where no common fields are declared. The possible
+Unions are an abstract type where no common fields are declared. The declared
+member types of a union are accessible via `memberTypes`. The possible Object
 types of a union are explicitly listed out in `possibleTypes`. Types can be made
 parts of unions without modification of that type.
 
@@ -306,8 +309,9 @@ Fields\:
 - `kind` must return `__TypeKind.UNION`.
 - `name` must return a String.
 - `description` may return a String or {null}.
-- `possibleTypes` returns the list of types that can be represented within this
-  union. They must be object types.
+- `memberTypes` returns the list of member types declared by the union.
+- `possibleTypes` returns the list of Object types that can be represented
+  within this union.
 - All other fields must return {null}.
 
 **Interface**