Make flattened synthetic source concatenate object keys on scalar/object mismatch

docs/changelog/129600.yaml

@@ -0,0 +1,7 @@
+pr: 129600
+summary: Make flattened synthetic source concatenate object keys on scalar/object
+  mismatch
+area: Mapping
+type: bug
+issues:
+ - 122936

docs/reference/elasticsearch/mapping-reference/flattened.md

@@ -364,3 +364,36 @@ Will become (note the nested objects instead of the "flattened" array):
   }
 }
 ```
+
+Flattened fields allow for a key to contain both an object and a scalar value.
+For example, consider the following flattened field `flattened`:
+
+```console-result
+{
+  "flattened": {
+    "foo.bar": "10",
+    "foo": {
+      "bar": {
+        "baz": "20"
+      }
+    }
+  }
+}
+```
+
+Because `"foo.bar": "10"` is implicitly equivalent to `"foo": { "bar": "10" }`,
+`"bar"` has both a scalar value `"10"`, and an object value of `{ "baz": "20" }`.
+
+With synthetic source, to produce a valid JSON output, objects with such fields will appear differently in `_source`.
+For example, if the field is defined in an index configured with synthetic source, the value of `_source` would be:
+
+```console-result
+{
+  "flattened": {
+    "foo": {
+      "bar": "10",
+      "bar.baz": "20"
+    }
+  }
+}
+```