Add guide instructions

Signed-off-by: Thomas Farr <tsfarr@amazon.com>

guides/json.md

@@ -55,6 +55,22 @@ private String toJson(JsonpSerializable object) {
 }
 ```
 
+### Disabling Typed Keys Serialization
+By default, the JSON serialization of the OpenSearch Java client uses typed keys for certain types, notably Aggregations.
+This is done for the benefit of unambiguous deserialization, but may result in JSON output that is incompatible with use-cases expecting OpenSearch's default untyped keys.
+You may disable this behavior by setting the `JsonpMapperAttributes.SERIALIZE_TYPED_KEYS` attribute to `false` on a JsonpMapper instance.
+For example, the following code demonstrates how to serialize a SearchResponse without typed keys:
+```java
+private String withoutTypedKeys(OpenSearchClient client, SearchResponse response) {
+    JsonpMapper mapper = client._transport().jsonpMapper().withAttribute(JsonpMapperAttributes.SERIALIZE_TYPED_KEYS, false);
+    StringWriter writer = new StringWriter();
+    try (JsonGenerator generator = mapper.jsonProvider().createGenerator(writer)) {
+        response.serialize(generator, mapper);
+    }
+    return writer.toString();
+}
+```
+
 ## Deserialization
 
 For demonstration let's consider an IndexTemplateMapping JSON String.

java-client/src/main/java/org/opensearch/client/json/JsonpMapper.java

@@ -93,7 +93,7 @@ default <T> T attribute(String name, T defaultValue) {
      *           See {@link org.opensearch.client.json.jsonb.JsonbJsonpMapper#withAttribute(String, Object)} and {@link org.opensearch.client.json.jackson.JacksonJsonpMapper#withAttribute(String, Object)} for examples.
      */
     default <T> JsonpMapper withAttribute(String name, T value) {
-        //noinspection deprecation
+        // noinspection deprecation
         return new AttributedJsonpMapper(this, name, value);
     }
 }

java-client/src/main/java/org/opensearch/client/json/JsonpMapperAttributes.java

@@ -1,8 +1,15 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
 package org.opensearch.client.json;
 
 public final class JsonpMapperAttributes {
-    private JsonpMapperAttributes() {
-    }
+    private JsonpMapperAttributes() {}
 
     public static final String SERIALIZE_TYPED_KEYS = JsonpMapperAttributes.class.getName() + ":SERIALIZE_TYPED_KEYS";
 }

java-client/src/main/java/org/opensearch/client/json/JsonpMapperBase.java

@@ -45,16 +45,15 @@ public abstract class JsonpMapperBase implements JsonpMapper {
     @Nullable
     private Map<String, Object> attributes;
 
-    protected JsonpMapperBase() {
-    }
+    protected JsonpMapperBase() {}
 
     protected JsonpMapperBase(JsonpMapperBase o) {
         this.attributes = o.attributes; // We always copy in `setAttribute` so no need to copy here.
     }
 
     @Override
     public <T> T attribute(String name) {
-        //noinspection unchecked
+        // noinspection unchecked
         return attributes == null ? null : (T) attributes.get(name);
     }
 

java-client/src/test/java/org/opensearch/client/opensearch/model/TypedKeysTest.java

@@ -32,10 +32,9 @@
 
 package org.opensearch.client.opensearch.model;
 
+import com.fasterxml.jackson.databind.node.ObjectNode;
 import java.util.ArrayList;
 import java.util.Collections;
-
-import com.fasterxml.jackson.databind.node.ObjectNode;
 import org.junit.Test;
 import org.opensearch.client.json.JsonpDeserializer;
 import org.opensearch.client.json.JsonpMapperAttributes;
@@ -120,15 +119,13 @@ public void testAdditionalProperties() {
 
     @Test
     public void testDisablingSerializeTypedKeys() {
-        SearchResponse<ObjectNode> resp = new SearchResponse.Builder<ObjectNode>()
-                .aggregations("aggKey", v -> v.lterms(lv -> lv.buckets(b -> b.array(new ArrayList<>())).sumOtherDocCount(0)))
-                .took(0)
-                .timedOut(false)
-                .shards(s -> s.failed(0).successful(1).total(1))
-                .hits(h -> h.hits(new ArrayList<>()))
-                .build();
-
-        String json = "{\"took\":0,\"timed_out\":false,\"_shards\":{\"failed\":0,\"successful\":1,\"total\":1},\"hits\":{\"hits\":[]},\"aggregations\":{\"aggKey\":{\"buckets\":[],\"sum_other_doc_count\":0}}}";
+        SearchResponse<ObjectNode> resp = new SearchResponse.Builder<ObjectNode>().aggregations(
+            "aggKey",
+            v -> v.lterms(lv -> lv.buckets(b -> b.array(new ArrayList<>())).sumOtherDocCount(0))
+        ).took(0).timedOut(false).shards(s -> s.failed(0).successful(1).total(1)).hits(h -> h.hits(new ArrayList<>())).build();
+
+        String json =
+            "{\"took\":0,\"timed_out\":false,\"_shards\":{\"failed\":0,\"successful\":1,\"total\":1},\"hits\":{\"hits\":[]},\"aggregations\":{\"aggKey\":{\"buckets\":[],\"sum_other_doc_count\":0}}}";
 
         assertEquals(json, toJson(resp, mapper.withAttribute(JsonpMapperAttributes.SERIALIZE_TYPED_KEYS, false)));
     }