Field extensions: spec edits

spec/Section 3 -- Type System.md

@@ -1096,15 +1096,49 @@ Object type extensions have the potential to be invalid if incorrectly defined.
 1. The named type must already be defined and must be an Object type.
 2. The fields of an Object type extension must have unique names; no two fields
    may share the same name.
-3. Any fields of an Object type extension must not be already defined on the
-   previous Object type.
-4. Any non-repeatable directives provided must not already apply to the previous
+3. Any non-repeatable directives provided must not already apply to the previous
    Object type.
-5. Any interfaces provided must not be already implemented by the previous
+4. Any interfaces provided must not be already implemented by the previous
    Object type.
-6. The resulting extended object type must be a super-set of all interfaces it
+5. The resulting extended object type must be a super-set of all interfaces it
    implements.
 
+#### Field Extensions
+
+Field extensions are used to represent a field which has been extended from some
+previously defined field. For example this may be used by a GraphQL service
+which is itself an extension of another GraphQL service. When the same field
+appears in multiple extensions, the properties are merged with later extensions
+taking precedence for conflicting values.
+
+In this example, we can deprecate the field `field` on type `Query` by using a
+field extension:
+
+```graphql example
+type Query {
+  field: String
+}
+```
+
+```graphql example
+extend type Query {
+  field: String @deprecated(reason: "Use newField")
+}
+```
+
+** Type Validation **
+
+Fields have the potential to be invalid if incorrectly defined.
+
+1. The field type must match the previous definition exactly
+2. The default argument definitions may not be changed or removed.
+3. The description may be added if none exists, or must match the existing
+   description exactly
+4. The deprecation reason may be added if none exists, or must match the
+   existing reason exactly
+5. Directives may be added but cannot conflict with existing non-repeatable
+   directives
+
 ## Interfaces
 
 InterfaceTypeDefinition :
@@ -1358,6 +1392,21 @@ defined.
 6. The resulting extended Interface type must be a super-set of all Interfaces
    it implements.
 
+#### Interface Field Extensions
+
+Interface field extensions follow the same rules as Object field extensions and
+are used to extend fields on interface types.
+
+```graphql example
+interface Node {
+  id: ID
+}
+
+extend interface Node {
+  id: ID @deprecated(reason: "Use globalId instead")
+}
+```
+
 ## Unions
 
 UnionTypeDefinition : Description? union Name Directives[Const]?