Update 'removal of types' docs to reflect the new plan. (#38003)

docs/reference/mapping/removal_of_types.asciidoc

@@ -4,7 +4,8 @@
 IMPORTANT: Indices created in Elasticsearch 6.0.0 or later may only contain a
 single <<mapping-type,mapping type>>.  Indices created in 5.x with multiple
 mapping types will continue to function as before in Elasticsearch 6.x.
-Mapping types will be completely removed in Elasticsearch 7.0.0.
+Types will be deprecated in APIs in Elasticsearch 7.0.0, and completely
+removed in 8.0.0.
 
 [float]
 === What are mapping types?
@@ -161,12 +162,12 @@ You can achieve the same thing by adding a custom `type` field as follows:
 
 [source,js]
 ----
-PUT twitter?include_type_name=true <1>
+PUT twitter
 {
   "mappings": {
     "_doc": {
       "properties": {
-        "type": { "type": "keyword" }, <2>
+        "type": { "type": "keyword" }, <1>
         "name": { "type": "text" },
         "user_name": { "type": "keyword" },
         "email": { "type": "keyword" },
@@ -204,7 +205,7 @@ GET twitter/_search
       },
       "filter": {
         "match": {
-          "type": "tweet" <2>
+          "type": "tweet" <1>
         }
       }
     }
@@ -212,9 +213,7 @@ GET twitter/_search
 }
 ----
 // NOTCONSOLE
-<1> Use `include_type_name=true` in case need to use the "old" syntax including the "_doc" object like
-in this example 
-<2> The explicit `type` field takes the place of the implicit `_type` field.
+<1> The explicit `type` field takes the place of the implicit `_type` field.
 
 [float]
 ==== Parent/Child without mapping types
@@ -258,30 +257,28 @@ Elasticsearch 6.x::
 
 * The `_default_` mapping type is deprecated.
 
+* In 6.7, the index creation, index template, and mapping APIs support a query
+  string parameter (`include_type_name`) which indicates whether requests and
+  responses should include a type name. It defaults to `true`, and not setting
+  `include_type_name=false` will result in a deprecation warning. Indices which
+  don't have an explicit type will use the dummy type name `_doc`.
+
 Elasticsearch 7.x::
 
-* The `type` parameter in URLs are deprecated.  For instance, indexing
-  a document no longer requires a document `type`.  The new index APIs
+* Specifying types in requests is deprecated. For instance, indexing a
+  document no longer requires a document `type`.  The new index APIs
   are `PUT {index}/_doc/{id}` in case of explicit ids and `POST {index}/_doc`
   for auto-generated ids.
 
-* The index creation, `GET|PUT _mapping` and document APIs support a query
-  string parameter (`include_type_name`) which indicates whether requests and
-  responses should include a type name. It defaults to `true`.
-  7.x indices which don't have an explicit type will use the dummy type name
-  `_doc`. Not setting `include_type_name=false` will result in a deprecation
-  warning.
+* The `include_type_name` parameter in the index creation, index template,
+  and mapping APIs will default to `false`. Setting the parameter will result
+  in a deprecation warning.
 
 * The `_default_` mapping type is removed.
 
 Elasticsearch 8.x::
 
-* The `type` parameter is no longer supported in URLs.
-
-* The `include_type_name` parameter is deprecated, default to `false` and fails
-  the request when set to `true`.
-
-Elasticsearch 9.x::
+* Specifying types in requests is no longer supported.
 
 * The `include_type_name` parameter is removed.
 
@@ -427,17 +424,26 @@ POST _reindex
 // NOTCONSOLE
 
 [float]
-=== Use `include_type_name=false` to prepare for upgrade to 8.0
+=== Typeless APIs in 7.0
 
-Index creation and mapping APIs support a new `include_type_name` url parameter 
-starting with version 6.7. It will default to `true` in version 6.7, default to
-`false` in version 7.0 and will be removed in version 8.0. When set to `true`, 
-this parameter enables the pre-7.0 behavior of using type names in the API.
+In Elasticsearch 7.0, each API will support typeless requests,
+and specifying a type will produce a deprecation warning.
 
-See some examples of interactions with Elasticsearch with this option turned off:
+NOTE: Typeless APIs work even if the target index contains a custom type.
+For example, if an index has the the custom type name `my_type`, we can add
+documents to it using typeless `index` calls, and load documents with typeless
+`get` calls.
 
 [float]
-==== Index creation
+==== Indices APIs
+
+Index creation, index template, and mapping APIs support a new `include_type_name`
+url parameter that specifies whether mapping definitions in requests and responses
+should contain the type name. The parameter defaults to `true` in version 6.7 to
+match the pre-7.0 behavior of using type names in mappings. It defaults to `false`
+in version 7.0 and will be removed in version 8.0.
+
+See some examples of interactions with Elasticsearch with this option provided:
 
 [source,js]
 --------------------------------------------------
@@ -455,27 +461,27 @@ PUT index?include_type_name=false
 // CONSOLE
 <1> Mappings are included directly under the `mappings` key, without a type name.
 
-[float]
-==== PUT and GET mappings
-
 [source,js]
 --------------------------------------------------
-PUT index
-
 PUT index/_mappings?include_type_name=false
 {
   "properties": { <1>
-    "foo": {
-      "type": "keyword"
+    "bar": {
+      "type": "text"
     }
   }
 }
-
-GET index/_mappings?include_type_name=false
 --------------------------------------------------
 // CONSOLE
+// TEST[continued]
 <1> Mappings are included directly under the `mappings` key, without a type name.
 
+[source,js]
+--------------------------------------------------
+GET index/_mappings?include_type_name=false
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
 
 The above call returns
 
@@ -487,6 +493,9 @@ The above call returns
       "properties": { <1>
         "foo": {
           "type": "keyword"
+        },
+        "bar": {
+          "type": "text"
         }
       }
     }
@@ -499,14 +508,14 @@ The above call returns
 [float]
 ==== Document APIs
 
-Index APIs must be called with the `{index}/_doc` path for automatic generation of
-the `_id` and `{index}/_doc/{id}` with explicit ids.
+In 7.0, index APIs must be called with the `{index}/_doc` path for automatic
+generation of the `_id` and `{index}/_doc/{id}` with explicit ids.
 
 [source,js]
 --------------------------------------------------
 PUT index/_doc/1
 {
-  "foo": "bar"
+  "foo": "baz"
 }
 --------------------------------------------------
 // CONSOLE
@@ -514,7 +523,7 @@ PUT index/_doc/1
 [source,js]
 --------------------------------------------------
 {
-  "_index": "index", <1>
+  "_index": "index",
   "_id": "1",
   "_type": "_doc",
   "_version": 1,
@@ -529,14 +538,98 @@ PUT index/_doc/1
 }
 --------------------------------------------------
 // TESTRESPONSE
-<1> The response does not include a `_type`.
 
-The <<docs-index_,GET>>, <<docs-delete,`DELETE`>>, <<docs-update,`_update`>> and <<search,`_search`>> APIs
-will continue to return a `_type` key in the response in 7.0, but it is considered deprecated and will be
-removed in 8.0.
+Similarly, the `get` and `delete` APIs use the path `{index}/_doc/{id}`:
+
+[source,js]
+--------------------------------------------------
+GET index/_doc/1
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+For API paths that contain both a type and endpoint name like `_update`,
+in 7.0 the endpoint will immediately follow the index name:
+
+[source,js]
+--------------------------------------------------
+POST index/_update/1
+{
+    "doc" : {
+        "foo" : "qux"
+    }
+}
+
+GET /index/_source/1
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+Types should also no longer appear in the body of requests. The following
+example of bulk indexing omits the type both in the URL, and in the individual
+bulk commands:
+
+[source,js]
+--------------------------------------------------
+POST _bulk
+{ "index" : { "_index" : "index", "_id" : "3" } }
+{ "foo" : "baz" }
+{ "index" : { "_index" : "index", "_id" : "4" } }
+{ "foo" : "qux" }
+--------------------------------------------------
+// CONSOLE
+
+[float]
+==== Search APIs
+
+When calling a search API such `_search`, `_msearch`, or `_explain`, types
+should not be included in the URL. Additionally, the `_type` field should not
+be used in queries, aggregations, or scripts.
+
+[float]
+==== Types in responses
+
+The document and search APIs will continue to return a `_type` key in
+responses, to avoid breaks to response parsing. However, the key is
+considered deprecated and should no longer be referenced. Types will
+be completely removed from responses in 8.0.
+
+Note that when a deprecated typed API is used, the index's mapping type will be
+returned as normal, but that typeless APIs will return the dummy type `_doc`
+in the response. For example, the following typeless `get` call will always
+return `_doc` as the type, even if the mapping has a custom type name like
+`my_type`:
+
+[source,js]
+--------------------------------------------------
+PUT index/my_type/1
+{
+  "foo": "baz"
+}
+
+GET index/_doc/1
+--------------------------------------------------
+// CONSOLE
+
+[source,js]
+--------------------------------------------------
+{
+    "_index" : "index",
+    "_type" : "_doc",
+    "_id" : "1",
+    "_version" : 1,
+    "_seq_no" : 0,
+    "_primary_term" : 1,
+    "found": true,
+    "_source" : {
+        "foo" : "baz"
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE
 
 [float]
-=== Index templates
+==== Index templates
 
 It is recommended to make index templates typeless before upgrading to 7.0 by
 re-adding them with `include_type_name` set to `false`.
@@ -608,3 +701,16 @@ In case of implicit index creation, because of documents that get indexed in
 an index that doesn't exist yet, the template is always honored. This is
 usually not a problem due to the fact that typeless index calls work on typed
 indices.
+
+[float]
+==== Mixed-version clusters
+
+In a cluster composed of both 6.7 and 7.0 nodes, the parameter
+`include_type_name` should be specified in indices APIs like index
+creation. This is because the parameter has a different default between
+6.7 and 7.0, so the same mapping definition will not be valid for both
+node versions.
+
+Typeless document APIs such as `bulk` and `update` are only available as of
+7.0, and will not work with 6.7 nodes. This also holds true for the typeless
+versions of queries that perform document lookups, such as `terms`.