Rename 'json' to 'embedded_json'. (#40712)

One concern around the name `json` is that because the entire document is JSON,
new users may see this field and think that they should always use it. We
thought that a more verbose name like `embedded_json` would help convey that the
field type has a special, non-obvious purpose.

This commit updates documentation references to `embedded_json`, but leaves the
`JsonField` naming in the code to avoid very long class names.

docs/reference/mapping/types.asciidoc

@@ -44,7 +44,7 @@ string::         <<text,`text`>> and <<keyword,`keyword`>>
 
 <<alias>>::         Defines an alias to an existing field.
 
-<<json>>::          Allows an entire JSON object to be indexed as a single field.
+<<embedded-json>>:: Allows an entire JSON object to be indexed as a single field.
 
 <<rank-feature>>::  Record numeric feature to boost hits at query time.
 
@@ -84,14 +84,14 @@ include::types/date.asciidoc[]
 
 include::types/date_nanos.asciidoc[]
 
+include::types/embedded_json.asciidoc[]
+
 include::types/geo-point.asciidoc[]
 
 include::types/geo-shape.asciidoc[]
 
 include::types/ip.asciidoc[]
 
-include::types/json.asciidoc[]
-
 include::types/keyword.asciidoc[]
 
 include::types/nested.asciidoc[]

docs/reference/mapping/types/json.asciidoc → docs/reference/mapping/types/embedded_json.asciidoc

@@ -1,38 +1,38 @@
-[[json]]
-=== JSON datatype
+[[embedded-json]]
+=== Embedded JSON datatype
 
-experimental[The `json` field type is experimental and may be changed in a breaking way in future releases.]
+experimental[The `embedded_json` field type is experimental and may be changed in a breaking way in future releases.]
 
 By default, each subfield in an object is mapped and indexed separately. If
 the names or types of the subfields are not known in advance, then they are
 <<dynamic-mapping, mapped dynamically>>.
 
-The `json` type provides an alternative approach, where the entire object is
-mapped as a single field. Given an object, the `json` mapping will parse out
+The `embedded_json` type provides an alternative approach, where the entire object is
+mapped as a single field. Given an object, the `embedded_json` mapping will parse out
 its leaf values and index them into one field. The object's contents can then
 be searched through simple keyword-style queries.
 
 This data type can be useful for indexing objects with a very large number of
-distinct keys. Compared to mapping each field separately, `json` fields have
+distinct keys. Compared to mapping each field separately, embedded JSON fields have
 the following advantages:
 
 - Only one field mapping is created for the whole object, which can help
   prevent a <<mapping-limit-settings, mappings explosion>> due to a large
   number of field mappings.
-- A `json` field may take up less space in the index, as only one underlying
+- An embedded JSON field may take up less space in the index, as only one underlying
   field is created.
 
-However, `json` fields present a trade-off in terms of search functionality.
+However, embedded JSON fields present a trade-off in terms of search functionality.
 Only basic queries are allowed, with no support for numeric range queries or
 highlighting. Further information on the limitations can be found in the
 <<supported-operations, Supported operations>> section.
 
-NOTE: The `json` mapping type should **not** be used for indexing all JSON
+NOTE: The `embedded_json` mapping type should **not** be used for indexing all JSON
 content, as it provides only limited search functionality. The default
 approach, where each subfield has its own entry in the mappings, works well in
 the majority of cases.
 
-A `json` field can be created as follows:
+An embedded JSON field can be created as follows:
 [source,js]
 --------------------------------
 PUT bug_reports
@@ -43,7 +43,7 @@ PUT bug_reports
         "type": "text"
       },
       "labels": {
-        "type": "json"
+        "type": "embedded_json"
       }
     }
   }
@@ -69,7 +69,7 @@ During indexing, tokens are created for each leaf value in the JSON object. The
 values are indexed as string keywords, without analysis or special handling for
 numbers or dates.
 
-Querying the top-level `json` field searches all leaf values in the object:
+Querying the top-level `embedded_json` field searches all leaf values in the object:
 [source,js]
 --------------------------------
 POST bug_reports/_search
@@ -96,7 +96,7 @@ POST bug_reports/_search
 [[supported-operations]]
 ==== Supported operations
 
-Currently, `json` fields can be used with the following query types:
+Currently, embedded JSON fields can be used with the following query types:
 
 - `term`, `terms`, and `terms_set`
 - `prefix`
@@ -110,7 +110,7 @@ When querying, it is not possible to refer to field keys using wildcards, as in
 `range`, treat the values as string keywords. Highlighting is not supported on
 `json` fields.
 
-It is possible to sort on a `json` field, as well as perform simple
+It is possible to sort on an embedded JSON field, as well as perform simple
 keyword-style aggregations such as `terms`. As with queries, there is no
 special support for numerics -- all values in the JSON object are treated as
 keywords. When sorting, this implies that values are compared lexicographically.
