implement PR suggestions

- move schema coordinates to section 3.3.3
- add lee's grammar suggestion

Author: magicmark

spec/Appendix C -- Schema Coordinates.md

@@ -127,5 +127,3 @@ Note: This is an example of a non-normative note.
 # [Appendix: Notation Conventions](Appendix%20A%20--%20Notation%20Conventions.md)
 
 # [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md)
-
-# [Appendix: Schema Coordinates](Appendix%20C%20--%20Schema%20Coordinates.md)

spec/GraphQL.md

@@ -251,6 +251,152 @@ Schema extensions have the potential to be invalid if incorrectly defined.
 2. Any non-repeatable directives provided must not already apply to the
    original Schema.
 
+### Schema Coordinates
+
+Schema Coordinates are human readable strings that uniquely identify an element defined in a GraphQL Schema.
+
+**Definition**
+
+SchemaCoordinate:
+  - Name
+  - Name . Name
+  - Name . Name ( Name : )
+  - @ Name
+  - @ Name ( Name : )
+
+**Semantics**
+
+SchemaCoordinate: Name
+  1. Let {typeName} be the value of the first {Name}.
+  2. Return the type in the schema named {typeName}.
+
+SchemaCoordinate: Name . Name
+  1. Let {typeName} be the value of the first {Name}.
+  2. Let {type} be the type in the schema named {typeName}.
+  3. If {type} is an Enum type:
+    1. Let {enumName} be the value of the second {Name}.
+    2. Return the enum value of {type} named {enumName}.
+  4. Otherwise if {type} is an Input Object type:
+    1. Let {inputFieldName} be the value of the second {Name}.
+    2. Return the input field of {type} named {inputFieldName}.
+  5. Otherwise {type} must be an Object or Interface type:
+    1. Let {fieldName} be the value of the second {Name}.
+    2. Return the field of {type} named {fieldName}.
+  
+SchemaCoordinate: Name . Name ( Name : )
+  1. Let {typeName} be the value of the first {Name}.
+  2. Let {type} be the type in the schema named {typeName}.
+  3. Assert: {type} must be an Object or Interface type.
+  4. Let {fieldName} be the value of the second {Name}.
+  5. Let {field} be the field of {type} named {fieldName}.
+  6. Assert: {field} must exist.
+  7. Let {argumentName} be the value of the third {Name}.
+  8. Return the argument of {field} named {argumentName}.
+
+SchemaCoordinate: @ Name
+  1. Let {directiveName} be the value of the first {Name}.
+  2. Return the directive in the schema named {directiveName}.
+
+SchemaCoordinate: @ Name ( Name : )
+  1. Let {directiveName} be the value of the first {Name}.
+  2. Let {directive} be the directive in the schema named {directiveName}.
+  3. Assert: {directive} must exist.
+  7. Let {argumentName} be the value of the second {Name}.
+  8. Return the argument of {directive} named {argumentName}
+
+**Examples**
+
+This section shows example coordinates for the possible schema element types this syntax covers.
+
+All examples below will assume the following schema:
+
+```graphql example
+directive @private(scope: String!) on FIELD
+
+scalar DateTime
+
+input ReviewInput {
+  content: String
+  author: String
+  businessId: String
+}
+
+interface Address {
+    city: String
+}
+
+type User implements Address {
+    name: String
+    reviewCount: Int
+    friends: [User]
+    email: String @private(scope: "loggedIn")
+    city: String
+}
+
+type Business implements Address {
+    name: String
+    address: String
+    rating: Int
+    city: String
+    reviews: [Review]
+    createdAt: DateTime
+}
+
+type Review {
+    content: String
+    author: User
+    business: Business
+    createdAt: DateTime
+}
+
+union Entity = User | Business | Review
+
+enum SearchFilter {
+    OPEN_NOW
+    DELIVERS_TAKEOUT
+    VEGETARIAN_MENU
+}
+
+type Query {
+    searchBusiness(name: String!, filter: SearchFilter): Business
+}
+
+type Mutation {
+    addReview(input: ReviewInput!): Review
+}
+```
+
+The following table demonstrates how to select various kinds of schema elements:
+
+|  Example                       | Description                                                         |
+| ------------------------------ | ------------------------------------------------------------------- |
+| `Business`                     | `Business` type                                                     |
+| `User`                         | `User` type                                                         |
+| `Business.name`                | `name` field on the `Business` type                                 |
+| `User.name`                    | `name` field on the `User` type                                     |
+| `Query.searchBusiness(name:)`  | `name` argument on the `searchBusiness` field on the `Query` type   |
+| `Query.searchBusiness(filter:)`| `filter` argument on the `searchBusiness` field on the `Query` type |
+| `SearchFilter`                 | `SearchFilter` enum                                                 |
+| `SearchFilter.OPEN_NOW`        | `OPEN_NOW` value of the`SearchFilter` enum                          |
+| `@private`                     | `@private` directive definition                                     |
+| `@private(scope:)`             | `scope` argument on the `@private` directive definition             |
+| `Address`                      | `Address` interface                                                 |
+| `Address.city`                 | `city` field on the `Address` interface                             |
+| `ReviewInput`                  | `ReviewInput` input object type                                     |
+| `ReviewInput.author`           | `author` field on the `ReviewInput` input object type               |
+| `Entity`                       | `Entity` union definition                                           |
+| `DateTime`                     | Custom `DateTime` scalar type                                       |
+| `String`                       | Built-in `String` scalar type                                       |
+
+Note: You may not select members inside a union definition.
+
+The following counter example is *not* considered a valid Schema Coordinate:
+
+```graphql counter-example
+Entity.Business
+```
+
+In such cases, you may wish to select the type directly instead (e.g. `Business`).
 
 ## Types