Introduce Lookup Directive.

spec/Section 2 -- Source Schema.md

@@ -2,59 +2,120 @@
 
 ## 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
+  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
+extend 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
+  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
+  entityById(id: ID!, categoryId: Int): Entity @lookup
 }
 
 union Entity = Cat | Dog
 
-extend type Dog {
+extend type Dog @key(fields "id categoryId") {
   id: ID!
   categoryId: Int
 }
 
-extend type Cat {
+extend 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
+extend type Query {
+  entityById(id: ID!, categoryId: Int): Entity @lookup
+}
+
+union Entity = Cat | Dog
+
+extend type Dog @key(fields "id categoryId") {
   id: ID!
   categoryId: Int
 }
+
+extend 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
+extend type Query {
+  lookups: Lookups!
+}
+
+type Lookups {
+  personById(id: ID!): Person @lookup
+}
+
+extend type Person @key(fields "id") {
+  id: ID!
+}
 ```
 
 ### @is