feat: add DataPart.fromJson() factory method for raw JSON strings

Allow developers to create a DataPart directly from a JSON string
without manually deserializing it into Java objects first.

This fixes #753

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jmesnil

spec/src/main/java/io/a2a/spec/DataPart.java

@@ -1,6 +1,10 @@
 package io.a2a.spec;
 
 
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonSyntaxException;
+import com.google.gson.ToNumberPolicy;
 import io.a2a.util.Assert;
 import java.util.Map;
 import org.jspecify.annotations.Nullable;
@@ -77,4 +81,59 @@ public DataPart (Object data, @Nullable Map<String, Object> metadata) {
     public DataPart(Object data) {
         this(data, null);
     }
+
+    /**
+     * Creates a DataPart by parsing a JSON string into its corresponding Java type.
+     * <p>
+     * The JSON string is parsed using Gson with {@code ToNumberPolicy.LONG_OR_DOUBLE},
+     * producing the following mappings:
+     * <ul>
+     *   <li>JSON objects → {@code Map<String, Object>}</li>
+     *   <li>JSON arrays → {@code List<Object>}</li>
+     *   <li>JSON strings → {@code String}</li>
+     *   <li>JSON integers → {@code Long}</li>
+     *   <li>JSON decimals → {@code Double}</li>
+     *   <li>JSON booleans → {@code Boolean}</li>
+     * </ul>
+     * <p>
+     * Example usage:
+     * <pre>{@code
+     * DataPart dataPart = DataPart.fromJson("""
+     *     {
+     *         "temperature": 22.5,
+     *         "humidity": 65
+     *     }""");
+     * }</pre>
+     *
+     * @param json the JSON string to parse (must not be null or the JSON literal "null")
+     * @return a new DataPart containing the parsed data
+     * @throws IllegalArgumentException if json is null, parses to null, or is not valid
+     */
+    public static DataPart fromJson(String json) {
+        return fromJson(json, null);
+    }
+
+    /**
+     * Creates a DataPart by parsing a JSON string into its corresponding Java type,
+     * with optional metadata.
+     *
+     * @param json the JSON string to parse (must not be null or the JSON literal "null")
+     * @param metadata additional metadata for the part
+     * @return a new DataPart containing the parsed data and metadata
+     * @throws IllegalArgumentException if json is null, parses to null, or is not valid
+     * @see #fromJson(String)
+     */
+    public static DataPart fromJson(String json, @Nullable Map<String, Object> metadata) {
+        Assert.checkNotNullParam("json", json);
+        try {
+            Object data = JSON_PARSER.fromJson(json, Object.class);
+            return new DataPart(data, metadata);
+        } catch (JsonSyntaxException e) {
+            throw new IllegalArgumentException("Invalid JSON: " + json, e);
+        }
+    }
+
+    private static final Gson JSON_PARSER = new GsonBuilder()
+            .setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
+            .create();
 }

spec/src/test/java/io/a2a/spec/DataPartTest.java

@@ -0,0 +1,97 @@
+package io.a2a.spec;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+class DataPartTest {
+
+    @Test
+    void testFromJson_object() {
+        DataPart part = DataPart.fromJson("""
+                {"temperature": 22.5, "humidity": 65}""");
+
+        Map<String, Object> data = assertInstanceOf(Map.class, part.data());
+        assertEquals(22.5, data.get("temperature"));
+        assertEquals(65L, data.get("humidity"));
+        assertNull(part.metadata());
+    }
+
+    @Test
+    void testFromJson_array() {
+        DataPart part = DataPart.fromJson("""
+                ["a", "b", "c"]""");
+
+        List<Object> data = assertInstanceOf(List.class, part.data());
+        assertEquals(List.of("a", "b", "c"), data);
+    }
+
+    @Test
+    void testFromJson_string() {
+        DataPart part = DataPart.fromJson("\"hello\"");
+
+        assertEquals("hello", part.data());
+    }
+
+    @Test
+    void testFromJson_integerNumber() {
+        DataPart part = DataPart.fromJson("42");
+
+        assertEquals(42L, part.data());
+    }
+
+    @Test
+    void testFromJson_decimalNumber() {
+        DataPart part = DataPart.fromJson("3.14");
+
+        assertEquals(3.14, part.data());
+    }
+
+    @Test
+    void testFromJson_boolean() {
+        DataPart part = DataPart.fromJson("true");
+
+        assertEquals(true, part.data());
+    }
+
+    @Test
+    void testFromJson_withMetadata() {
+        Map<String, Object> metadata = Map.of("source", "sensor");
+        DataPart part = DataPart.fromJson("""
+                {"temperature": 22.5}""", metadata);
+
+        assertInstanceOf(Map.class, part.data());
+        assertEquals("sensor", part.metadata().get("source"));
+    }
+
+    @Test
+    void testFromJson_nestedObject() {
+        DataPart part = DataPart.fromJson("""
+                {"outer": {"inner": [1, 2, 3]}}""");
+
+        Map<String, Object> data = assertInstanceOf(Map.class, part.data());
+        Map<String, Object> outer = assertInstanceOf(Map.class, data.get("outer"));
+        assertEquals(List.of(1L, 2L, 3L), outer.get("inner"));
+    }
+
+    @Test
+    void testFromJson_nullJsonThrows() {
+        assertThrows(IllegalArgumentException.class, () -> DataPart.fromJson(null));
+    }
+
+    @Test
+    void testFromJson_nullLiteralThrows() {
+        assertThrows(IllegalArgumentException.class, () -> DataPart.fromJson("null"));
+    }
+
+    @Test
+    void testFromJson_invalidJsonThrows() {
+        assertThrows(IllegalArgumentException.class, () -> DataPart.fromJson("{invalid}"));
+    }
+}