@@ -123,7 +123,7 @@ character `\0` is not allowed to appear in the keys of the JSON object.
 
 If the <<mapping-store,`store`>> option is enabled, the entire JSON object will
 be stored in pretty-printed format. It can be retrieved through the top-level
-`json` field:
+`embedded_json` field:
 
 [source,js]
 --------------------------------
@@ -141,7 +141,7 @@ Field keys cannot be used to load stored content. For example, specifying
 [[json-params]]
 ==== Parameters for JSON fields
 
-Because of the similarities in the way values are indexed, the `json` type
+Because of the similarities in the way values are indexed, the `embedded_json` type
 shares many mapping options with <<keyword, `keyword`>>. The following
 parameters are accepted:
 

rest-api-spec/src/main/resources/rest-api-spec/test/search/160_exists_query.yml

@@ -1343,7 +1343,7 @@ setup:
             dynamic: false
             properties:
               json:
-                type: json
+                type: embedded_json
   - do:
       index:
         index:  json_test

rest-api-spec/src/main/resources/rest-api-spec/test/search/60_query_string.yml

@@ -75,7 +75,7 @@
           mappings:
             properties:
               headers:
-                type: json
+                type: embedded_json
 
   - do:
       index:

server/src/main/java/org/elasticsearch/index/mapper/JsonFieldMapper.java

