[Federation] Support value types

docs/source/federation/core-concepts.md

@@ -165,24 +165,32 @@ extend type Query {
 
 There is no need to explictly define `Query` or `Mutation` base types anywhere; Apollo automatically handles this for you.
 
-## Sharing Types
+## Value Types
 
-Sometimes, Enum or Scalar types are needed in multiple services. Rather than having a single service "own" those types, all services that use them are expected to share ownership of those types.
+A natural overlap among identical types between services is not uncommon. Rather than having a single service "own" those types, all services that use them are expected to share ownership. This form of type "duplication" across services is supported for Scalars, Objects, Interfaces, Enums, Unions, and Inputs. The rule of thumb for any of these value types is that the types **must be identical** in name and contents.
 
-Defining the same Enum or Scalar across services is supported **as long as the definitions are all identical**.
+### Objects, Interfaces, and Inputs
+For types with field definitions, all fields _and their types_ must be identical.
 
+### Scalars
+For Scalar values, it's important that services **share the same serialization and parsing logic**, since there is no way to validate that logic from the schema level by federation tooling.
+
+### Enums
 For Enum types, all values must match across services. **Even if a service doesn't use all values in an Enum, they still must be defined in the schema**. Failure to include all enum values in all services that use the Enum will result in a validation error when building the federated schema.
 
-For scalar values, it's important that services **share the same serialization and parsing logic**, since there is no way to validate that logic from the schema level by federation tooling.
+### Unions
+Union types must share the same types in the union, even if not all types are used by a service.
 
-In the following example, the Product and User services both use the same ProductCategory enum and Date scalar.
+In the following example, the Product and User services both use the same `ProductCategory` enum, `Date` scalar, and `UPC` union.
 
 ```graphql
 # Product Service
 scalar Date
 
+union UPC = String | ID
+
 type Product @key(fields: "sku"){
-  sku: ID!
+  sku: UPC!
   category: ProductCategory
   dateCreated: Date
 }
@@ -196,17 +204,24 @@ enum ProductCategory {
 # User Service
 scalar Date
 
+union UPC = String | ID
+
 type User @key(fields: "id"){
   id: ID!
   dateCreated: Date
   favoriteCategory: ProductCategory
+  favoriteProducts: [Product!]
 }
 
 enum ProductCategory {
   FURNITURE
   BOOK
   DIGITAL_DOWNLOAD
 }
+
+extend type Product @key(fields: "sku"){
+  sku: UPC! @external
+}
 ```
 
 

docs/source/federation/errors.md

@@ -49,6 +49,13 @@ Apollo Federation implements a strict composition model. When building a gateway
 - `ROOT_MUTATION_USED`: `Mutation` is disallowed when a schema definition or extension is provided.
 - `ROOT_SUBSCRIPTION_USED`: `Subscription` is disallowed when a schema definition or extension is provided.
 
+### Value Types
+
+- `VALUE_TYPE_FIELD_TYPE_MISMATCH`: Two identical types were found, however one or more of their field's types aren't the same. Value types must be identical across services.
+- `VALUE_TYPE_NO_ENTITY`: Two identical types were found, however it's marked as an entity in one of the services. Extend the type correctly, or make the identical types non-entities.
+- `VALUE_TYPE_UNION_TYPES_MISMATCH`: Two identitical union types were found, however their types are not the same. Shared union types must be identical across services.
+- `VALUE_TYPE_KIND_MISMATCH`: A type was found with the same name and fields, however they aren't of the same kind (object, input, interface). Only value types can be duplicated across services.
+
 ### Modified SDL validations
 
-- Unique Type Names: type definitions can not be duplicated across services, with the exception of Enums and Scalars. This is a modified version of the `graphql-js` validation with exclusions for Enums and Scalars, since those are required to be duplicated across services.
+- Unique Type Names: type definitions can not be duplicated across services, with the exception of Enums, Scalars, and [value types](/core-concepts/#value-types). This is a modified version of the `graphql-js` validation with exclusions for Enums and Scalars, since those are required to be duplicated across services.

package.json

@@ -81,6 +81,7 @@
     "@types/koa-router": "7.0.42",
     "@types/lodash": "4.14.136",
     "@types/lodash.sortby": "4.7.6",
+    "@types/lodash.xorby": "4.7.6",
     "@types/loglevel": "1.5.4",
     "@types/lru-cache": "5.1.0",
     "@types/memcached": "2.2.6",

packages/apollo-federation/package.json

@@ -16,7 +16,8 @@
   "dependencies": {
     "apollo-env": "^0.5.1",
     "apollo-graphql": "^0.3.3",
-    "apollo-server-env": "file:../apollo-server-env"
+    "apollo-server-env": "file:../apollo-server-env",
+    "lodash.xorby": "^4.7.0"
   },
   "peerDependencies": {
     "graphql": "^14.0.2"