[FLINK-37175][docs] Complement documentation for json function

docs/data/sql_functions.yml

@@ -1086,8 +1086,8 @@ json:
       This function can currently only be used within the `JSON_OBJECT` function. It allows passing 
       pre-formatted JSON strings that will be inserted directly into the resulting JSON structure 
       rather than being escaped as a string value. This allows storing nested JSON structures in a 
-      JSON_OBJECT without processing them as strings. If the value is NULL or empty, the function 
-      returns NULL.
+      JSON_OBJECT without processing them as strings, which is often useful when ingesting already 
+      formatted json data. If the value is NULL or empty, the function returns NULL.
 
       ```sql
       -- {"K":{"K2":42}}

flink-python/pyflink/table/expressions.py

@@ -778,7 +778,8 @@ def json(value) -> Expression:
     This function can currently only be used within the `JSON_OBJECT` function. It allows passing
     pre-formatted JSON strings that will be inserted directly into the resulting JSON structure
     rather than being escaped as a string value. This allows storing nested JSON structures in a
-    JSON_OBJECT without processing them as strings. If the value is NULL or empty, the function
+    JSON_OBJECT without processing them as strings, which is often useful when ingesting already
+    formatted json data. If the value is NULL or empty, the function
     returns NULL.
 
     Examples:

flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Expressions.java

@@ -885,8 +885,9 @@ public static ApiExpression jsonObject(JsonOnNull onNull, Object... keyValues) {
      * <p>This function can currently only be used within the {@link #jsonObject(JsonOnNull,
      * Object...)} function. It allows passing pre-formatted JSON strings that will be inserted
      * directly into the resulting JSON structure rather than being escaped as a string value. This
-     * allows storing nested JSON structures in a JSON_OBJECT without processing them as strings. If
-     * the value is null or empty, the function returns {@code null}.
+     * allows storing nested JSON structures in a JSON_OBJECT without processing them as strings,
+     * which is often useful when ingesting already formatted json data. If the value is null or
+     * empty, the function returns {@code null}.
      *
      * <p>Examples:
      *

flink-table/flink-table-planner/src/test/java/org/apache/flink/table/planner/functions/JsonFunctionsITCase.java

@@ -693,7 +693,6 @@ private static List<TestSetSpec> jsonStringSpec() {
                                 STRING().notNull()));
     }
 
-    // Test with alias?? using str$1
     private static List<TestSetSpec> jsonSpec() {
         return Arrays.asList(
                 TestSetSpec.forFunction(BuiltInFunctionDefinitions.JSON_OBJECT)