Introduce Lookup Directive.

spec/Section 2 -- Source Schema.md

@@ -2,61 +2,139 @@
 
 ## Directives
 
-### @entityResolver
+### @lookup
 
 ```graphql
-directive @entityResolver on FIELD_DEFINITION
+directive @lookup on FIELD_DEFINITION
 ```
 
-Entity resolvers are fields on the query root type of a subgraph that can
-resolve an entity by a stable key. The stable key is defined by the arguments of
-the field.
+The `@lookup` directive is used within a _source schema_ to specify object
+fields that can be used by the _distributed GraphQL executor_ to resolve an
+entity by a stable key.
+
+The stable key is defined by the arguments of the field. Only fields that are
+annotated with the `@lookup` directive will be recognized as lookup field.
+
+Source schemas can provide multiple lookup fields for the same entity with
+different keys.
+
+In this example the source schema specifies that the `Person` entity can be
+resolved with the `personById` field or the `personByName` field on the `Query`
+type. Both fields can resolve the same entity but do so with different keys.
 
 ```graphql example
-extend type Query {
-  version: Int # NOT an entity resolver.
-  personById(id: ID!): Person @entityResolver
+type Query {
+  version: Int # NOT a lookup field.
+  personById(id: ID!): Person @lookup
+  personByName(name: String!): Person @lookup
 }
 
-extend type Person {
-  id: ID! # matches the argument of personById
+type Person @key(fields: "id") @key(fields: "name") {
+  id: ID!
+  name: String!
 }
 ```
 
-The arguments of an entity resolver field must match fields of the returning
-type.
+The arguments of a lookup field must correspond to fields specified by a `@key`
+directive annotated on the return type of the lookup field.
 
 ```graphql example
-extend type Query {
-  node(id: ID!): Node @entityResolver
+type Query {
+  node(id: ID!): Node @lookup
 }
 
-interface Node {
+interface Node @key(fields: "id") {
   id: ID!
 }
 ```
 
-When an entity resolver returns an interface all implementing types are inferred
-as entities.
+Lookup fields may return object, interface or union types. In case a lookup
+field returns an interface or union type all possible object types are
+considered entities and must have keys that correspond with the fields argument
+signature.
 
 ```graphql example
-extend type Query {
-  entityById(id: ID!, categoryId: Int): Entity @entityResolver
+type Query {
+  entityById(id: ID!, categoryId: Int): Entity @lookup
 }
 
 union Entity = Cat | Dog
 
-extend type Dog {
+type Dog @key(fields: "id categoryId") {
   id: ID!
   categoryId: Int
 }
 
-extend type Cat {
+type Cat @key(fields: "id categoryId") {
   id: ID!
   categoryId: Int
 }
 ```
 
+The following example shows an invalid lookup field as the `Cat` type does not
+declare a key that corresponds with the lookup fields argument signature.
+
+```graphql counter-example
+type Query {
+  entityById(id: ID!, categoryId: Int): Entity @lookup
+}
+
+union Entity = Cat | Dog
+
+type Dog @key(fields: "id categoryId") {
+  id: ID!
+  categoryId: Int
+}
+
+type Cat @key(fields: "id") {
+  id: ID!
+}
+```
+
+If the lookup returns an interface in particular the interface must also be
+annotated with a `@key` directive.
+
+```graphql example
+interface Node @key(fields: "id") {
+  id: ID!
+}
+```
+
+Lookup fields must be accessible from the Query type. If not directly on the
+Query type, they must be accessible via fields that do not require arguments,
+starting from the Query root type.
+
+```graphql example
+type Query {
+  lookups: Lookups!
+}
+
+type Lookups {
+  personById(id: ID!): Person @lookup
+}
+
+type Person @key(fields: "id") {
+  id: ID!
+}
+```
+
+Lookups can also be nested if they can be reached through other lookups.
+
+```graphql example
+type Query {
+  organization(id: ID!): Ogranization @lookup
+}
+
+type Ogranization {
+  repository(name: String!): Repository @lookup
+}
+
+type Repository @key(fields: "id organization { id }") {
+  name: String!
+  organization: Ogranization
+}
+```
+
 ### @is
 
 ```graphql
@@ -77,15 +155,15 @@ resolver for `Person` from the field `Query.personById`.
 
 ```graphql example
 extend type Query {
-  personById(id: ID! @is(field: "id")): Person @entityResolver
+  personById(id: ID! @is(field: "id")): Person @lookup
 }
 ```
 
 The `@is` directive also allows to refer to nested fields relative to `Person`.
 
 ```graphql example
 extend type Query {
-  personByAddressId(id: ID! @is(field: "address { id }")): Person
+  personByAddressId(id: ID! @is(field: "address.id")): Person
 }
 ```
 
@@ -94,43 +172,15 @@ The `@is` directive not limited to a single argument.
 ```graphql example
 extend type Query {
   personByAddressId(
-    id: ID! @is(field: "address { id }")
+    id: ID! @is(field: "address.id")
     kind: PersonKind @is(field: "kind")
   ): Person
 }
 ```
 
-The directive can also establish semantic equivalence between two output fields.
-In this example, the field `productSKU` is semantically equivalent to the field
-`Product.sku`, allowing the schema composition to infer the connection of the
-`Product` with the `Review` type.
-
-```graphql example
-extend type Review {
-  productSKU: ID! @is(coordinate: "Product.sku") @internal
-  product: Product @resolve
-}
-```
-
-The `@is` directive can use either the `field` or `coordinate` argument. If both
-are specified, the schema composition must fail.
-
-```graphql counter-example
-extend type Review {
-  productSKU: ID!
-    @is(coordinate: "Product.sku", field: "product { sku }")
-    @internal
-  product: Product @resolve
-}
-```
-
 **Arguments:**
 
-- `field`: Represents a GraphQL field selection syntax that refers to field
-  relative to the current type; or, when used on arguments it refers to a field
-  relative to the return type.
-- `coordinate`: Represents a schema coordinate that refers to a type system
-  member.
+- `field`: Represents a selection path syntax.
 
 ### @shareable
 
@@ -170,8 +220,8 @@ type Product {
   id: ID!
   delivery(
     zip: String!
-    size: Int! @require(field: "dimension { size }")
-    weight: Int! @require(field: "dimension { weight }")
+    size: Int! @require(field: "dimension.size")
+    weight: Int! @require(field: "dimension.weight")
   ): DeliveryEstimates
 }
 ```
@@ -190,6 +240,30 @@ type Product {
 }
 ```
 
+If the input types do not match it can also be mapped with the path selection
+syntax.
+
+```graphql example
+type Product {
+  id: ID!
+  delivery(
+    zip: String!
+    dimension: ProductDimensionInput!
+      @require(field: "{ productSize: dimension.size, productWeight: dimension.weight }"))
+  ): DeliveryEstimates
+}
+
+type ProductDimension {
+  size: Int!
+  weight: Int!
+}
+
+input ProductDimensionInput {
+  productSize: Int!
+  productWeight: Int!
+}
+```
+
 ### @provides
 
 ```graphql
@@ -226,19 +300,3 @@ directive @internal on OBJECT | INTERFACE | FIELD_DEFINITION | UNION | ENUM | EN
 The `@internal` directive signals to the composition process that annotated type
 system members shall not be included into the public schema but still can be
 used by the executor to build resolvers.
-
-### Schemacoordinate
-
-```graphql
-scalar Schemacoordinate
-```
-
-The `Schemacoordinate` scalar represents a schema coordinate syntax.
-
-```graphql example
-Product.id
-```
-
-```graphql example
-Product.estimateDelivery(zip:)
-```