@@ -98,7 +98,7 @@
  */
 public final class JsonFieldMapper extends FieldMapper {
 
-    public static final String CONTENT_TYPE = "json";
+    public static final String CONTENT_TYPE = "embedded_json";
     public static final NamedAnalyzer WHITESPACE_ANALYZER = new NamedAnalyzer(
         "whitespace", AnalyzerScope.INDEX, new WhitespaceAnalyzer());
     private static final String KEYED_FIELD_SUFFIX = "._keyed";

server/src/main/java/org/elasticsearch/index/mapper/JsonFieldParser.java

@@ -139,7 +139,7 @@ private void addField(ContentPath path,
 
         String key = path.pathAsText(currentName);
         if (key.contains(SEPARATOR)) {
-            throw new IllegalArgumentException("Keys in [json] fields cannot contain the reserved character \\0."
+            throw new IllegalArgumentException("Keys in [embedded_json] fields cannot contain the reserved character \\0."
                 + " Offending key: [" + key + "].");
         }
         String keyedValue = createKeyedValue(key, value);

server/src/test/java/org/elasticsearch/index/mapper/JsonFieldMapperTests.java

@@ -64,7 +64,7 @@ public void testDefaults() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                     .endObject()
                 .endObject()
             .endObject()
@@ -119,7 +119,7 @@ public void testDisableIndex() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("index", false)
                     .endObject()
                 .endObject()
@@ -151,7 +151,7 @@ public void testDisableDocValues() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("doc_values", false)
                     .endObject()
                 .endObject()
@@ -187,11 +187,11 @@ public void testEnableStore() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("store")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("store", true)
                     .endObject()
                     .startObject("store_only")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("index", false)
                         .field("store", true)
                         .field("doc_values", false)
@@ -241,7 +241,7 @@ public void testIndexOptions() throws IOException {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("index_options", "freqs")
                     .endObject()
                 .endObject()
@@ -256,15 +256,15 @@ public void testIndexOptions() throws IOException {
                 .startObject("type")
                     .startObject("properties")
                         .startObject("field")
-                            .field("type", "json")
+                            .field("type", "embedded_json")
                             .field("index_options", indexOptions)
                         .endObject()
                     .endObject()
                 .endObject()
             .endObject());
             IllegalArgumentException e = expectThrows(IllegalArgumentException.class,
                     () -> parser.parse("type", new CompressedXContent(invalidMapping)));
-            assertEquals("The [json] field does not support positions, got [index_options]=" + indexOptions, e.getMessage());
+            assertEquals("The [embedded_json] field does not support positions, got [index_options]=" + indexOptions, e.getMessage());
         }
     }
 
@@ -273,7 +273,7 @@ public void testNullField() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                     .endObject()
                 .endObject()
             .endObject()
@@ -296,7 +296,7 @@ public void testMalformedJson() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                     .endObject()
                 .endObject()
             .endObject()
@@ -322,7 +322,7 @@ public void testFieldMultiplicity() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                     .endObject()
                 .endObject()
             .endObject()
@@ -363,7 +363,7 @@ public void testDepthLimit() throws IOException {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("depth_limit", 2)
                     .endObject()
                 .endObject()
@@ -392,7 +392,7 @@ public void testEagerGlobalOrdinals() throws IOException {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("eager_global_ordinals", true)
                     .endObject().endObject()
                 .endObject().endObject());
@@ -409,7 +409,7 @@ public void testIgnoreAbove() throws IOException {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("ignore_above", 10)
                     .endObject()
                 .endObject()
@@ -437,10 +437,10 @@ public void testNullValues() throws Exception {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                     .endObject()
                     .startObject("other_field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("null_value", "placeholder")
                     .endObject()
                 .endObject()
@@ -480,7 +480,7 @@ public void testSplitQueriesOnWhitespace() throws IOException {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("split_queries_on_whitespace", true)
                     .endObject()
                 .endObject()

server/src/test/java/org/elasticsearch/index/mapper/JsonFieldParserTests.java

@@ -318,7 +318,7 @@ public void testReservedCharacters() throws Exception {
         XContentParser xContentParser = createXContentParser(input.utf8ToString());
 
         IllegalArgumentException e = expectThrows(IllegalArgumentException.class, () -> parser.parse(xContentParser));
-        assertEquals("Keys in [json] fields cannot contain the reserved character \\0. Offending key: [k\0y].",
+        assertEquals("Keys in [embedded_json] fields cannot contain the reserved character \\0. Offending key: [k\0y].",
             e.getMessage());
     }
 

server/src/test/java/org/elasticsearch/index/mapper/KeyedJsonFieldTypeTests.java

@@ -117,7 +117,7 @@ public void testFuzzyQuery() {
 
         UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
             () -> ft.fuzzyQuery("valuee", Fuzziness.fromEdits(2), 1, 50, true));
-        assertEquals("[fuzzy] queries are not currently supported on [json] fields.", e.getMessage());
+        assertEquals("[fuzzy] queries are not currently supported on [embedded_json] fields.", e.getMessage());
     }
 
     public void testRangeQuery() {
@@ -136,12 +136,12 @@ public void testRangeQuery() {
 
         IllegalArgumentException e = expectThrows(IllegalArgumentException.class, () ->
             ft.rangeQuery("lower", null, false, false, null));
-        assertEquals("[range] queries on keyed [json] fields must include both an upper and a lower bound.",
+        assertEquals("[range] queries on keyed [embedded_json] fields must include both an upper and a lower bound.",
             e.getMessage());
 
         e = expectThrows(IllegalArgumentException.class, () ->
             ft.rangeQuery(null, "upper", false, false, null));
-        assertEquals("[range] queries on keyed [json] fields must include both an upper and a lower bound.",
+        assertEquals("[range] queries on keyed [embedded_json] fields must include both an upper and a lower bound.",
             e.getMessage());
     }
 
@@ -151,7 +151,7 @@ public void testRegexpQuery() {
 
         UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
             () -> ft.regexpQuery("valu*", 0, 10, null, null));
-        assertEquals("[regexp] queries are not currently supported on [json] fields.", e.getMessage());
+        assertEquals("[regexp] queries are not currently supported on [embedded_json] fields.", e.getMessage());
     }
 
     public void testWildcardQuery() {
@@ -160,6 +160,6 @@ public void testWildcardQuery() {
 
         UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
             () -> ft.wildcardQuery("valu*", null, null));
-        assertEquals("[wildcard] queries are not currently supported on [json] fields.", e.getMessage());
+        assertEquals("[wildcard] queries are not currently supported on [embedded_json] fields.", e.getMessage());
     }
 }

server/src/test/java/org/elasticsearch/index/mapper/RootJsonFieldTypeTests.java

@@ -85,7 +85,7 @@ public void testFuzzyQuery() {
 
         UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
             () -> ft.fuzzyQuery("valuee", Fuzziness.fromEdits(2), 1, 50, true));
-        assertEquals("[fuzzy] queries are not currently supported on [json] fields.", e.getMessage());
+        assertEquals("[fuzzy] queries are not currently supported on [embedded_json] fields.", e.getMessage());
     }
 
     public void testRangeQuery() {
@@ -109,7 +109,7 @@ public void testRegexpQuery() {
 
         UnsupportedOperationException e  = expectThrows(UnsupportedOperationException.class,
             () -> ft.regexpQuery("valu*", 0, 10, null, null));
-        assertEquals("[regexp] queries are not currently supported on [json] fields.", e.getMessage());
+        assertEquals("[regexp] queries are not currently supported on [embedded_json] fields.", e.getMessage());
     }
 
     public void testWildcardQuery() {
@@ -118,6 +118,6 @@ public void testWildcardQuery() {
 
         UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
             () -> ft.wildcardQuery("valu*", null, null));
-        assertEquals("[wildcard] queries are not currently supported on [json] fields.", e.getMessage());
+        assertEquals("[wildcard] queries are not currently supported on [embedded_json] fields.", e.getMessage());
     }
 }

server/src/test/java/org/elasticsearch/index/search/MultiMatchQueryTests.java

@@ -343,10 +343,10 @@ public void testJsonSplitQueriesOnWhitespace() throws IOException {
             .startObject("type")
                 .startObject("properties")
                     .startObject("field")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                     .endObject()
                     .startObject("field_split")
-                        .field("type", "json")
+                        .field("type", "embedded_json")
                         .field("split_queries_on_whitespace", true)
                     .endObject()
                 .endObject()