Expand @deprecated to Objects

spec/Section 3 -- Type System.md

@@ -2057,7 +2057,7 @@ condition is false.
 ```graphql
 directive @deprecated(
   reason: String = "No longer supported"
-) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
+) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE | OBJECT
 ```
 
 The `@deprecated` _built-in directive_ is used within the type system definition
@@ -2098,6 +2098,36 @@ type ExampleType {
 To deprecate a required argument or input field, it must first be made optional
 by either changing the type to nullable or adding a default value.
 
+The `@deprecated` directive is useful for object types that are included in
+unions or interfaces. Deprecating the type indicates to clients that the server
+will no longer be returning this type and clients should remove references to
+this type in their queries.
+
+```graphql example
+type Query {
+  returnsUnion: MyUnion
+}
+
+union MyUnion = ExampleType | DeprecatedType
+
+type DeprecatedType @deprecated {
+  id: ID
+}
+```
+
+The `@deprecated` directive should not appear on object types that are
+referenced by non-deprecated fields.
+
+```graphql counter-example
+type Query {
+  returnsDeprecatedType: DeprecatedType
+}
+
+type DeprecatedType @deprecated {
+  id: ID
+}
+```
+
 ### @specifiedBy
 
 ```graphql

spec/Section 4 -- Introspection.md

@@ -109,9 +109,9 @@ CommonMark-compliant Markdown renderer.
 **Deprecation**
 
 To support the management of backwards compatibility, GraphQL fields, arguments,
-input fields, and enum values can indicate whether or not they are deprecated
-(`isDeprecated: Boolean`) along with a description of why it is deprecated
-(`deprecationReason: String`).
+input fields, enum values, and objects can indicate whether or not they are
+deprecated (`isDeprecated: Boolean`) along with a description of why it is
+deprecated (`deprecationReason: String`).
 
 Tools built using GraphQL introspection should respect deprecation by
 discouraging deprecated use through information hiding or developer-facing
@@ -126,7 +126,7 @@ which are fully defined in the sections below.
 ```graphql
 type __Schema {
   description: String
-  types: [__Type!]!
+  types(includeDeprecated: Boolean = false): [__Type!]!
   queryType: __Type!
   mutationType: __Type
   subscriptionType: __Type
@@ -142,7 +142,7 @@ type __Type {
   # must be non-null for OBJECT and INTERFACE, otherwise null.
   interfaces: [__Type!]
   # must be non-null for INTERFACE and UNION, otherwise null.
-  possibleTypes: [__Type!]
+  possibleTypes(includeDeprecated: Boolean = false): [__Type!]
   # must be non-null for ENUM, otherwise null.
   enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
   # must be non-null for INPUT_OBJECT, otherwise null.
@@ -151,6 +151,8 @@ type __Type {
   ofType: __Type
   # may be non-null for custom SCALAR, otherwise null.
   specifiedByURL: String
+  isDeprecated: Boolean!
+  deprecationReason: String
 }
 
 enum __TypeKind {
@@ -236,6 +238,8 @@ Fields\:
 - `types` must return the set of all named types contained within this schema.
   Any named type which can be found through a field of any introspection type
   must be included in this set.
+  - Accepts the argument `includeDeprecated` which defaults to {false}. If
+    {true}, deprecated fields are also returned.
 - `directives` must return the set of all directives available within this
   schema including all built-in directives.
 
@@ -311,6 +315,8 @@ Fields\:
 - `description` may return a String or {null}.
 - `possibleTypes` returns the list of types that can be represented within this
   union. They must be object types.
+  - Accepts the argument `includeDeprecated` which defaults to {false}. If
+    {true}, deprecated fields are also returned.
 - All other fields must return {null}.
 
 **Interface**
@@ -332,6 +338,8 @@ Fields\:
   (if none, `interfaces` must return the empty set).
 - `possibleTypes` returns the list of types that implement this interface. They
   must be object types.
+  - Accepts the argument `includeDeprecated` which defaults to {false}. If
+    {true}, deprecated fields are also returned.
 - All other fields must return {null}.
 
 **Enum**