Update the docs and deprecation info API.

Author: jtibshirani

docs/reference/migration/migrate_7_2.asciidoc

@@ -29,3 +29,16 @@ In earlier versions you could include a range of ports in entries in the
 unexpectedly ignored the rest.  For instance if you set `discovery.seed_hosts:
 "10.11.12.13:9300-9310"` then {es} would only use `10.11.12.13:9300` for
 discovery. Seed host addresses containing port ranges are now rejected.
+
+[[breaking_72_mapping_changes]]
+=== Mapping changes
+
+[float]
+==== Defining multi-fields within multi-fields
+
+Previously, it was possible to define a multi-field within a multi-field.
+Defining chained multi-fields is now deprecated and will no longer be supported
+in 8.0. To resolve the issue, all instances of `fields` that occur within a
+`fields` block should be removed from the mappings, either by flattening the
+chained `fields` blocks into a single level, or by switching to `copy_to` if
+appropriate.

x-pack/plugin/deprecation/src/main/java/org/elasticsearch/xpack/deprecation/DeprecationChecks.java

@@ -47,7 +47,8 @@ private DeprecationChecks() {
     static List<Function<IndexMetaData, DeprecationIssue>> INDEX_SETTINGS_CHECKS =
         Collections.unmodifiableList(Arrays.asList(
             IndexDeprecationChecks::oldIndicesCheck,
-            IndexDeprecationChecks::tooManyFieldsCheck
+            IndexDeprecationChecks::tooManyFieldsCheck,
+            IndexDeprecationChecks::chainedMultiFieldsCheck
         ));
 
     static List<BiFunction<DatafeedConfig, NamedXContentRegistry, DeprecationIssue>> ML_SETTINGS_CHECKS =

x-pack/plugin/deprecation/src/main/java/org/elasticsearch/xpack/deprecation/IndexDeprecationChecks.java

@@ -115,6 +115,32 @@ static DeprecationIssue tooManyFieldsCheck(IndexMetaData indexMetaData) {
         return null;
     }
 
+    static DeprecationIssue chainedMultiFieldsCheck(IndexMetaData indexMetaData) {
+        List<String> issues = new ArrayList<>();
+        fieldLevelMappingIssue(indexMetaData, ((mappingMetaData, sourceAsMap) -> issues.addAll(
+            findInPropertiesRecursively(mappingMetaData.type(), sourceAsMap, IndexDeprecationChecks::containsChainedMultiFields))));
+        if (issues.size() > 0) {
+            return new DeprecationIssue(DeprecationIssue.Level.CRITICAL,
+                "Multi-fields within multi-fields",
+                "https://www.elastic.co/guide/en/elasticsearch/reference/7.2/breaking-changes-7.2.html" +
+                    "#_defining_multi_fields_within_multi_fields",
+                "The names of fields that contain chained multi-fields: " + issues.toString());
+        }
+        return null;
+    }
+
+    private static boolean containsChainedMultiFields(Map<?, ?> property) {
+        if (property.containsKey("fields")) {
+            Map<?, ?> fields = (Map<?, ?>) property.get("fields");
+            for (Object rawSubField: fields.values()) {
+                Map<?, ?> subField = (Map<?, ?>) rawSubField;
+                if (subField.containsKey("fields")) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
 
     private static final Set<String> TYPES_THAT_DONT_COUNT;
     static {

x-pack/plugin/deprecation/src/test/java/org/elasticsearch/xpack/deprecation/IndexDeprecationChecksTests.java

@@ -9,7 +9,9 @@
 import org.elasticsearch.Version;
 import org.elasticsearch.cluster.metadata.IndexMetaData;
 import org.elasticsearch.common.Strings;
+import org.elasticsearch.common.bytes.BytesReference;
 import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.common.xcontent.XContentFactory;
 import org.elasticsearch.index.IndexSettings;
 import org.elasticsearch.test.ESTestCase;
 import org.elasticsearch.test.VersionUtils;
@@ -110,6 +112,43 @@ public void testTooManyFieldsCheck() throws IOException {
         assertEquals(0, withDefaultFieldIssues.size());
     }
 
+    public void testChainedMultiFields() throws IOException {
+        XContentBuilder xContent = XContentFactory.jsonBuilder().startObject()
+            .startObject("properties")
+                .startObject("field")
+                    .field("type", "keyword")
+                    .startObject("fields")
+                        .startObject("sub-field")
+                            .field("type", "keyword")
+                            .startObject("fields")
+                                .startObject("sub-sub-field")
+                                    .field("type", "keyword")
+                                .endObject()
+                            .endObject()
+                        .endObject()
+                    .endObject()
+                .endObject()
+            .endObject()
+        .endObject();
+        String mapping = BytesReference.bytes(xContent).utf8ToString();
+
+        IndexMetaData simpleIndex = IndexMetaData.builder(randomAlphaOfLengthBetween(5, 10))
+            .settings(settings(Version.V_7_2_0))
+            .numberOfShards(1)
+            .numberOfReplicas(1)
+            .putMapping("_doc", mapping)
+            .build();
+        List<DeprecationIssue> issues = DeprecationChecks.filterChecks(INDEX_SETTINGS_CHECKS, c -> c.apply(simpleIndex));
+        assertEquals(1, issues.size());
+
+        DeprecationIssue expected = new DeprecationIssue(DeprecationIssue.Level.CRITICAL,
+            "Multi-fields within multi-fields",
+            "https://www.elastic.co/guide/en/elasticsearch/reference/7.2/breaking-changes-7.2.html" +
+                "#_defining_multi_fields_within_multi_fields",
+            "The names of fields that contain chained multi-fields: [[type: _doc, field: field]]");
+        assertEquals(singletonList(expected), issues);
+    }
+
     static void addRandomFields(final int fieldLimit,
                                 XContentBuilder mappingBuilder) throws IOException {
         AtomicInteger fieldCount = new AtomicInteger(0);