diff --git a/spec/src/main/java/io/a2a/json/JsonMappingException.java b/spec/src/main/java/io/a2a/json/JsonMappingException.java
new file mode 100644
index 000000000..550b7827c
--- /dev/null
+++ b/spec/src/main/java/io/a2a/json/JsonMappingException.java
@@ -0,0 +1,102 @@
+package io.a2a.json;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Exception for JSON mapping errors when converting between JSON and Java objects.
+ *
+ * This exception serves as a replacement for Jackson's JsonMappingException, allowing
+ * the A2A Java SDK to remain independent of any specific JSON library implementation.
+ * It represents errors that occur during the mapping phase of deserialization or
+ * serialization, such as type mismatches, invalid values, or constraint violations.
+ *
+ * This exception extends {@link JsonProcessingException} and is used for more specific
+ * mapping-related errors compared to general parsing errors.
+ *
+ * Usage example:
+ *
{@code
+ * try {
+ * Task task = JsonUtil.fromJson(json, Task.class);
+ * if (task.getId() == null) {
+ * throw new JsonMappingException(null, "Task ID cannot be null");
+ * }
+ * } catch (JsonProcessingException e) {
+ * throw new JsonMappingException(null, "Invalid task format: " + e.getMessage(), e);
+ * }
+ * }
+ *
+ * @see JsonProcessingException for the base exception class
+ */
+public class JsonMappingException extends JsonProcessingException {
+
+ /**
+ * Optional reference object that caused the mapping error (e.g., JsonParser or field path).
+ */
+ private final @Nullable Object reference;
+
+ /**
+ * Constructs a new JsonMappingException with the specified reference and message.
+ *
+ * The reference parameter can be used to provide context about where the mapping
+ * error occurred (e.g., a field name, path, or parser reference). It can be null
+ * if no specific reference is available.
+ *
+ * @param reference optional reference object providing context for the error (may be null)
+ * @param message the detail message explaining the mapping error
+ */
+ public JsonMappingException(@Nullable Object reference, String message) {
+ super(message);
+ this.reference = reference;
+ }
+
+ /**
+ * Constructs a new JsonMappingException with the specified reference, message, and cause.
+ *
+ * The reference parameter can be used to provide context about where the mapping
+ * error occurred (e.g., a field name, path, or parser reference). It can be null
+ * if no specific reference is available.
+ *
+ * @param reference optional reference object providing context for the error (may be null)
+ * @param message the detail message explaining the mapping error
+ * @param cause the underlying cause of the mapping error (may be null)
+ */
+ public JsonMappingException(@Nullable Object reference, String message, @Nullable Throwable cause) {
+ super(message, cause);
+ this.reference = reference;
+ }
+
+ /**
+ * Constructs a new JsonMappingException with the specified message and cause.
+ *
+ * This constructor is provided for compatibility when no reference object is needed.
+ *
+ * @param message the detail message explaining the mapping error
+ * @param cause the underlying cause of the mapping error (may be null)
+ */
+ public JsonMappingException(String message, @Nullable Throwable cause) {
+ this(null, message, cause);
+ }
+
+ /**
+ * Constructs a new JsonMappingException with the specified message.
+ *
+ * This constructor is provided for compatibility when no reference object is needed.
+ *
+ * @param message the detail message explaining the mapping error
+ */
+ public JsonMappingException(String message) {
+ this(null, message);
+ }
+
+ /**
+ * Returns the reference object that provides context for the mapping error.
+ *
+ * This may be null if no specific reference was available when the exception
+ * was created.
+ *
+ * @return the reference object, or null if not available
+ */
+ public @Nullable Object getReference() {
+ return reference;
+ }
+}
diff --git a/spec/src/main/java/io/a2a/json/JsonProcessingException.java b/spec/src/main/java/io/a2a/json/JsonProcessingException.java
new file mode 100644
index 000000000..9af50b7ce
--- /dev/null
+++ b/spec/src/main/java/io/a2a/json/JsonProcessingException.java
@@ -0,0 +1,55 @@
+package io.a2a.json;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * General exception for JSON processing errors during serialization or deserialization.
+ *
+ * This exception serves as a replacement for Jackson's JsonProcessingException, allowing
+ * the A2A Java SDK to remain independent of any specific JSON library implementation.
+ * It can be used with any JSON processing library (Gson, Jackson, etc.).
+ *
+ * This is the base class for more specific JSON processing exceptions like
+ * {@link JsonMappingException}.
+ *
+ * Usage example:
+ *
{@code
+ * try {
+ * String json = gson.toJson(object);
+ * } catch (Exception e) {
+ * throw new JsonProcessingException("Failed to serialize object", e);
+ * }
+ * }
+ *
+ * @see JsonMappingException for mapping-specific errors
+ */
+public class JsonProcessingException extends Exception {
+
+ /**
+ * Constructs a new JsonProcessingException with the specified message.
+ *
+ * @param message the detail message explaining the cause of the exception
+ */
+ public JsonProcessingException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new JsonProcessingException with the specified message and cause.
+ *
+ * @param message the detail message explaining the cause of the exception
+ * @param cause the underlying cause of the exception (may be null)
+ */
+ public JsonProcessingException(String message, @Nullable Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new JsonProcessingException with the specified cause.
+ *
+ * @param cause the underlying cause of the exception
+ */
+ public JsonProcessingException(Throwable cause) {
+ super(cause);
+ }
+}
diff --git a/spec/src/main/java/io/a2a/json/JsonUtil.java b/spec/src/main/java/io/a2a/json/JsonUtil.java
new file mode 100644
index 000000000..56dd3f310
--- /dev/null
+++ b/spec/src/main/java/io/a2a/json/JsonUtil.java
@@ -0,0 +1,904 @@
+package io.a2a.json;
+
+import static com.google.gson.stream.JsonToken.BEGIN_ARRAY;
+import static com.google.gson.stream.JsonToken.BEGIN_OBJECT;
+import static com.google.gson.stream.JsonToken.BOOLEAN;
+import static com.google.gson.stream.JsonToken.NULL;
+import static com.google.gson.stream.JsonToken.NUMBER;
+import static com.google.gson.stream.JsonToken.STRING;
+import static io.a2a.spec.A2AErrorCodes.CONTENT_TYPE_NOT_SUPPORTED_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.INTERNAL_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.INVALID_AGENT_RESPONSE_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.INVALID_PARAMS_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.INVALID_REQUEST_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.JSON_PARSE_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.METHOD_NOT_FOUND_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.PUSH_NOTIFICATION_NOT_SUPPORTED_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.TASK_NOT_CANCELABLE_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.TASK_NOT_FOUND_ERROR_CODE;
+import static io.a2a.spec.A2AErrorCodes.UNSUPPORTED_OPERATION_ERROR_CODE;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonSyntaxException;
+import com.google.gson.ToNumberPolicy;
+import com.google.gson.TypeAdapter;
+import com.google.gson.stream.JsonReader;
+import com.google.gson.stream.JsonWriter;
+import io.a2a.spec.APIKeySecurityScheme;
+import io.a2a.spec.EventKind;
+import io.a2a.spec.ContentTypeNotSupportedError;
+import io.a2a.spec.DataPart;
+import io.a2a.spec.FileContent;
+import io.a2a.spec.FilePart;
+import io.a2a.spec.FileWithBytes;
+import io.a2a.spec.FileWithUri;
+import io.a2a.spec.HTTPAuthSecurityScheme;
+import io.a2a.spec.InvalidAgentResponseError;
+import io.a2a.spec.InvalidParamsError;
+import io.a2a.spec.InvalidRequestError;
+import io.a2a.spec.JSONParseError;
+import io.a2a.spec.JSONRPCError;
+import io.a2a.spec.Message;
+import io.a2a.spec.MethodNotFoundError;
+import io.a2a.spec.MutualTLSSecurityScheme;
+import io.a2a.spec.OAuth2SecurityScheme;
+import io.a2a.spec.OpenIdConnectSecurityScheme;
+import io.a2a.spec.Part;
+import io.a2a.spec.PushNotificationNotSupportedError;
+import io.a2a.spec.SecurityScheme;
+import io.a2a.spec.StreamingEventKind;
+import io.a2a.spec.Task;
+import io.a2a.spec.TaskArtifactUpdateEvent;
+import io.a2a.spec.TaskNotCancelableError;
+import io.a2a.spec.TaskNotFoundError;
+import io.a2a.spec.TaskState;
+import io.a2a.spec.TaskStatusUpdateEvent;
+import io.a2a.spec.TextPart;
+import io.a2a.spec.UnsupportedOperationError;
+import java.io.StringReader;
+import java.lang.reflect.Type;
+import java.time.OffsetDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import org.jspecify.annotations.Nullable;
+
+import static io.a2a.json.JsonUtil.JSONRPCErrorTypeAdapter.THROWABLE_MARKER_FIELD;
+
+public class JsonUtil {
+
+ private static GsonBuilder createBaseGsonBuilder() {
+ return new GsonBuilder()
+ .setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
+ .registerTypeAdapter(OffsetDateTime.class, new OffsetDateTimeTypeAdapter())
+ .registerTypeHierarchyAdapter(JSONRPCError.class, new JSONRPCErrorTypeAdapter())
+ .registerTypeAdapter(TaskState.class, new TaskStateTypeAdapter())
+ .registerTypeAdapter(Message.Role.class, new RoleTypeAdapter())
+ .registerTypeAdapter(Part.Kind.class, new PartKindTypeAdapter())
+ .registerTypeHierarchyAdapter(FileContent.class, new FileContentTypeAdapter())
+ .registerTypeHierarchyAdapter(SecurityScheme.class, new SecuritySchemeTypeAdapter());
+ }
+
+ /**
+ * Pre-configured {@link Gson} instance for JSON operations.
+ *
+ * This mapper is configured with strict parsing mode and all necessary custom TypeAdapters
+ * for A2A Protocol types including polymorphic types, enums, and date/time types.
+ *
+ * Used throughout the SDK for consistent JSON serialization and deserialization.
+ *
+ * @see GsonFactory#createGson()
+ */
+ public static final Gson OBJECT_MAPPER = createBaseGsonBuilder()
+ .registerTypeHierarchyAdapter(Part.class, new PartTypeAdapter())
+ .registerTypeHierarchyAdapter(StreamingEventKind.class, new StreamingEventKindTypeAdapter())
+ .registerTypeAdapter(EventKind.class, new EventKindTypeAdapter())
+ .create();
+
+ public static T fromJson(String json, Class classOfT) throws JsonProcessingException {
+ try {
+ return OBJECT_MAPPER.fromJson(json, classOfT);
+ } catch (JsonSyntaxException e) {
+ throw new JsonProcessingException("Failed to parse JSON", e);
+ }
+ }
+
+ public static T fromJson(String json, Type type) throws JsonProcessingException {
+ try {
+ return OBJECT_MAPPER.fromJson(json, type);
+ } catch (JsonSyntaxException e) {
+ throw new JsonProcessingException("Failed to parse JSON", e);
+ }
+ }
+
+ /**
+ * Serializes an object to a JSON string using Gson.
+ *
+ * This method uses the pre-configured {@link #OBJECT_MAPPER} to produce
+ * JSON representation of the provided object.
+ *
+ * @param data the object to serialize
+ * @return JSON string representation of the object
+ */
+ public static String toJson(Object data) throws JsonProcessingException {
+ try {
+ return OBJECT_MAPPER.toJson(data);
+ } catch (JsonSyntaxException e) {
+ throw new JsonProcessingException("Failed to generate JSON", e);
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link OffsetDateTime} to/from ISO-8601 format.
+ *
+ * This adapter ensures that OffsetDateTime instances are serialized to ISO-8601 formatted strings
+ * (e.g., "2023-10-01T12:00:00.234-05:00") and deserialized from the same format.
+ * This is necessary because Gson cannot access private fields of java.time classes via reflection
+ * in Java 17+ due to module system restrictions.
+ *
+ * The adapter uses {@link DateTimeFormatter#ISO_OFFSET_DATE_TIME} for both serialization and
+ * deserialization, which ensures proper handling of timezone offsets.
+ *
+ * @see OffsetDateTime
+ * @see DateTimeFormatter#ISO_OFFSET_DATE_TIME
+ */
+ static class OffsetDateTimeTypeAdapter extends TypeAdapter {
+
+ @Override
+ public void write(JsonWriter out, OffsetDateTime value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ } else {
+ out.value(value.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME));
+ }
+ }
+
+ @Override
+ public @Nullable
+ OffsetDateTime read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+ String dateTimeString = in.nextString();
+ try {
+ return OffsetDateTime.parse(dateTimeString, DateTimeFormatter.ISO_OFFSET_DATE_TIME);
+ } catch (DateTimeParseException e) {
+ throw new JsonSyntaxException("Failed to parse OffsetDateTime: " + dateTimeString, e);
+ }
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link Throwable} and its subclasses.
+ *
+ * This adapter avoids reflection into {@link Throwable}'s private fields, which is not allowed
+ * in Java 17+ due to module system restrictions. Instead, it serializes Throwables as simple
+ * objects containing only the type (fully qualified class name) and message.
+ *
+ * Serialization: Converts a Throwable to a JSON object with:
+ *
+ * - "type": The fully qualified class name (e.g., "java.lang.IllegalArgumentException")
+ * - "message": The exception message
+ *
+ *
+ * Deserialization: Reads the JSON and reconstructs the Throwable using reflection to find
+ * a constructor that accepts a String message parameter. If no such constructor exists or if
+ * instantiation fails, returns a generic {@link RuntimeException} with the message.
+ *
+ * @see Throwable
+ */
+ static class ThrowableTypeAdapter extends TypeAdapter {
+
+ @Override
+ public void write(JsonWriter out, Throwable value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ return;
+ }
+ out.beginObject();
+ out.name("type").value(value.getClass().getName());
+ out.name("message").value(value.getMessage());
+ out.name(THROWABLE_MARKER_FIELD).value(true);
+ out.endObject();
+ }
+
+ @Override
+ public @Nullable
+ Throwable read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+
+ String type = null;
+ String message = null;
+
+ in.beginObject();
+ while (in.hasNext()) {
+ String fieldName = in.nextName();
+ switch (fieldName) {
+ case "type" ->
+ type = in.nextString();
+ case "message" ->
+ message = in.nextString();
+ default ->
+ in.skipValue();
+ }
+ }
+ in.endObject();
+
+ // Try to reconstruct the Throwable
+ if (type != null) {
+ try {
+ Class throwableClass = Class.forName(type);
+ if (Throwable.class.isAssignableFrom(throwableClass)) {
+ // Try to find a constructor that takes a String message
+ try {
+ var constructor = throwableClass.getConstructor(String.class);
+ return (Throwable) constructor.newInstance(message);
+ } catch (NoSuchMethodException e) {
+ // No String constructor, return a generic RuntimeException
+ return new RuntimeException(message);
+ }
+ }
+ } catch (Exception e) {
+ // If we can't reconstruct the exact type, return a generic RuntimeException
+ return new RuntimeException(message);
+ }
+ }
+ return new RuntimeException(message);
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link JSONRPCError} and its subclasses.
+ *
+ * This adapter handles polymorphic deserialization based on the error code, creating the
+ * appropriate subclass instance.
+ *
+ * The adapter maps error codes to their corresponding error classes:
+ *
+ * - -32700: {@link JSONParseError}
+ * - -32600: {@link InvalidRequestError}
+ * - -32601: {@link MethodNotFoundError}
+ * - -32602: {@link InvalidParamsError}
+ * - -32603: {@link InternalError}
+ * - -32001: {@link TaskNotFoundError}
+ * - -32002: {@link TaskNotCancelableError}
+ * - -32003: {@link PushNotificationNotSupportedError}
+ * - -32004: {@link UnsupportedOperationError}
+ * - -32005: {@link ContentTypeNotSupportedError}
+ * - -32006: {@link InvalidAgentResponseError}
+ * - Other codes: {@link JSONRPCError}
+ *
+ *
+ * @see JSONRPCError
+ */
+ static class JSONRPCErrorTypeAdapter extends TypeAdapter {
+
+ private static final ThrowableTypeAdapter THROWABLE_ADAPTER = new ThrowableTypeAdapter();
+ static final String THROWABLE_MARKER_FIELD = "__throwable";
+ private static final String CODE_FIELD = "code";
+ private static final String DATA_FIELD = "data";
+ private static final String MESSAGE_FIELD = "message";
+ private static final String TYPE_FIELD = "type";
+
+ @Override
+ public void write(JsonWriter out, JSONRPCError value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ return;
+ }
+ out.beginObject();
+ out.name(CODE_FIELD).value(value.getCode());
+ out.name(MESSAGE_FIELD).value(value.getMessage());
+ if (value.getData() != null) {
+ out.name(DATA_FIELD);
+ // If data is a Throwable, use ThrowableTypeAdapter to avoid reflection issues
+ if (value.getData() instanceof Throwable throwable) {
+ THROWABLE_ADAPTER.write(out, throwable);
+ } else {
+ // Use Gson to serialize the data field for non-Throwable types
+ OBJECT_MAPPER.toJson(value.getData(), Object.class, out);
+ }
+ }
+ out.endObject();
+ }
+
+ @Override
+ public @Nullable
+ JSONRPCError read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+
+ Integer code = null;
+ String message = null;
+ Object data = null;
+
+ in.beginObject();
+ while (in.hasNext()) {
+ String fieldName = in.nextName();
+ switch (fieldName) {
+ case CODE_FIELD ->
+ code = in.nextInt();
+ case MESSAGE_FIELD ->
+ message = in.nextString();
+ case DATA_FIELD -> {
+ // Read data as a generic object (could be string, number, object, etc.)
+ data = readDataValue(in);
+ }
+ default ->
+ in.skipValue();
+ }
+ }
+ in.endObject();
+
+ // Create the appropriate subclass based on the error code
+ return createErrorInstance(code, message, data);
+ }
+
+ /**
+ * Reads the data field value, which can be of any JSON type.
+ */
+ private @Nullable
+ Object readDataValue(JsonReader in) throws java.io.IOException {
+ return switch (in.peek()) {
+ case STRING ->
+ in.nextString();
+ case NUMBER ->
+ in.nextDouble();
+ case BOOLEAN ->
+ in.nextBoolean();
+ case NULL -> {
+ in.nextNull();
+ yield null;
+ }
+ case BEGIN_OBJECT -> {
+ // Parse as JsonElement to check if it's a Throwable
+ com.google.gson.JsonElement element = com.google.gson.JsonParser.parseReader(in);
+ if (element.isJsonObject()) {
+ com.google.gson.JsonObject obj = element.getAsJsonObject();
+ // Check if it has the structure of a serialized Throwable (type + message)
+ if (obj.has(TYPE_FIELD) && obj.has(MESSAGE_FIELD) && obj.has(THROWABLE_MARKER_FIELD)) {
+ // Deserialize as Throwable using ThrowableTypeAdapter
+ yield THROWABLE_ADAPTER.read(new JsonReader(new StringReader(element.toString())));
+ }
+ }
+ // Otherwise, deserialize as generic object
+ yield OBJECT_MAPPER.fromJson(element, Object.class);
+ }
+ case BEGIN_ARRAY ->
+ // For arrays, read as raw JSON using Gson
+ OBJECT_MAPPER.fromJson(in, Object.class);
+ default -> {
+ in.skipValue();
+ yield null;
+ }
+ };
+ }
+
+ /**
+ * Creates the appropriate JSONRPCError subclass based on the error code.
+ */
+ private JSONRPCError createErrorInstance(@Nullable Integer code, @Nullable String message, @Nullable Object data) {
+ if (code == null) {
+ throw new JsonSyntaxException("JSONRPCError must have a code field");
+ }
+
+ return switch (code) {
+ case JSON_PARSE_ERROR_CODE ->
+ new JSONParseError(code, message, data);
+ case INVALID_REQUEST_ERROR_CODE ->
+ new InvalidRequestError(code, message, data);
+ case METHOD_NOT_FOUND_ERROR_CODE ->
+ new MethodNotFoundError(code, message, data);
+ case INVALID_PARAMS_ERROR_CODE ->
+ new InvalidParamsError(code, message, data);
+ case INTERNAL_ERROR_CODE ->
+ new io.a2a.spec.InternalError(code, message, data);
+ case TASK_NOT_FOUND_ERROR_CODE ->
+ new TaskNotFoundError(code, message, data);
+ case TASK_NOT_CANCELABLE_ERROR_CODE ->
+ new TaskNotCancelableError(code, message, data);
+ case PUSH_NOTIFICATION_NOT_SUPPORTED_ERROR_CODE ->
+ new PushNotificationNotSupportedError(code, message, data);
+ case UNSUPPORTED_OPERATION_ERROR_CODE ->
+ new UnsupportedOperationError(code, message, data);
+ case CONTENT_TYPE_NOT_SUPPORTED_ERROR_CODE ->
+ new ContentTypeNotSupportedError(code, message, data);
+ case INVALID_AGENT_RESPONSE_ERROR_CODE ->
+ new InvalidAgentResponseError(code, message, data);
+ default ->
+ new JSONRPCError(code, message, data);
+ };
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link TaskState} enum.
+ *
+ * This adapter ensures that TaskState enum values are serialized using their
+ * wire format string representation (e.g., "completed", "working") rather than
+ * the Java enum constant name (e.g., "COMPLETED", "WORKING").
+ *
+ * For serialization, it uses {@link TaskState#asString()} to get the wire format.
+ * For deserialization, it uses {@link TaskState#fromString(String)} to parse the
+ * wire format back to the enum constant.
+ *
+ * @see TaskState
+ * @see TaskState#asString()
+ * @see TaskState#fromString(String)
+ */
+ static class TaskStateTypeAdapter extends TypeAdapter {
+
+ @Override
+ public void write(JsonWriter out, TaskState value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ } else {
+ out.value(value.asString());
+ }
+ }
+
+ @Override
+ public @Nullable
+ TaskState read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+ String stateString = in.nextString();
+ try {
+ return TaskState.fromString(stateString);
+ } catch (IllegalArgumentException e) {
+ throw new JsonSyntaxException("Invalid TaskState: " + stateString, e);
+ }
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link Message.Role} enum.
+ *
+ * This adapter ensures that Message.Role enum values are serialized using their
+ * wire format string representation (e.g., "user", "agent") rather than the Java
+ * enum constant name (e.g., "USER", "AGENT").
+ *
+ * For serialization, it uses {@link Message.Role#asString()} to get the wire format.
+ * For deserialization, it parses the string to the enum constant.
+ *
+ * @see Message.Role
+ * @see Message.Role#asString()
+ */
+ static class RoleTypeAdapter extends TypeAdapter {
+
+ @Override
+ public void write(JsonWriter out, Message.Role value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ } else {
+ out.value(value.asString());
+ }
+ }
+
+ @Override
+ public Message.@Nullable Role read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+ String roleString = in.nextString();
+ try {
+ return switch (roleString) {
+ case "user" ->
+ Message.Role.USER;
+ case "agent" ->
+ Message.Role.AGENT;
+ default ->
+ throw new IllegalArgumentException("Invalid Role: " + roleString);
+ };
+ } catch (IllegalArgumentException e) {
+ throw new JsonSyntaxException("Invalid Message.Role: " + roleString, e);
+ }
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link Part.Kind} enum.
+ *
+ * This adapter ensures that Part.Kind enum values are serialized using their
+ * wire format string representation (e.g., "text", "file", "data") rather than
+ * the Java enum constant name (e.g., "TEXT", "FILE", "DATA").
+ *
+ * For serialization, it uses {@link Part.Kind#asString()} to get the wire format.
+ * For deserialization, it parses the string to the enum constant.
+ *
+ * @see Part.Kind
+ * @see Part.Kind#asString()
+ */
+ static class PartKindTypeAdapter extends TypeAdapter {
+
+ @Override
+ public void write(JsonWriter out, Part.Kind value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ } else {
+ out.value(value.asString());
+ }
+ }
+
+ @Override
+ public Part.@Nullable Kind read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+ String kindString = in.nextString();
+ try {
+ return switch (kindString) {
+ case "text" ->
+ Part.Kind.TEXT;
+ case "file" ->
+ Part.Kind.FILE;
+ case "data" ->
+ Part.Kind.DATA;
+ default ->
+ throw new IllegalArgumentException("Invalid Part.Kind: " + kindString);
+ };
+ } catch (IllegalArgumentException e) {
+ throw new JsonSyntaxException("Invalid Part.Kind: " + kindString, e);
+ }
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link Part} and its subclasses.
+ *
+ * This adapter handles polymorphic deserialization based on the "kind" field, creating the
+ * appropriate subclass instance (TextPart, FilePart, or DataPart).
+ *
+ * The adapter uses a two-pass approach: first reads the JSON as a tree to inspect the "kind"
+ * field, then deserializes to the appropriate concrete type.
+ *
+ * @see Part
+ * @see TextPart
+ * @see FilePart
+ * @see DataPart
+ */
+ static class PartTypeAdapter extends TypeAdapter> {
+
+ // Create separate Gson instance without the Part adapter to avoid recursion
+ private final Gson delegateGson = createBaseGsonBuilder().create();
+
+ @Override
+ public void write(JsonWriter out, Part value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ return;
+ }
+ // Delegate to Gson's default serialization for the concrete type
+ if (value instanceof TextPart textPart) {
+ delegateGson.toJson(textPart, TextPart.class, out);
+ } else if (value instanceof FilePart filePart) {
+ delegateGson.toJson(filePart, FilePart.class, out);
+ } else if (value instanceof DataPart dataPart) {
+ delegateGson.toJson(dataPart, DataPart.class, out);
+ } else {
+ throw new JsonSyntaxException("Unknown Part subclass: " + value.getClass().getName());
+ }
+ }
+
+ @Override
+ public @Nullable
+ Part read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+
+ // Read the JSON as a tree so we can inspect the "kind" field
+ com.google.gson.JsonElement jsonElement = com.google.gson.JsonParser.parseReader(in);
+ if (!jsonElement.isJsonObject()) {
+ throw new JsonSyntaxException("Part must be a JSON object");
+ }
+
+ com.google.gson.JsonObject jsonObject = jsonElement.getAsJsonObject();
+ com.google.gson.JsonElement kindElement = jsonObject.get("kind");
+ if (kindElement == null || !kindElement.isJsonPrimitive()) {
+ throw new JsonSyntaxException("Part must have a 'kind' field");
+ }
+
+ String kind = kindElement.getAsString();
+ // Use the delegate Gson to deserialize to the concrete type
+ return switch (kind) {
+ case "text" ->
+ delegateGson.fromJson(jsonElement, TextPart.class);
+ case "file" ->
+ delegateGson.fromJson(jsonElement, FilePart.class);
+ case "data" ->
+ delegateGson.fromJson(jsonElement, DataPart.class);
+ default ->
+ throw new JsonSyntaxException("Unknown Part kind: " + kind);
+ };
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link EventKind} and its implementations.
+ *
+ * Discriminates based on the {@code "kind"} field:
+ *
+ * - {@code "task"} → {@link Task}
+ * - {@code "message"} → {@link Message}
+ *
+ */
+ static class EventKindTypeAdapter extends TypeAdapter {
+
+ private final Gson delegateGson = createBaseGsonBuilder()
+ .registerTypeHierarchyAdapter(Part.class, new PartTypeAdapter())
+ .create();
+
+ @Override
+ public void write(JsonWriter out, EventKind value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ return;
+ }
+ if (value instanceof Task task) {
+ delegateGson.toJson(task, Task.class, out);
+ } else if (value instanceof Message message) {
+ delegateGson.toJson(message, Message.class, out);
+ } else {
+ throw new JsonSyntaxException("Unknown EventKind implementation: " + value.getClass().getName());
+ }
+ }
+
+ @Override
+ public @Nullable EventKind read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+
+ com.google.gson.JsonElement jsonElement = com.google.gson.JsonParser.parseReader(in);
+ if (!jsonElement.isJsonObject()) {
+ throw new JsonSyntaxException("EventKind must be a JSON object");
+ }
+
+ com.google.gson.JsonObject jsonObject = jsonElement.getAsJsonObject();
+ com.google.gson.JsonElement kindElement = jsonObject.get("kind");
+ if (kindElement == null || !kindElement.isJsonPrimitive()) {
+ throw new JsonSyntaxException("EventKind must have a 'kind' field");
+ }
+
+ String kind = kindElement.getAsString();
+ return switch (kind) {
+ case Task.TASK -> delegateGson.fromJson(jsonElement, Task.class);
+ case Message.MESSAGE -> delegateGson.fromJson(jsonElement, Message.class);
+ default -> throw new JsonSyntaxException("Unknown EventKind kind: " + kind);
+ };
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link StreamingEventKind} and its implementations.
+ *
+ * This adapter handles polymorphic deserialization based on the "kind" field, creating the
+ * appropriate implementation instance (Task, Message, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
+ *
+ * The adapter uses a two-pass approach: first reads the JSON as a tree to inspect the "kind"
+ * field, then deserializes to the appropriate concrete type.
+ *
+ * @see StreamingEventKind
+ * @see Task
+ * @see Message
+ * @see TaskStatusUpdateEvent
+ * @see TaskArtifactUpdateEvent
+ */
+ static class StreamingEventKindTypeAdapter extends TypeAdapter {
+
+ // Create separate Gson instance without the StreamingEventKind adapter to avoid recursion
+ private final Gson delegateGson = createBaseGsonBuilder()
+ .registerTypeHierarchyAdapter(Part.class, new PartTypeAdapter())
+ .create();
+
+ @Override
+ public void write(JsonWriter out, StreamingEventKind value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ return;
+ }
+ // Delegate to Gson's default serialization for the concrete type
+ if (value instanceof Task task) {
+ delegateGson.toJson(task, Task.class, out);
+ } else if (value instanceof Message message) {
+ delegateGson.toJson(message, Message.class, out);
+ } else if (value instanceof TaskStatusUpdateEvent event) {
+ delegateGson.toJson(event, TaskStatusUpdateEvent.class, out);
+ } else if (value instanceof TaskArtifactUpdateEvent event) {
+ delegateGson.toJson(event, TaskArtifactUpdateEvent.class, out);
+ } else {
+ throw new JsonSyntaxException("Unknown StreamingEventKind implementation: " + value.getClass().getName());
+ }
+ }
+
+ @Override
+ public @Nullable
+ StreamingEventKind read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+
+ // Read the JSON as a tree so we can inspect the "kind" field
+ com.google.gson.JsonElement jsonElement = com.google.gson.JsonParser.parseReader(in);
+ if (!jsonElement.isJsonObject()) {
+ throw new JsonSyntaxException("StreamingEventKind must be a JSON object");
+ }
+
+ com.google.gson.JsonObject jsonObject = jsonElement.getAsJsonObject();
+ com.google.gson.JsonElement kindElement = jsonObject.get("kind");
+ if (kindElement == null || !kindElement.isJsonPrimitive()) {
+ throw new JsonSyntaxException("StreamingEventKind must have a 'kind' field");
+ }
+
+ String kind = kindElement.getAsString();
+ // Use the delegate Gson to deserialize to the concrete type
+ return switch (kind) {
+ case "task" ->
+ delegateGson.fromJson(jsonElement, Task.class);
+ case "message" ->
+ delegateGson.fromJson(jsonElement, Message.class);
+ case "status-update" ->
+ delegateGson.fromJson(jsonElement, TaskStatusUpdateEvent.class);
+ case "artifact-update" ->
+ delegateGson.fromJson(jsonElement, TaskArtifactUpdateEvent.class);
+ default ->
+ throw new JsonSyntaxException("Unknown StreamingEventKind kind: " + kind);
+ };
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link SecurityScheme} and its implementations.
+ *
+ * Discriminates based on the {@code "type"} field:
+ *
+ * - {@code "apiKey"} → {@link APIKeySecurityScheme}
+ * - {@code "http"} → {@link HTTPAuthSecurityScheme}
+ * - {@code "oauth2"} → {@link OAuth2SecurityScheme}
+ * - {@code "openIdConnect"} → {@link OpenIdConnectSecurityScheme}
+ * - {@code "mutualTLS"} → {@link MutualTLSSecurityScheme}
+ *
+ */
+ static class SecuritySchemeTypeAdapter extends TypeAdapter {
+
+ // Use a plain Gson to avoid circular initialization — SecurityScheme concrete types
+ // contain only simple fields (Strings, OAuthFlows) that need no custom adapters.
+ private final Gson delegateGson = new Gson();
+
+ @Override
+ public void write(JsonWriter out, SecurityScheme value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ return;
+ }
+ if (value instanceof APIKeySecurityScheme v) {
+ delegateGson.toJson(v, APIKeySecurityScheme.class, out);
+ } else if (value instanceof HTTPAuthSecurityScheme v) {
+ delegateGson.toJson(v, HTTPAuthSecurityScheme.class, out);
+ } else if (value instanceof OAuth2SecurityScheme v) {
+ delegateGson.toJson(v, OAuth2SecurityScheme.class, out);
+ } else if (value instanceof OpenIdConnectSecurityScheme v) {
+ delegateGson.toJson(v, OpenIdConnectSecurityScheme.class, out);
+ } else if (value instanceof MutualTLSSecurityScheme v) {
+ delegateGson.toJson(v, MutualTLSSecurityScheme.class, out);
+ } else {
+ throw new JsonSyntaxException("Unknown SecurityScheme implementation: " + value.getClass().getName());
+ }
+ }
+
+ @Override
+ public @Nullable SecurityScheme read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+
+ com.google.gson.JsonElement jsonElement = com.google.gson.JsonParser.parseReader(in);
+ if (!jsonElement.isJsonObject()) {
+ throw new JsonSyntaxException("SecurityScheme must be a JSON object");
+ }
+
+ com.google.gson.JsonObject jsonObject = jsonElement.getAsJsonObject();
+ com.google.gson.JsonElement typeElement = jsonObject.get("type");
+ if (typeElement == null || !typeElement.isJsonPrimitive()) {
+ throw new JsonSyntaxException("SecurityScheme must have a 'type' field");
+ }
+
+ String type = typeElement.getAsString();
+ return switch (type) {
+ case APIKeySecurityScheme.API_KEY ->
+ delegateGson.fromJson(jsonElement, APIKeySecurityScheme.class);
+ case HTTPAuthSecurityScheme.HTTP ->
+ delegateGson.fromJson(jsonElement, HTTPAuthSecurityScheme.class);
+ case OAuth2SecurityScheme.OAUTH2 ->
+ delegateGson.fromJson(jsonElement, OAuth2SecurityScheme.class);
+ case OpenIdConnectSecurityScheme.OPENID_CONNECT ->
+ delegateGson.fromJson(jsonElement, OpenIdConnectSecurityScheme.class);
+ case MutualTLSSecurityScheme.MUTUAL_TLS ->
+ delegateGson.fromJson(jsonElement, MutualTLSSecurityScheme.class);
+ default ->
+ throw new JsonSyntaxException("Unknown SecurityScheme type: " + type);
+ };
+ }
+ }
+
+ /**
+ * Gson TypeAdapter for serializing and deserializing {@link FileContent} and its implementations.
+ *
+ * This adapter handles polymorphic deserialization for the sealed FileContent interface,
+ * which permits two implementations:
+ *
+ * - {@link FileWithBytes} - File content embedded as base64-encoded bytes
+ * - {@link FileWithUri} - File content referenced by URI
+ *
+ *
+ * The adapter distinguishes between the two types by checking for the presence of
+ * "bytes" or "uri" fields in the JSON object.
+ *
+ * @see FileContent
+ * @see FileWithBytes
+ * @see FileWithUri
+ */
+ static class FileContentTypeAdapter extends TypeAdapter {
+
+ // Create separate Gson instance without the FileContent adapter to avoid recursion
+ private final Gson delegateGson = new Gson();
+
+ @Override
+ public void write(JsonWriter out, FileContent value) throws java.io.IOException {
+ if (value == null) {
+ out.nullValue();
+ return;
+ }
+ // Delegate to Gson's default serialization for the concrete type
+ if (value instanceof FileWithBytes fileWithBytes) {
+ delegateGson.toJson(fileWithBytes, FileWithBytes.class, out);
+ } else if (value instanceof FileWithUri fileWithUri) {
+ delegateGson.toJson(fileWithUri, FileWithUri.class, out);
+ } else {
+ throw new JsonSyntaxException("Unknown FileContent implementation: " + value.getClass().getName());
+ }
+ }
+
+ @Override
+ public @Nullable
+ FileContent read(JsonReader in) throws java.io.IOException {
+ if (in.peek() == com.google.gson.stream.JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+
+ // Read the JSON as a tree to inspect the fields
+ com.google.gson.JsonElement jsonElement = com.google.gson.JsonParser.parseReader(in);
+ if (!jsonElement.isJsonObject()) {
+ throw new JsonSyntaxException("FileContent must be a JSON object");
+ }
+
+ com.google.gson.JsonObject jsonObject = jsonElement.getAsJsonObject();
+
+ // Distinguish between FileWithBytes and FileWithUri by checking for "bytes" or "uri" field
+ if (jsonObject.has("bytes")) {
+ return delegateGson.fromJson(jsonElement, FileWithBytes.class);
+ } else if (jsonObject.has("uri")) {
+ return delegateGson.fromJson(jsonElement, FileWithUri.class);
+ } else {
+ throw new JsonSyntaxException("FileContent must have either 'bytes' or 'uri' field");
+ }
+ }
+ }
+
+}
diff --git a/spec/src/main/java/io/a2a/json/package-info.java b/spec/src/main/java/io/a2a/json/package-info.java
new file mode 100644
index 000000000..81fe05a3a
--- /dev/null
+++ b/spec/src/main/java/io/a2a/json/package-info.java
@@ -0,0 +1,8 @@
+/**
+ * JSON processing exceptions for the A2A Java SDK.
+ *
+ * This package provides custom exceptions that replace Jackson's JSON processing exceptions,
+ * allowing the SDK to be independent of any specific JSON library implementation.
+ */
+@org.jspecify.annotations.NullMarked
+package io.a2a.json;
diff --git a/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java b/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java
index 75988da1c..06d04605c 100644
--- a/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java
+++ b/spec/src/main/java/io/a2a/spec/A2AClientJSONError.java
@@ -1,5 +1,30 @@
package io.a2a.spec;
+/**
+ * Client exception indicating a JSON serialization or deserialization error.
+ *
+ * This exception is thrown when the A2A client SDK encounters errors while
+ * parsing JSON responses from agents or serializing requests. This typically
+ * indicates:
+ *
+ * - Malformed JSON in agent responses
+ * - Unexpected JSON structure or field types
+ * - Missing required JSON fields
+ * - JSON encoding/decoding errors
+ *
+ *
+ * Usage example:
+ *
{@code
+ * try {
+ * AgentCard card = objectMapper.readValue(json, AgentCard.class);
+ * } catch (io.a2a.json.JsonProcessingException e) {
+ * throw new A2AClientJSONError("Failed to parse agent card", e);
+ * }
+ * }
+ *
+ * @see A2AClientError for the base client error class
+ * @see JSONParseError for protocol-level JSON errors
+ */
public class A2AClientJSONError extends A2AClientError {
public A2AClientJSONError() {
diff --git a/spec/src/main/java/io/a2a/spec/A2AErrorCodes.java b/spec/src/main/java/io/a2a/spec/A2AErrorCodes.java
new file mode 100644
index 000000000..09175b744
--- /dev/null
+++ b/spec/src/main/java/io/a2a/spec/A2AErrorCodes.java
@@ -0,0 +1,22 @@
+package io.a2a.spec;
+
+/**
+ * All the error codes for A2A errors.
+ */
+public interface A2AErrorCodes {
+
+ int TASK_NOT_FOUND_ERROR_CODE = -32001;
+ int TASK_NOT_CANCELABLE_ERROR_CODE = -32002;
+ int PUSH_NOTIFICATION_NOT_SUPPORTED_ERROR_CODE = -32003;
+ int UNSUPPORTED_OPERATION_ERROR_CODE = -32004;
+ int CONTENT_TYPE_NOT_SUPPORTED_ERROR_CODE = -32005;
+ int INVALID_AGENT_RESPONSE_ERROR_CODE = -32006;
+ int AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED_ERROR_CODE = -32007;
+
+ int INVALID_REQUEST_ERROR_CODE = -32600;
+ int METHOD_NOT_FOUND_ERROR_CODE = -32601;
+ int INVALID_PARAMS_ERROR_CODE = -32602;
+ int INTERNAL_ERROR_CODE = -32603;
+
+ int JSON_PARSE_ERROR_CODE = -32700;
+}
diff --git a/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java b/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java
index 028fea303..a2dc48c4d 100644
--- a/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java
@@ -1,12 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
-import com.fasterxml.jackson.annotation.JsonValue;
-
import io.a2a.util.Assert;
import static io.a2a.spec.APIKeySecurityScheme.API_KEY;
@@ -14,9 +7,6 @@
/**
* Defines a security scheme using an API key.
*/
-@JsonTypeName(API_KEY)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class APIKeySecurityScheme implements SecurityScheme {
public static final String API_KEY = "apiKey";
@@ -39,12 +29,10 @@ public enum Location {
this.location = location;
}
- @JsonValue
public String asString() {
return location;
}
- @JsonCreator
public static Location fromString(String location) {
switch (location) {
case "cookie" -> {
@@ -65,9 +53,8 @@ public APIKeySecurityScheme(String in, String name, String description) {
this(in, name, description, API_KEY);
}
- @JsonCreator
- public APIKeySecurityScheme(@JsonProperty("in") String in, @JsonProperty("name") String name,
- @JsonProperty("description") String description, @JsonProperty("type") String type) {
+ public APIKeySecurityScheme(String in, String name,
+ String description, String type) {
Assert.checkNotNullParam("in", in);
Assert.checkNotNullParam("name", name);
Assert.checkNotNullParam("type", type);
diff --git a/spec/src/main/java/io/a2a/spec/AgentCapabilities.java b/spec/src/main/java/io/a2a/spec/AgentCapabilities.java
index 1c6fdf1b2..1de51d5f9 100644
--- a/spec/src/main/java/io/a2a/spec/AgentCapabilities.java
+++ b/spec/src/main/java/io/a2a/spec/AgentCapabilities.java
@@ -2,14 +2,9 @@
import java.util.List;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
/**
* Defines optional capabilities supported by an agent.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record AgentCapabilities(boolean streaming, boolean pushNotifications, boolean stateTransitionHistory,
List extensions) {
diff --git a/spec/src/main/java/io/a2a/spec/AgentCard.java b/spec/src/main/java/io/a2a/spec/AgentCard.java
index b59a9403b..2574f5425 100644
--- a/spec/src/main/java/io/a2a/spec/AgentCard.java
+++ b/spec/src/main/java/io/a2a/spec/AgentCard.java
@@ -4,8 +4,6 @@
import java.util.List;
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
@@ -13,8 +11,6 @@
* metadata including the agent's identity, capabilities, skills, supported
* communication methods, and security requirements.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record AgentCard(String name, String description, String url, AgentProvider provider,
String version, String documentationUrl, AgentCapabilities capabilities,
List defaultInputModes, List defaultOutputModes, List skills,
diff --git a/spec/src/main/java/io/a2a/spec/AgentCardSignature.java b/spec/src/main/java/io/a2a/spec/AgentCardSignature.java
index 4e383d998..70a92cd57 100644
--- a/spec/src/main/java/io/a2a/spec/AgentCardSignature.java
+++ b/spec/src/main/java/io/a2a/spec/AgentCardSignature.java
@@ -1,20 +1,15 @@
package io.a2a.spec;
+import com.google.gson.annotations.SerializedName;
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
import io.a2a.util.Assert;
/**
* Represents a JWS signature of an AgentCard.
* This follows the JSON format of an RFC 7515 JSON Web Signature (JWS).
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
-public record AgentCardSignature(Map header, @JsonProperty("protected") String protectedHeader,
+public record AgentCardSignature(Map header, @SerializedName("protected")String protectedHeader,
String signature) {
public AgentCardSignature {
diff --git a/spec/src/main/java/io/a2a/spec/AgentInterface.java b/spec/src/main/java/io/a2a/spec/AgentInterface.java
index db81ce8f0..0b2e8d8b0 100644
--- a/spec/src/main/java/io/a2a/spec/AgentInterface.java
+++ b/spec/src/main/java/io/a2a/spec/AgentInterface.java
@@ -1,16 +1,13 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
+
import io.a2a.util.Assert;
/**
* Declares a combination of a target URL and a transport protocol for interacting with the agent.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
-public record AgentInterface(String transport, String url) {
+public record AgentInterface(String transport, String url) {
public AgentInterface {
Assert.checkNotNullParam("transport", transport);
Assert.checkNotNullParam("url", url);
diff --git a/spec/src/main/java/io/a2a/spec/AgentProvider.java b/spec/src/main/java/io/a2a/spec/AgentProvider.java
index fa57b4478..1d50b699e 100644
--- a/spec/src/main/java/io/a2a/spec/AgentProvider.java
+++ b/spec/src/main/java/io/a2a/spec/AgentProvider.java
@@ -1,14 +1,10 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Represents the service provider of an agent.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record AgentProvider(String organization, String url) {
public AgentProvider {
diff --git a/spec/src/main/java/io/a2a/spec/AgentSkill.java b/spec/src/main/java/io/a2a/spec/AgentSkill.java
index 3802b3418..b397f6248 100644
--- a/spec/src/main/java/io/a2a/spec/AgentSkill.java
+++ b/spec/src/main/java/io/a2a/spec/AgentSkill.java
@@ -3,15 +3,11 @@
import java.util.List;
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* The set of skills, or distinct capabilities, that the agent can perform.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record AgentSkill(String id, String name, String description, List tags,
List examples, List inputModes, List outputModes,
List>> security) {
diff --git a/spec/src/main/java/io/a2a/spec/Artifact.java b/spec/src/main/java/io/a2a/spec/Artifact.java
index 798ac5823..69d2f0581 100644
--- a/spec/src/main/java/io/a2a/spec/Artifact.java
+++ b/spec/src/main/java/io/a2a/spec/Artifact.java
@@ -3,15 +3,11 @@
import java.util.List;
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Represents a file, data structure, or other resource generated by an agent during a task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record Artifact(String artifactId, String name, String description, List> parts, Map metadata,
List extensions) {
diff --git a/spec/src/main/java/io/a2a/spec/AuthenticatedExtendedCardNotConfiguredError.java b/spec/src/main/java/io/a2a/spec/AuthenticatedExtendedCardNotConfiguredError.java
index 323cd147d..7ac3e9d9c 100644
--- a/spec/src/main/java/io/a2a/spec/AuthenticatedExtendedCardNotConfiguredError.java
+++ b/spec/src/main/java/io/a2a/spec/AuthenticatedExtendedCardNotConfiguredError.java
@@ -2,34 +2,19 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
/**
* An A2A-specific error indicating that the agent does not have an
* Authenticated Extended Card configured
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class AuthenticatedExtendedCardNotConfiguredError extends JSONRPCError {
public final static Integer DEFAULT_CODE = -32007;
- @JsonCreator
- public AuthenticatedExtendedCardNotConfiguredError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ public AuthenticatedExtendedCardNotConfiguredError(Integer code, String message, Object data) {
super(
defaultIfNull(code, DEFAULT_CODE),
defaultIfNull(message, "Authenticated Extended Card not configured"),
data);
}
-
- public AuthenticatedExtendedCardNotConfiguredError() {
- this(null, null, null);
- }
-
}
diff --git a/spec/src/main/java/io/a2a/spec/AuthenticationInfo.java b/spec/src/main/java/io/a2a/spec/AuthenticationInfo.java
index d28a1e173..4f24e3c4c 100644
--- a/spec/src/main/java/io/a2a/spec/AuthenticationInfo.java
+++ b/spec/src/main/java/io/a2a/spec/AuthenticationInfo.java
@@ -2,15 +2,11 @@
import java.util.List;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* The authentication info for an agent.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record AuthenticationInfo(List schemes, String credentials) {
public AuthenticationInfo {
diff --git a/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java b/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java
index afa6fed72..cc5e0ee54 100644
--- a/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java
+++ b/spec/src/main/java/io/a2a/spec/AuthorizationCodeOAuthFlow.java
@@ -2,16 +2,12 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Defines configuration details for the OAuth 2.0 Authorization Code flow.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record AuthorizationCodeOAuthFlow(String authorizationUrl, String refreshUrl, Map scopes,
String tokenUrl) {
diff --git a/spec/src/main/java/io/a2a/spec/CancelTaskRequest.java b/spec/src/main/java/io/a2a/spec/CancelTaskRequest.java
index 39c370ae3..f8a1bb8bf 100644
--- a/spec/src/main/java/io/a2a/spec/CancelTaskRequest.java
+++ b/spec/src/main/java/io/a2a/spec/CancelTaskRequest.java
@@ -4,25 +4,17 @@
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
import io.a2a.util.Assert;
/**
* A request that can be used to cancel a task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class CancelTaskRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "tasks/cancel";
- @JsonCreator
- public CancelTaskRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") TaskIdParams params) {
+ public CancelTaskRequest(String jsonrpc, Object id, String method, TaskIdParams params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/CancelTaskResponse.java b/spec/src/main/java/io/a2a/spec/CancelTaskResponse.java
index 9ef775118..d65091080 100644
--- a/spec/src/main/java/io/a2a/spec/CancelTaskResponse.java
+++ b/spec/src/main/java/io/a2a/spec/CancelTaskResponse.java
@@ -1,20 +1,12 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* A response to a cancel task request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
+
public final class CancelTaskResponse extends JSONRPCResponse {
- @JsonCreator
- public CancelTaskResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") Task result, @JsonProperty("error") JSONRPCError error) {
+ public CancelTaskResponse(String jsonrpc, Object id, Task result, JSONRPCError error) {
super(jsonrpc, id, result, error, Task.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/ClientCredentialsOAuthFlow.java b/spec/src/main/java/io/a2a/spec/ClientCredentialsOAuthFlow.java
index 372b57d78..18056681f 100644
--- a/spec/src/main/java/io/a2a/spec/ClientCredentialsOAuthFlow.java
+++ b/spec/src/main/java/io/a2a/spec/ClientCredentialsOAuthFlow.java
@@ -3,16 +3,12 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Defines configuration details for the OAuth 2.0 Client Credentials flow.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record ClientCredentialsOAuthFlow(String refreshUrl, Map scopes, String tokenUrl) {
public ClientCredentialsOAuthFlow {
diff --git a/spec/src/main/java/io/a2a/spec/ContentTypeNotSupportedError.java b/spec/src/main/java/io/a2a/spec/ContentTypeNotSupportedError.java
index 3aa245ca2..fc8c412d5 100644
--- a/spec/src/main/java/io/a2a/spec/ContentTypeNotSupportedError.java
+++ b/spec/src/main/java/io/a2a/spec/ContentTypeNotSupportedError.java
@@ -1,29 +1,19 @@
package io.a2a.spec;
+import static io.a2a.spec.A2AErrorCodes.CONTENT_TYPE_NOT_SUPPORTED_ERROR_CODE;
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
/**
* An A2A-specific error indicating an incompatibility between the requested
* content types and the agent's capabilities.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class ContentTypeNotSupportedError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32005;
+ public final static Integer DEFAULT_CODE = CONTENT_TYPE_NOT_SUPPORTED_ERROR_CODE;
- @JsonCreator
- public ContentTypeNotSupportedError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
- super(
- defaultIfNull(code, DEFAULT_CODE),
+ public ContentTypeNotSupportedError(Integer code, String message, Object data) {
+ super(defaultIfNull(code, CONTENT_TYPE_NOT_SUPPORTED_ERROR_CODE),
defaultIfNull(message, "Incompatible content types"),
data);
}
diff --git a/spec/src/main/java/io/a2a/spec/DataPart.java b/spec/src/main/java/io/a2a/spec/DataPart.java
index 7ac244263..58e8ae412 100644
--- a/spec/src/main/java/io/a2a/spec/DataPart.java
+++ b/spec/src/main/java/io/a2a/spec/DataPart.java
@@ -2,21 +2,12 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
-import static io.a2a.spec.DataPart.DATA;
/**
* Represents a structured data segment (e.g., JSON) within a message or artifact.
*/
-@JsonTypeName(DATA)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class DataPart extends Part> {
public static final String DATA = "data";
@@ -28,9 +19,7 @@ public DataPart(Map data) {
this(data, null);
}
- @JsonCreator
- public DataPart(@JsonProperty("data") Map data,
- @JsonProperty("metadata") Map metadata) {
+ public DataPart(Map data, Map metadata) {
Assert.checkNotNullParam("data", data);
this.data = data;
this.metadata = metadata;
diff --git a/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigParams.java b/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigParams.java
index a64421a4c..0cb34a38d 100644
--- a/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigParams.java
+++ b/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigParams.java
@@ -2,16 +2,12 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Parameters for removing pushNotificationConfiguration associated with a Task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record DeleteTaskPushNotificationConfigParams(String id, String pushNotificationConfigId, Map metadata) {
public DeleteTaskPushNotificationConfigParams {
diff --git a/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigRequest.java b/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigRequest.java
index 99f50ebfd..dc3449ada 100644
--- a/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigRequest.java
+++ b/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigRequest.java
@@ -2,27 +2,17 @@
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
import io.a2a.util.Assert;
import io.a2a.util.Utils;
/**
* A delete task push notification config request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class DeleteTaskPushNotificationConfigRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "tasks/pushNotificationConfig/delete";
- @JsonCreator
- public DeleteTaskPushNotificationConfigRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method,
- @JsonProperty("params") DeleteTaskPushNotificationConfigParams params) {
+ public DeleteTaskPushNotificationConfigRequest(String jsonrpc, Object id, String method, DeleteTaskPushNotificationConfigParams params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigResponse.java b/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigResponse.java
index 0f65b5ad5..89e4964db 100644
--- a/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigResponse.java
+++ b/spec/src/main/java/io/a2a/spec/DeleteTaskPushNotificationConfigResponse.java
@@ -1,23 +1,11 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.databind.annotation.JsonSerialize;
-
/**
* A response for a delete task push notification config request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
-@JsonSerialize(using = JSONRPCVoidResponseSerializer.class)
public final class DeleteTaskPushNotificationConfigResponse extends JSONRPCResponse {
- @JsonCreator
- public DeleteTaskPushNotificationConfigResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") Void result,
- @JsonProperty("error") JSONRPCError error) {
+ public DeleteTaskPushNotificationConfigResponse(String jsonrpc, Object id, Void result,JSONRPCError error) {
super(jsonrpc, id, result, error, Void.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/EventKind.java b/spec/src/main/java/io/a2a/spec/EventKind.java
index a1ed7ef31..888611f81 100644
--- a/spec/src/main/java/io/a2a/spec/EventKind.java
+++ b/spec/src/main/java/io/a2a/spec/EventKind.java
@@ -1,21 +1,24 @@
package io.a2a.spec;
-import static io.a2a.spec.Message.MESSAGE;
-import static io.a2a.spec.Task.TASK;
-
-import com.fasterxml.jackson.annotation.JsonSubTypes;
-import com.fasterxml.jackson.annotation.JsonTypeInfo;
-
-@JsonTypeInfo(
- use = JsonTypeInfo.Id.NAME,
- include = JsonTypeInfo.As.EXISTING_PROPERTY,
- property = "kind",
- visible = true
-)
-@JsonSubTypes({
- @JsonSubTypes.Type(value = Task.class, name = TASK),
- @JsonSubTypes.Type(value = Message.class, name = MESSAGE)
-})
+/**
+ * Interface for events that can be returned from non-streaming A2A Protocol operations.
+ *
+ * EventKind represents events that are suitable for synchronous request-response patterns.
+ * These events provide complete state information and are typically returned as the final
+ * result of an operation.
+ *
+ * EventKind implementations use polymorphic JSON serialization with the "kind" discriminator
+ * to determine the concrete type during deserialization.
+ *
+ * Permitted implementations:
+ *
+ * - {@link Task} - Complete task state with status and artifacts
+ * - {@link Message} - Full message with all content parts
+ *
+ *
+ * @see StreamingEventKind
+ * @see Event
+ */
public interface EventKind {
String getKind();
diff --git a/spec/src/main/java/io/a2a/spec/FileContent.java b/spec/src/main/java/io/a2a/spec/FileContent.java
index f9609fb8b..c1d631e5c 100644
--- a/spec/src/main/java/io/a2a/spec/FileContent.java
+++ b/spec/src/main/java/io/a2a/spec/FileContent.java
@@ -1,8 +1,29 @@
package io.a2a.spec;
-import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
-
-@JsonDeserialize(using = FileContentDeserializer.class)
+/**
+ * Sealed interface representing file content in the A2A Protocol.
+ *
+ * FileContent provides a polymorphic abstraction for file data, allowing files to be
+ * represented either as embedded binary content or as URI references. This flexibility
+ * enables different strategies for file transmission based on size, security, and
+ * accessibility requirements.
+ *
+ * The sealed interface permits only two implementations:
+ *
+ * - {@link FileWithBytes} - File content embedded as base64-encoded bytes (for small files or inline data)
+ * - {@link FileWithUri} - File content referenced by URI (for large files or external resources)
+ *
+ *
+ * Both implementations must provide:
+ *
+ * - MIME type - Describes the file format (e.g., "image/png", "application/pdf")
+ * - File name - The original or display name for the file
+ *
+ *
+ * @see FilePart
+ * @see FileWithBytes
+ * @see FileWithUri
+ */
public sealed interface FileContent permits FileWithBytes, FileWithUri {
String mimeType();
diff --git a/spec/src/main/java/io/a2a/spec/FileContentDeserializer.java b/spec/src/main/java/io/a2a/spec/FileContentDeserializer.java
deleted file mode 100644
index aa763db42..000000000
--- a/spec/src/main/java/io/a2a/spec/FileContentDeserializer.java
+++ /dev/null
@@ -1,38 +0,0 @@
-package io.a2a.spec;
-
-import java.io.IOException;
-
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.DeserializationContext;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
-
-public class FileContentDeserializer extends StdDeserializer {
-
- public FileContentDeserializer() {
- this(null);
- }
-
- public FileContentDeserializer(Class vc) {
- super(vc);
- }
-
- @Override
- public FileContent deserialize(JsonParser jsonParser, DeserializationContext context)
- throws IOException, JsonProcessingException {
- JsonNode node = jsonParser.getCodec().readTree(jsonParser);
- JsonNode mimeType = node.get("mimeType");
- JsonNode name = node.get("name");
- JsonNode bytes = node.get("bytes");
- if (bytes != null) {
- return new FileWithBytes(mimeType != null ? mimeType.asText() : null,
- name != null ? name.asText() : null, bytes.asText());
- } else if (node.has("uri")) {
- return new FileWithUri(mimeType != null ? mimeType.asText() : null,
- name != null ? name.asText() : null, node.get("uri").asText());
- } else {
- throw new IOException("Invalid file format: missing 'bytes' or 'uri'");
- }
- }
-}
diff --git a/spec/src/main/java/io/a2a/spec/FilePart.java b/spec/src/main/java/io/a2a/spec/FilePart.java
index 79bd2e5e8..fae1788e3 100644
--- a/spec/src/main/java/io/a2a/spec/FilePart.java
+++ b/spec/src/main/java/io/a2a/spec/FilePart.java
@@ -2,11 +2,6 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.FilePart.FILE;
@@ -15,9 +10,6 @@
* Represents a file segment within a message or artifact. The file content can be
* provided either directly as bytes or as a URI.
*/
-@JsonTypeName(FILE)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class FilePart extends Part {
public static final String FILE = "file";
@@ -29,8 +21,7 @@ public FilePart(FileContent file) {
this(file, null);
}
- @JsonCreator
- public FilePart(@JsonProperty("file") FileContent file, @JsonProperty("metadata") Map metadata) {
+ public FilePart(FileContent file, Map metadata) {
Assert.checkNotNullParam("file", file);
this.file = file;
this.metadata = metadata;
diff --git a/spec/src/main/java/io/a2a/spec/FileWithBytes.java b/spec/src/main/java/io/a2a/spec/FileWithBytes.java
index 782bc2c02..01ccef127 100644
--- a/spec/src/main/java/io/a2a/spec/FileWithBytes.java
+++ b/spec/src/main/java/io/a2a/spec/FileWithBytes.java
@@ -1,12 +1,7 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
/**
* Represents a file with its content provided directly as a base64-encoded string.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record FileWithBytes(String mimeType, String name, String bytes) implements FileContent {
}
diff --git a/spec/src/main/java/io/a2a/spec/FileWithUri.java b/spec/src/main/java/io/a2a/spec/FileWithUri.java
index afb3a87d8..e1edd4bd2 100644
--- a/spec/src/main/java/io/a2a/spec/FileWithUri.java
+++ b/spec/src/main/java/io/a2a/spec/FileWithUri.java
@@ -1,13 +1,8 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
/**
* Represents a file with its content located at a specific URI.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record FileWithUri(String mimeType, String name, String uri) implements FileContent {
}
diff --git a/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardRequest.java b/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardRequest.java
index 9d561c2d2..4afe2d029 100644
--- a/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardRequest.java
+++ b/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardRequest.java
@@ -2,10 +2,6 @@
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
import io.a2a.util.Assert;
import io.a2a.util.Utils;
@@ -13,15 +9,11 @@
/**
* Represents a JSON-RPC request for the `agent/getAuthenticatedExtendedCard` method.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class GetAuthenticatedExtendedCardRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "agent/getAuthenticatedExtendedCard";
- @JsonCreator
- public GetAuthenticatedExtendedCardRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") Void params) {
+ public GetAuthenticatedExtendedCardRequest(String jsonrpc, Object id, String method, Void params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardResponse.java b/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardResponse.java
index ec624e77d..48f380f12 100644
--- a/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardResponse.java
+++ b/spec/src/main/java/io/a2a/spec/GetAuthenticatedExtendedCardResponse.java
@@ -1,21 +1,11 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* A response for the `agent/getAuthenticatedExtendedCard` method.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class GetAuthenticatedExtendedCardResponse extends JSONRPCResponse {
- @JsonCreator
- public GetAuthenticatedExtendedCardResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") AgentCard result,
- @JsonProperty("error") JSONRPCError error) {
+ public GetAuthenticatedExtendedCardResponse(String jsonrpc, Object id, AgentCard result, JSONRPCError error) {
super(jsonrpc, id, result, error, AgentCard.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigParams.java b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigParams.java
index 627feff34..2836e2065 100644
--- a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigParams.java
+++ b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigParams.java
@@ -2,8 +2,6 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
import org.jspecify.annotations.Nullable;
@@ -11,8 +9,6 @@
/**
* Parameters for fetching a pushNotificationConfiguration associated with a Task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record GetTaskPushNotificationConfigParams(String id, @Nullable String pushNotificationConfigId, @Nullable Map metadata) {
public GetTaskPushNotificationConfigParams {
diff --git a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java
index b353e0cc8..4f1ef9e88 100644
--- a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java
+++ b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigRequest.java
@@ -1,9 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
import io.a2a.util.Assert;
import io.a2a.util.Utils;
@@ -12,15 +8,11 @@
/**
* A get task push notification request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class GetTaskPushNotificationConfigRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "tasks/pushNotificationConfig/get";
- @JsonCreator
- public GetTaskPushNotificationConfigRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") GetTaskPushNotificationConfigParams params) {
+ public GetTaskPushNotificationConfigRequest( String jsonrpc, Object id, String method, GetTaskPushNotificationConfigParams params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigResponse.java b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigResponse.java
index 116799a9e..83a125925 100644
--- a/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigResponse.java
+++ b/spec/src/main/java/io/a2a/spec/GetTaskPushNotificationConfigResponse.java
@@ -1,21 +1,11 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* A response for a get task push notification request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class GetTaskPushNotificationConfigResponse extends JSONRPCResponse {
- @JsonCreator
- public GetTaskPushNotificationConfigResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") TaskPushNotificationConfig result,
- @JsonProperty("error") JSONRPCError error) {
+ public GetTaskPushNotificationConfigResponse(String jsonrpc, Object id, TaskPushNotificationConfig result, JSONRPCError error) {
super(jsonrpc, id, result, error, TaskPushNotificationConfig.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/GetTaskRequest.java b/spec/src/main/java/io/a2a/spec/GetTaskRequest.java
index f31237af0..7b7fb8803 100644
--- a/spec/src/main/java/io/a2a/spec/GetTaskRequest.java
+++ b/spec/src/main/java/io/a2a/spec/GetTaskRequest.java
@@ -4,25 +4,17 @@
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
import io.a2a.util.Assert;
/**
* A get task request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class GetTaskRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "tasks/get";
- @JsonCreator
- public GetTaskRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") TaskQueryParams params) {
+ public GetTaskRequest(String jsonrpc, Object id, String method, TaskQueryParams params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/GetTaskResponse.java b/spec/src/main/java/io/a2a/spec/GetTaskResponse.java
index 0d27a8e68..f5e6fa2ee 100644
--- a/spec/src/main/java/io/a2a/spec/GetTaskResponse.java
+++ b/spec/src/main/java/io/a2a/spec/GetTaskResponse.java
@@ -1,20 +1,11 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* The response for a get task request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class GetTaskResponse extends JSONRPCResponse {
- @JsonCreator
- public GetTaskResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") Task result, @JsonProperty("error") JSONRPCError error) {
+ public GetTaskResponse(String jsonrpc, Object id, Task result, JSONRPCError error) {
super(jsonrpc, id, result, error, Task.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java b/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java
index 408fd2605..0323d3fa9 100644
--- a/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java
@@ -1,11 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.HTTPAuthSecurityScheme.HTTP;
@@ -13,9 +7,6 @@
/**
* Defines a security scheme using HTTP authentication.
*/
-@JsonTypeName(HTTP)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class HTTPAuthSecurityScheme implements SecurityScheme {
public static final String HTTP = "http";
@@ -28,12 +19,10 @@ public HTTPAuthSecurityScheme(String bearerFormat, String scheme, String descrip
this(bearerFormat, scheme, description, HTTP);
}
- @JsonCreator
- public HTTPAuthSecurityScheme(@JsonProperty("bearerFormat") String bearerFormat, @JsonProperty("scheme") String scheme,
- @JsonProperty("description") String description, @JsonProperty("type") String type) {
+ public HTTPAuthSecurityScheme(String bearerFormat, String scheme, String description, String type) {
Assert.checkNotNullParam("scheme", scheme);
Assert.checkNotNullParam("type", type);
- if (! type.equals(HTTP)) {
+ if (! HTTP.equals(type)) {
throw new IllegalArgumentException("Invalid type for HTTPAuthSecurityScheme");
}
this.bearerFormat = bearerFormat;
diff --git a/spec/src/main/java/io/a2a/spec/IdJsonMappingException.java b/spec/src/main/java/io/a2a/spec/IdJsonMappingException.java
index 15e0b07b1..00270f909 100644
--- a/spec/src/main/java/io/a2a/spec/IdJsonMappingException.java
+++ b/spec/src/main/java/io/a2a/spec/IdJsonMappingException.java
@@ -1,18 +1,18 @@
package io.a2a.spec;
-import com.fasterxml.jackson.databind.JsonMappingException;
+import io.a2a.json.JsonMappingException;
public class IdJsonMappingException extends JsonMappingException {
Object id;
public IdJsonMappingException(String msg, Object id) {
- super(null, msg);
+ super(msg);
this.id = id;
}
public IdJsonMappingException(String msg, Throwable cause, Object id) {
- super(null, msg, cause);
+ super(msg, cause);
this.id = id;
}
diff --git a/spec/src/main/java/io/a2a/spec/ImplicitOAuthFlow.java b/spec/src/main/java/io/a2a/spec/ImplicitOAuthFlow.java
index 8e2d529ea..cd2ef6235 100644
--- a/spec/src/main/java/io/a2a/spec/ImplicitOAuthFlow.java
+++ b/spec/src/main/java/io/a2a/spec/ImplicitOAuthFlow.java
@@ -2,16 +2,12 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Defines configuration details for the OAuth 2.0 Implicit flow.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record ImplicitOAuthFlow(String authorizationUrl, String refreshUrl, Map scopes) {
public ImplicitOAuthFlow {
diff --git a/spec/src/main/java/io/a2a/spec/InternalError.java b/spec/src/main/java/io/a2a/spec/InternalError.java
index ae52ecb70..f319c43ea 100644
--- a/spec/src/main/java/io/a2a/spec/InternalError.java
+++ b/spec/src/main/java/io/a2a/spec/InternalError.java
@@ -2,27 +2,17 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
/**
* An error indicating an internal error on the server.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class InternalError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32603;
+ public final static Integer DEFAULT_CODE = A2AErrorCodes.INTERNAL_ERROR_CODE;
- @JsonCreator
- public InternalError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ public InternalError(Integer code, String message, Object data) {
super(
- defaultIfNull(code, DEFAULT_CODE),
+ defaultIfNull(code, A2AErrorCodes.INTERNAL_ERROR_CODE),
defaultIfNull(message, "Internal Error"),
data);
}
diff --git a/spec/src/main/java/io/a2a/spec/InvalidAgentResponseError.java b/spec/src/main/java/io/a2a/spec/InvalidAgentResponseError.java
index faab71a96..d96e2d870 100644
--- a/spec/src/main/java/io/a2a/spec/InvalidAgentResponseError.java
+++ b/spec/src/main/java/io/a2a/spec/InvalidAgentResponseError.java
@@ -2,28 +2,48 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
/**
- * An A2A-specific error indicating that the agent returned a response that
- * does not conform to the specification for the current method.
+ * A2A Protocol error indicating that an agent returned a response not conforming to protocol specifications.
+ *
+ * This error is typically raised by client implementations when validating agent responses.
+ * It indicates that the agent's response structure, content, or format violates the A2A Protocol
+ * requirements for the invoked method.
+ *
+ * Common violations:
+ *
+ * - Missing required fields in response objects
+ * - Invalid field types or values
+ * - Malformed event stream data
+ * - Response doesn't match declared agent capabilities
+ *
+ *
+ * Corresponds to A2A-specific error code {@code -32006}.
+ *
+ * Usage example:
+ *
{@code
+ * SendMessageResponse response = client.sendMessage(request);
+ * if (response.task() == null) {
+ * throw new InvalidAgentResponseError(
+ * null,
+ * "Response missing required 'task' field",
+ * null
+ * );
+ * }
+ * }
+ *
+ * @see JSONRPCResponse for response structure
+ * @see SendMessageResponse for message send response
+ * @see A2A Protocol Specification
+
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class InvalidAgentResponseError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32006;
+ public final static Integer DEFAULT_CODE = A2AErrorCodes.INVALID_AGENT_RESPONSE_ERROR_CODE;
- @JsonCreator
- public InvalidAgentResponseError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ public InvalidAgentResponseError(Integer code, String message, Object data) {
super(
- defaultIfNull(code, DEFAULT_CODE),
+ defaultIfNull(code, A2AErrorCodes.INVALID_AGENT_RESPONSE_ERROR_CODE),
defaultIfNull(message, "Invalid agent response"),
data);
}
diff --git a/spec/src/main/java/io/a2a/spec/InvalidParamsError.java b/spec/src/main/java/io/a2a/spec/InvalidParamsError.java
index c71ea14bf..eb067eec5 100644
--- a/spec/src/main/java/io/a2a/spec/InvalidParamsError.java
+++ b/spec/src/main/java/io/a2a/spec/InvalidParamsError.java
@@ -2,27 +2,40 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
- * An error indicating that the method parameters are invalid.
+ * JSON-RPC error indicating that method parameters are invalid or missing required fields.
+ *
+ * This error is returned when a JSON-RPC method is called with parameters that fail validation.
+ * Common causes include:
+ *
+ * - Missing required parameters
+ * - Parameters of incorrect type
+ * - Parameter values outside acceptable ranges
+ * - Malformed parameter structures
+ *
+ *
+ * Corresponds to JSON-RPC 2.0 error code {@code -32602}.
+ *
+ * Usage example:
+ *
{@code
+ * // Default error with standard message
+ * throw new InvalidParamsError();
+ *
+ * // Custom error message
+ * throw new InvalidParamsError("taskId parameter is required");
+ * }
+ *
+ * @see JSONRPCError for the base error class
+ * @see A2AError for the error marker interface
+ * @see JSON-RPC 2.0 Error Codes
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class InvalidParamsError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32602;
+ public final static Integer DEFAULT_CODE = A2AErrorCodes.INVALID_PARAMS_ERROR_CODE;
- @JsonCreator
- public InvalidParamsError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ public InvalidParamsError(Integer code, String message, Object data) {
super(
- defaultIfNull(code, DEFAULT_CODE),
+ defaultIfNull(code, A2AErrorCodes.INVALID_PARAMS_ERROR_CODE),
defaultIfNull(message, "Invalid parameters"),
data);
}
diff --git a/spec/src/main/java/io/a2a/spec/InvalidRequestError.java b/spec/src/main/java/io/a2a/spec/InvalidRequestError.java
index 4d9e50779..66d9ddb05 100644
--- a/spec/src/main/java/io/a2a/spec/InvalidRequestError.java
+++ b/spec/src/main/java/io/a2a/spec/InvalidRequestError.java
@@ -2,31 +2,45 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
/**
- * An error indicating that the JSON sent is not a valid Request object.
+ * JSON-RPC error indicating that the request payload is not a valid JSON-RPC Request object.
+ *
+ * This error is returned when the JSON-RPC request fails structural validation.
+ * Common causes include:
+ *
+ * - Missing required JSON-RPC fields (jsonrpc, method, id)
+ * - Invalid JSON-RPC version (must be "2.0")
+ * - Malformed request structure
+ * - Type mismatches in required fields
+ *
+ *
+ * Corresponds to JSON-RPC 2.0 error code {@code -32600}.
+ *
+ * Usage example:
+ *
{@code
+ * // Default error with standard message
+ * throw new InvalidRequestError();
+ *
+ * // Custom error message
+ * throw new InvalidRequestError("Missing 'method' field in request");
+ * }
+ *
+ * @see JSONRPCError for the base error class
+ * @see A2AError for the error marker interface
+ * @see JSON-RPC 2.0 Error Codes
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class InvalidRequestError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32600;
+ public final static Integer DEFAULT_CODE = A2AErrorCodes.INVALID_REQUEST_ERROR_CODE;
public InvalidRequestError() {
this(null, null, null);
}
- @JsonCreator
- public InvalidRequestError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ public InvalidRequestError(Integer code, String message, Object data) {
super(
- defaultIfNull(code, DEFAULT_CODE),
+ defaultIfNull(code, A2AErrorCodes.INVALID_REQUEST_ERROR_CODE),
defaultIfNull(message, "Request payload validation error"),
data);
}
diff --git a/spec/src/main/java/io/a2a/spec/JSONErrorResponse.java b/spec/src/main/java/io/a2a/spec/JSONErrorResponse.java
index 3029f5394..8823f9bd3 100644
--- a/spec/src/main/java/io/a2a/spec/JSONErrorResponse.java
+++ b/spec/src/main/java/io/a2a/spec/JSONErrorResponse.java
@@ -1,9 +1,19 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
+/**
+ * A simplified error response wrapper for non-JSON-RPC error scenarios.
+ *
+ * This record provides a lightweight error response format for cases where
+ * a full JSON-RPC error structure is not appropriate, such as HTTP-level
+ * errors or transport-layer failures.
+ *
+ * Unlike {@link JSONRPCErrorResponse}, this is not part of the JSON-RPC 2.0
+ * specification but serves as a utility for simpler error reporting in the
+ * A2A Java SDK implementation.
+ *
+ * @param error a human-readable error message
+ * @see JSONRPCErrorResponse
+ * @see JSONRPCError
+ */
public record JSONErrorResponse(String error) {
}
diff --git a/spec/src/main/java/io/a2a/spec/JSONParseError.java b/spec/src/main/java/io/a2a/spec/JSONParseError.java
index d596c0701..acec50ca7 100644
--- a/spec/src/main/java/io/a2a/spec/JSONParseError.java
+++ b/spec/src/main/java/io/a2a/spec/JSONParseError.java
@@ -1,17 +1,31 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
import static io.a2a.util.Utils.defaultIfNull;
/**
- * An error indicating that the server received invalid JSON.
+ * JSON-RPC error indicating that the server received invalid JSON that could not be parsed.
+ *
+ * This error is returned when the request payload is not valid JSON, such as malformed syntax,
+ * unexpected tokens, or encoding issues. This is distinct from {@link InvalidRequestError},
+ * which indicates structurally valid JSON that doesn't conform to the JSON-RPC specification.
+ *
+ * Corresponds to JSON-RPC 2.0 error code {@code -32700}.
+ *
+ * Usage example:
+ *
{@code
+ * try {
+ * objectMapper.readValue(payload, JSONRPCRequest.class);
+ * } catch (io.a2a.json.JsonProcessingException e) {
+ * throw new JSONParseError("Malformed JSON: " + e.getMessage());
+ * }
+ * }
+ *
+ * @see JSONRPCError for the base error class
+ * @see A2AError for the error marker interface
+ * @see InvalidRequestError for structurally valid but invalid requests
+ * @see JSON-RPC 2.0 Error Codes
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class JSONParseError extends JSONRPCError implements A2AError {
public final static Integer DEFAULT_CODE = -32700;
@@ -24,11 +38,10 @@ public JSONParseError(String message) {
this(null, message, null);
}
- @JsonCreator
public JSONParseError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ Integer code,
+ String message,
+ Object data) {
super(
defaultIfNull(code, DEFAULT_CODE),
defaultIfNull(message, "Invalid JSON payload"),
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCError.java b/spec/src/main/java/io/a2a/spec/JSONRPCError.java
index 776b9c8c6..766e54fda 100644
--- a/spec/src/main/java/io/a2a/spec/JSONRPCError.java
+++ b/spec/src/main/java/io/a2a/spec/JSONRPCError.java
@@ -1,31 +1,27 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
-import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import io.a2a.util.Assert;
/**
* Represents a JSON-RPC 2.0 Error object, included in an error response.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonDeserialize(using = JSONRPCErrorDeserializer.class)
-@JsonSerialize(using = JSONRPCErrorSerializer.class)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class JSONRPCError extends Error implements Event, A2AError {
private final Integer code;
private final Object data;
- @JsonCreator
- public JSONRPCError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ /**
+ * Constructs a JSON-RPC error with the specified code, message, and optional data.
+ *
+ * This constructor is used by Jackson for JSON deserialization.
+ *
+ * @param code the numeric error code (required, see JSON-RPC 2.0 spec for standard codes)
+ * @param message the human-readable error message (required)
+ * @param data additional error information, structure defined by the error code (optional)
+ * @throws IllegalArgumentException if code or message is null
+ */
+ public JSONRPCError(Integer code, String message, Object data) {
super(message);
Assert.checkNotNullParam("code", code);
Assert.checkNotNullParam("message", message);
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCErrorDeserializer.java b/spec/src/main/java/io/a2a/spec/JSONRPCErrorDeserializer.java
deleted file mode 100644
index 229abf55d..000000000
--- a/spec/src/main/java/io/a2a/spec/JSONRPCErrorDeserializer.java
+++ /dev/null
@@ -1,59 +0,0 @@
-package io.a2a.spec;
-
-import java.io.IOException;
-import java.util.HashMap;
-import java.util.Map;
-
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.DeserializationContext;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
-
-public class JSONRPCErrorDeserializer extends StdDeserializer {
-
- private static final Map> ERROR_MAP = new HashMap<>();
-
- static {
- ERROR_MAP.put(JSONParseError.DEFAULT_CODE, JSONParseError::new);
- ERROR_MAP.put(InvalidRequestError.DEFAULT_CODE, InvalidRequestError::new);
- ERROR_MAP.put(MethodNotFoundError.DEFAULT_CODE, MethodNotFoundError::new);
- ERROR_MAP.put(InvalidParamsError.DEFAULT_CODE, InvalidParamsError::new);
- ERROR_MAP.put(InternalError.DEFAULT_CODE, InternalError::new);
- ERROR_MAP.put(PushNotificationNotSupportedError.DEFAULT_CODE, PushNotificationNotSupportedError::new);
- ERROR_MAP.put(UnsupportedOperationError.DEFAULT_CODE, UnsupportedOperationError::new);
- ERROR_MAP.put(ContentTypeNotSupportedError.DEFAULT_CODE, ContentTypeNotSupportedError::new);
- ERROR_MAP.put(InvalidAgentResponseError.DEFAULT_CODE, InvalidAgentResponseError::new);
- ERROR_MAP.put(TaskNotCancelableError.DEFAULT_CODE, TaskNotCancelableError::new);
- ERROR_MAP.put(TaskNotFoundError.DEFAULT_CODE, TaskNotFoundError::new);
- }
-
- public JSONRPCErrorDeserializer() {
- this(null);
- }
-
- public JSONRPCErrorDeserializer(Class vc) {
- super(vc);
- }
-
- @Override
- public JSONRPCError deserialize(JsonParser jsonParser, DeserializationContext context)
- throws IOException, JsonProcessingException {
- JsonNode node = jsonParser.getCodec().readTree(jsonParser);
- int code = node.get("code").asInt();
- String message = node.get("message").asText();
- JsonNode dataNode = node.get("data");
- Object data = dataNode != null ? jsonParser.getCodec().treeToValue(dataNode, Object.class) : null;
- TriFunction constructor = ERROR_MAP.get(code);
- if (constructor != null) {
- return constructor.apply(code, message, data);
- } else {
- return new JSONRPCError(code, message, data);
- }
- }
-
- @FunctionalInterface
- private interface TriFunction {
- R apply(A a, B b, C c);
- }
-}
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCErrorResponse.java b/spec/src/main/java/io/a2a/spec/JSONRPCErrorResponse.java
index ea7846655..f24271c46 100644
--- a/spec/src/main/java/io/a2a/spec/JSONRPCErrorResponse.java
+++ b/spec/src/main/java/io/a2a/spec/JSONRPCErrorResponse.java
@@ -1,22 +1,24 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
import io.a2a.util.Assert;
/**
* A JSON RPC error response.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class JSONRPCErrorResponse extends JSONRPCResponse {
- @JsonCreator
- public JSONRPCErrorResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") Void result, @JsonProperty("error") JSONRPCError error) {
+ /**
+ * Constructs a JSON-RPC error response with all fields.
+ *
+ * This constructor is used for JSON deserialization.
+ *
+ * @param jsonrpc the JSON-RPC version (must be "2.0")
+ * @param id the request ID, or null if the ID could not be determined from the request
+ * @param result must be null for error responses
+ * @param error the error object describing what went wrong (required)
+ * @throws IllegalArgumentException if error is null
+ */
+ public JSONRPCErrorResponse(String jsonrpc, Object id, Void result, JSONRPCError error) {
super(jsonrpc, id, result, error, Void.class);
Assert.checkNotNullParam("error", error);
}
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCErrorSerializer.java b/spec/src/main/java/io/a2a/spec/JSONRPCErrorSerializer.java
deleted file mode 100644
index 87b427548..000000000
--- a/spec/src/main/java/io/a2a/spec/JSONRPCErrorSerializer.java
+++ /dev/null
@@ -1,29 +0,0 @@
-package io.a2a.spec;
-
-import java.io.IOException;
-
-import com.fasterxml.jackson.core.JsonGenerator;
-import com.fasterxml.jackson.databind.SerializerProvider;
-import com.fasterxml.jackson.databind.ser.std.StdSerializer;
-
-public class JSONRPCErrorSerializer extends StdSerializer {
-
- public JSONRPCErrorSerializer() {
- this(null);
- }
-
- public JSONRPCErrorSerializer(Class vc) {
- super(vc);
- }
-
- @Override
- public void serialize(JSONRPCError value, JsonGenerator gen, SerializerProvider provider) throws IOException {
- gen.writeStartObject();
- gen.writeNumberField("code", value.getCode());
- gen.writeStringField("message", value.getMessage());
- if (value.getData() != null) {
- gen.writeObjectField("data", value.getData());
- }
- gen.writeEndObject();
- }
-}
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCRequest.java b/spec/src/main/java/io/a2a/spec/JSONRPCRequest.java
index a88de90f1..45e2b6883 100644
--- a/spec/src/main/java/io/a2a/spec/JSONRPCRequest.java
+++ b/spec/src/main/java/io/a2a/spec/JSONRPCRequest.java
@@ -2,16 +2,11 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
import io.a2a.util.Assert;
/**
* Represents a JSONRPC request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public abstract sealed class JSONRPCRequest implements JSONRPCMessage permits NonStreamingJSONRPCRequest, StreamingJSONRPCRequest {
protected String jsonrpc;
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCRequestDeserializerBase.java b/spec/src/main/java/io/a2a/spec/JSONRPCRequestDeserializerBase.java
deleted file mode 100644
index 2af7d0513..000000000
--- a/spec/src/main/java/io/a2a/spec/JSONRPCRequestDeserializerBase.java
+++ /dev/null
@@ -1,89 +0,0 @@
-package io.a2a.spec;
-
-import static io.a2a.util.Utils.OBJECT_MAPPER;
-
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.JsonMappingException;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
-
-public abstract class JSONRPCRequestDeserializerBase extends StdDeserializer> {
-
- public JSONRPCRequestDeserializerBase() {
- this(null);
- }
-
- public JSONRPCRequestDeserializerBase(Class vc) {
- super(vc);
- }
-
- protected T getAndValidateParams(JsonNode paramsNode, JsonParser jsonParser, JsonNode node, Class paramsType) throws JsonMappingException {
- if (paramsNode == null) {
- return null;
- }
- try {
- return OBJECT_MAPPER.treeToValue(paramsNode, paramsType);
- } catch (JsonProcessingException e) {
- throw new InvalidParamsJsonMappingException("Invalid params", e, getIdIfPossible(node, jsonParser));
- }
- }
-
- protected String getAndValidateJsonrpc(JsonNode treeNode, JsonParser jsonParser) throws JsonMappingException {
- JsonNode jsonrpcNode = treeNode.get("jsonrpc");
- if (jsonrpcNode == null || ! jsonrpcNode.asText().equals(JSONRPCMessage.JSONRPC_VERSION)) {
- throw new IdJsonMappingException("Invalid JSON-RPC protocol version", getIdIfPossible(treeNode, jsonParser));
- }
- return jsonrpcNode.asText();
- }
-
- protected String getAndValidateMethod(JsonNode treeNode, JsonParser jsonParser) throws JsonMappingException {
- JsonNode methodNode = treeNode.get("method");
- if (methodNode == null) {
- throw new IdJsonMappingException("Missing method", getIdIfPossible(treeNode, jsonParser));
- }
- String method = methodNode.asText();
- if (! isValidMethodName(method)) {
- throw new MethodNotFoundJsonMappingException("Invalid method", getIdIfPossible(treeNode, jsonParser));
- }
- return method;
- }
-
- protected Object getAndValidateId(JsonNode treeNode, JsonParser jsonParser) throws JsonProcessingException {
- JsonNode idNode = treeNode.get("id");
- Object id = null;
- if (idNode != null) {
- if (idNode.isTextual()) {
- id = OBJECT_MAPPER.treeToValue(idNode, String.class);
- } else if (idNode.isNumber()) {
- id = OBJECT_MAPPER.treeToValue(idNode, Integer.class);
- } else {
- throw new JsonMappingException(jsonParser, "Invalid id");
- }
- }
- return id;
- }
-
- protected Object getIdIfPossible(JsonNode treeNode, JsonParser jsonParser) {
- try {
- return getAndValidateId(treeNode, jsonParser);
- } catch (JsonProcessingException e) {
- // id can't be determined
- return null;
- }
- }
-
- protected static boolean isValidMethodName(String methodName) {
- return methodName != null && (methodName.equals(CancelTaskRequest.METHOD)
- || methodName.equals(GetTaskRequest.METHOD)
- || methodName.equals(GetTaskPushNotificationConfigRequest.METHOD)
- || methodName.equals(SetTaskPushNotificationConfigRequest.METHOD)
- || methodName.equals(TaskResubscriptionRequest.METHOD)
- || methodName.equals(SendMessageRequest.METHOD)
- || methodName.equals(SendStreamingMessageRequest.METHOD)
- || methodName.equals(ListTaskPushNotificationConfigRequest.METHOD)
- || methodName.equals(DeleteTaskPushNotificationConfigRequest.METHOD)
- || methodName.equals(GetAuthenticatedExtendedCardRequest.METHOD));
-
- }
-}
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCResponse.java b/spec/src/main/java/io/a2a/spec/JSONRPCResponse.java
index be67a1e24..d4330d843 100644
--- a/spec/src/main/java/io/a2a/spec/JSONRPCResponse.java
+++ b/spec/src/main/java/io/a2a/spec/JSONRPCResponse.java
@@ -2,16 +2,11 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
import io.a2a.util.Assert;
/**
* Represents a JSONRPC response.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public abstract sealed class JSONRPCResponse implements JSONRPCMessage permits SendStreamingMessageResponse,
GetTaskResponse, CancelTaskResponse, SetTaskPushNotificationConfigResponse, GetTaskPushNotificationConfigResponse,
SendMessageResponse, DeleteTaskPushNotificationConfigResponse, ListTaskPushNotificationConfigResponse, JSONRPCErrorResponse,
diff --git a/spec/src/main/java/io/a2a/spec/JSONRPCVoidResponseSerializer.java b/spec/src/main/java/io/a2a/spec/JSONRPCVoidResponseSerializer.java
deleted file mode 100644
index 200bc4cd4..000000000
--- a/spec/src/main/java/io/a2a/spec/JSONRPCVoidResponseSerializer.java
+++ /dev/null
@@ -1,32 +0,0 @@
-package io.a2a.spec;
-
-import java.io.IOException;
-
-import com.fasterxml.jackson.core.JsonGenerator;
-import com.fasterxml.jackson.databind.SerializerProvider;
-import com.fasterxml.jackson.databind.ser.std.StdSerializer;
-import com.fasterxml.jackson.databind.type.TypeFactory;
-
-public class JSONRPCVoidResponseSerializer extends StdSerializer> {
-
- private static final JSONRPCErrorSerializer JSON_RPC_ERROR_SERIALIZER = new JSONRPCErrorSerializer();
-
- public JSONRPCVoidResponseSerializer() {
- super(TypeFactory.defaultInstance().constructParametricType(JSONRPCResponse.class,
- Void.class));
- }
-
- @Override
- public void serialize(JSONRPCResponse value, JsonGenerator gen, SerializerProvider provider) throws IOException {
- gen.writeStartObject();
- gen.writeStringField("jsonrpc", value.getJsonrpc());
- gen.writeObjectField("id", value.getId());
- if (value.getError() != null) {
- gen.writeFieldName("error");
- JSON_RPC_ERROR_SERIALIZER.serialize(value.getError(), gen, provider);
- } else {
- gen.writeNullField("result");
- }
- gen.writeEndObject();
- }
-}
diff --git a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java
index 5ebb12f76..2d04f36ce 100644
--- a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java
+++ b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java
@@ -2,16 +2,11 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
import io.a2a.util.Assert;
/**
* Parameters for getting list of pushNotificationConfigurations associated with a Task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record ListTaskPushNotificationConfigParams(String id, Map metadata) {
public ListTaskPushNotificationConfigParams {
diff --git a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigRequest.java b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigRequest.java
index 90ba0f1f5..8a4b75a1f 100644
--- a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigRequest.java
+++ b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigRequest.java
@@ -2,27 +2,17 @@
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
import io.a2a.util.Assert;
import io.a2a.util.Utils;
/**
* A list task push notification config request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class ListTaskPushNotificationConfigRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "tasks/pushNotificationConfig/list";
- @JsonCreator
- public ListTaskPushNotificationConfigRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method,
- @JsonProperty("params") ListTaskPushNotificationConfigParams params) {
+ public ListTaskPushNotificationConfigRequest(String jsonrpc, Object id, String method, ListTaskPushNotificationConfigParams params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigResponse.java b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigResponse.java
index cc610416e..5546f148c 100644
--- a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigResponse.java
+++ b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigResponse.java
@@ -2,22 +2,12 @@
import java.util.List;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* A response for a list task push notification config request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class ListTaskPushNotificationConfigResponse extends JSONRPCResponse> {
- @JsonCreator
- public ListTaskPushNotificationConfigResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") List result,
- @JsonProperty("error") JSONRPCError error) {
+ public ListTaskPushNotificationConfigResponse(String jsonrpc, Object id, List result, JSONRPCError error) {
super(jsonrpc, id, result, error, (Class>) (Class) List.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/Message.java b/spec/src/main/java/io/a2a/spec/Message.java
index dd7e860a5..9d08cb56c 100644
--- a/spec/src/main/java/io/a2a/spec/Message.java
+++ b/spec/src/main/java/io/a2a/spec/Message.java
@@ -4,13 +4,6 @@
import java.util.Map;
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
-import com.fasterxml.jackson.annotation.JsonValue;
-import com.fasterxml.jackson.core.type.TypeReference;
import io.a2a.util.Assert;
import static io.a2a.spec.Message.MESSAGE;
@@ -18,13 +11,8 @@
/**
* Represents a single message in the conversation between a user and an agent.
*/
-@JsonTypeName(MESSAGE)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class Message implements EventKind, StreamingEventKind {
- public static final TypeReference TYPE_REFERENCE = new TypeReference<>() {};
-
public static final String MESSAGE = "message";
private final Role role;
private final List> parts;
@@ -41,12 +29,11 @@ public Message(Role role, List> parts, String messageId, String contextI
this(role, parts, messageId, contextId, taskId, referenceTaskIds, metadata, extensions, MESSAGE);
}
- @JsonCreator
- public Message(@JsonProperty("role") Role role, @JsonProperty("parts") List> parts,
- @JsonProperty("messageId") String messageId, @JsonProperty("contextId") String contextId,
- @JsonProperty("taskId") String taskId, @JsonProperty("referenceTaskIds") List referenceTaskIds,
- @JsonProperty("metadata") Map metadata, @JsonProperty("extensions") List extensions,
- @JsonProperty("kind") String kind) {
+ public Message(Role role, List> parts,
+ String messageId, String contextId,
+ String taskId, List referenceTaskIds,
+ Map metadata, List extensions,
+ String kind) {
Assert.checkNotNullParam("kind", kind);
Assert.checkNotNullParam("parts", parts);
if (parts.isEmpty()) {
@@ -123,7 +110,11 @@ public enum Role {
this.role = role;
}
- @JsonValue
+ /**
+ * Returns the string representation of the role for JSON serialization.
+ *
+ * @return the role as a string ("user" or "agent")
+ */
public String asString() {
return this.role;
}
diff --git a/spec/src/main/java/io/a2a/spec/MessageSendConfiguration.java b/spec/src/main/java/io/a2a/spec/MessageSendConfiguration.java
index cbe72cfb1..d44ce494f 100644
--- a/spec/src/main/java/io/a2a/spec/MessageSendConfiguration.java
+++ b/spec/src/main/java/io/a2a/spec/MessageSendConfiguration.java
@@ -2,16 +2,12 @@
import java.util.List;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;
/**
* Defines configuration options for a `message/send` or `message/stream` request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record MessageSendConfiguration(List acceptedOutputModes, Integer historyLength,
PushNotificationConfig pushNotificationConfig, Boolean blocking) {
diff --git a/spec/src/main/java/io/a2a/spec/MessageSendParams.java b/spec/src/main/java/io/a2a/spec/MessageSendParams.java
index 7cba6f1ae..5914ef462 100644
--- a/spec/src/main/java/io/a2a/spec/MessageSendParams.java
+++ b/spec/src/main/java/io/a2a/spec/MessageSendParams.java
@@ -2,16 +2,12 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Defines the parameters for a request to send a message to an agent. This can be used
* to create a new task, continue an existing one, or restart a task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record MessageSendParams(Message message, MessageSendConfiguration configuration,
Map metadata) {
diff --git a/spec/src/main/java/io/a2a/spec/MethodNotFoundError.java b/spec/src/main/java/io/a2a/spec/MethodNotFoundError.java
index 5a46b336f..e8af3590a 100644
--- a/spec/src/main/java/io/a2a/spec/MethodNotFoundError.java
+++ b/spec/src/main/java/io/a2a/spec/MethodNotFoundError.java
@@ -1,33 +1,20 @@
package io.a2a.spec;
+import static io.a2a.spec.A2AErrorCodes.METHOD_NOT_FOUND_ERROR_CODE;
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* An error indicating that the requested method does not exist or is not available.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class MethodNotFoundError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32601;
+ public final static Integer DEFAULT_CODE = METHOD_NOT_FOUND_ERROR_CODE;
- @JsonCreator
- public MethodNotFoundError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
- super(
- defaultIfNull(code, DEFAULT_CODE),
- defaultIfNull(message, "Method not found"),
- data);
+ public MethodNotFoundError(Integer code, String message, Object data) {
+ super(defaultIfNull(code, METHOD_NOT_FOUND_ERROR_CODE), defaultIfNull(message, "Method not found"), data);
}
public MethodNotFoundError() {
- this(DEFAULT_CODE, null, null);
+ this(METHOD_NOT_FOUND_ERROR_CODE, null, null);
}
}
diff --git a/spec/src/main/java/io/a2a/spec/MutualTLSSecurityScheme.java b/spec/src/main/java/io/a2a/spec/MutualTLSSecurityScheme.java
index 37f5bd755..e0b6fb8e0 100644
--- a/spec/src/main/java/io/a2a/spec/MutualTLSSecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/MutualTLSSecurityScheme.java
@@ -1,10 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.MutualTLSSecurityScheme.MUTUAL_TLS;
@@ -12,9 +7,6 @@
/**
* Defines a security scheme using mTLS authentication.
*/
-@JsonTypeName(MUTUAL_TLS)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class MutualTLSSecurityScheme implements SecurityScheme {
public static final String MUTUAL_TLS = "mutualTLS";
@@ -29,9 +21,7 @@ public MutualTLSSecurityScheme() {
this(null, MUTUAL_TLS);
}
- @JsonCreator
- public MutualTLSSecurityScheme(@JsonProperty("description") String description,
- @JsonProperty("type") String type) {
+ public MutualTLSSecurityScheme(String description, String type) {
Assert.checkNotNullParam("type", type);
if (!type.equals(MUTUAL_TLS)) {
throw new IllegalArgumentException("Invalid type for MutualTLSSecurityScheme");
diff --git a/spec/src/main/java/io/a2a/spec/NonStreamingJSONRPCRequest.java b/spec/src/main/java/io/a2a/spec/NonStreamingJSONRPCRequest.java
index f3ac7d2cb..e969ce08e 100644
--- a/spec/src/main/java/io/a2a/spec/NonStreamingJSONRPCRequest.java
+++ b/spec/src/main/java/io/a2a/spec/NonStreamingJSONRPCRequest.java
@@ -1,15 +1,8 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
-
/**
* Represents a non-streaming JSON-RPC request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
-@JsonDeserialize(using = NonStreamingJSONRPCRequestDeserializer.class)
public abstract sealed class NonStreamingJSONRPCRequest extends JSONRPCRequest permits GetTaskRequest,
CancelTaskRequest, SetTaskPushNotificationConfigRequest, GetTaskPushNotificationConfigRequest,
SendMessageRequest, DeleteTaskPushNotificationConfigRequest, ListTaskPushNotificationConfigRequest,
diff --git a/spec/src/main/java/io/a2a/spec/NonStreamingJSONRPCRequestDeserializer.java b/spec/src/main/java/io/a2a/spec/NonStreamingJSONRPCRequestDeserializer.java
deleted file mode 100644
index 37366b9b7..000000000
--- a/spec/src/main/java/io/a2a/spec/NonStreamingJSONRPCRequestDeserializer.java
+++ /dev/null
@@ -1,58 +0,0 @@
-package io.a2a.spec;
-
-import java.io.IOException;
-
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.DeserializationContext;
-import com.fasterxml.jackson.databind.JsonNode;
-
-public class NonStreamingJSONRPCRequestDeserializer extends JSONRPCRequestDeserializerBase> {
-
- public NonStreamingJSONRPCRequestDeserializer() {
- this(null);
- }
-
- public NonStreamingJSONRPCRequestDeserializer(Class vc) {
- super(vc);
- }
-
- @Override
- public NonStreamingJSONRPCRequest deserialize(JsonParser jsonParser, DeserializationContext context)
- throws IOException, JsonProcessingException {
- JsonNode treeNode = jsonParser.getCodec().readTree(jsonParser);
- String jsonrpc = getAndValidateJsonrpc(treeNode, jsonParser);
- String method = getAndValidateMethod(treeNode, jsonParser);
- Object id = getAndValidateId(treeNode, jsonParser);
- JsonNode paramsNode = treeNode.get("params");
-
- switch (method) {
- case GetTaskRequest.METHOD:
- return new GetTaskRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, TaskQueryParams.class));
- case CancelTaskRequest.METHOD:
- return new CancelTaskRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, TaskIdParams.class));
- case SetTaskPushNotificationConfigRequest.METHOD:
- return new SetTaskPushNotificationConfigRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, TaskPushNotificationConfig.class));
- case GetTaskPushNotificationConfigRequest.METHOD:
- return new GetTaskPushNotificationConfigRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, GetTaskPushNotificationConfigParams.class));
- case SendMessageRequest.METHOD:
- return new SendMessageRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, MessageSendParams.class));
- case ListTaskPushNotificationConfigRequest.METHOD:
- return new ListTaskPushNotificationConfigRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, ListTaskPushNotificationConfigParams.class));
- case DeleteTaskPushNotificationConfigRequest.METHOD:
- return new DeleteTaskPushNotificationConfigRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, DeleteTaskPushNotificationConfigParams.class));
- case GetAuthenticatedExtendedCardRequest.METHOD:
- return new GetAuthenticatedExtendedCardRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, Void.class));
- default:
- throw new MethodNotFoundJsonMappingException("Invalid method", getIdIfPossible(treeNode, jsonParser));
- }
- }
-}
diff --git a/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java b/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java
index 9094eee7c..cd456864a 100644
--- a/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java
@@ -1,11 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.OAuth2SecurityScheme.OAUTH2;
@@ -13,9 +7,6 @@
/**
* Defines a security scheme using OAuth 2.0.
*/
-@JsonTypeName(OAUTH2)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class OAuth2SecurityScheme implements SecurityScheme {
public static final String OAUTH2 = "oauth2";
@@ -28,9 +19,7 @@ public OAuth2SecurityScheme(OAuthFlows flows, String description, String oauth2M
this(flows, description, oauth2MetadataUrl, OAUTH2);
}
- @JsonCreator
- public OAuth2SecurityScheme(@JsonProperty("flows") OAuthFlows flows, @JsonProperty("description") String description,
- @JsonProperty("oauth2MetadataUrl") String oauth2MetadataUrl, @JsonProperty("type") String type) {
+ public OAuth2SecurityScheme(OAuthFlows flows, String description, String oauth2MetadataUrl, String type) {
Assert.checkNotNullParam("flows", flows);
Assert.checkNotNullParam("type", type);
if (!type.equals(OAUTH2)) {
diff --git a/spec/src/main/java/io/a2a/spec/OAuthFlows.java b/spec/src/main/java/io/a2a/spec/OAuthFlows.java
index 8c5015893..849f84d41 100644
--- a/spec/src/main/java/io/a2a/spec/OAuthFlows.java
+++ b/spec/src/main/java/io/a2a/spec/OAuthFlows.java
@@ -1,13 +1,8 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
/**
* Defines the configuration for the supported OAuth 2.0 flows.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record OAuthFlows(AuthorizationCodeOAuthFlow authorizationCode, ClientCredentialsOAuthFlow clientCredentials,
ImplicitOAuthFlow implicit, PasswordOAuthFlow password) {
diff --git a/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java b/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java
index 01726d2ea..949fd2a68 100644
--- a/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java
@@ -1,10 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.OpenIdConnectSecurityScheme.OPENID_CONNECT;
@@ -12,9 +7,6 @@
/**
* Defines a security scheme using OpenID Connect.
*/
-@JsonTypeName(OPENID_CONNECT)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class OpenIdConnectSecurityScheme implements SecurityScheme {
public static final String OPENID_CONNECT = "openIdConnect";
@@ -26,9 +18,7 @@ public OpenIdConnectSecurityScheme(String openIdConnectUrl, String description)
this(openIdConnectUrl, description, OPENID_CONNECT);
}
- @JsonCreator
- public OpenIdConnectSecurityScheme(@JsonProperty("openIdConnectUrl") String openIdConnectUrl,
- @JsonProperty("description") String description, @JsonProperty("type") String type) {
+ public OpenIdConnectSecurityScheme(String openIdConnectUrl, String description, String type) {
Assert.checkNotNullParam("type", type);
Assert.checkNotNullParam("openIdConnectUrl", openIdConnectUrl);
if (!type.equals(OPENID_CONNECT)) {
diff --git a/spec/src/main/java/io/a2a/spec/Part.java b/spec/src/main/java/io/a2a/spec/Part.java
index 2bdfb69d1..e55577622 100644
--- a/spec/src/main/java/io/a2a/spec/Part.java
+++ b/spec/src/main/java/io/a2a/spec/Part.java
@@ -2,25 +2,10 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonSubTypes;
-import com.fasterxml.jackson.annotation.JsonTypeInfo;
-import com.fasterxml.jackson.annotation.JsonValue;
-
/**
* A fundamental unit with a Message or Artifact.
* @param the type of unit
*/
-@JsonTypeInfo(
- use = JsonTypeInfo.Id.NAME,
- include = JsonTypeInfo.As.EXISTING_PROPERTY,
- property = "kind",
- visible = true
-)
-@JsonSubTypes({
- @JsonSubTypes.Type(value = TextPart.class, name = TextPart.TEXT),
- @JsonSubTypes.Type(value = FilePart.class, name = FilePart.FILE),
- @JsonSubTypes.Type(value = DataPart.class, name = DataPart.DATA)
-})
public abstract class Part {
public enum Kind {
TEXT("text"),
@@ -33,7 +18,11 @@ public enum Kind {
this.kind = kind;
}
- @JsonValue
+ /**
+ * Returns the string representation of the kind for JSON serialization.
+ *
+ * @return the kind as a string
+ */
public String asString() {
return this.kind;
}
diff --git a/spec/src/main/java/io/a2a/spec/PasswordOAuthFlow.java b/spec/src/main/java/io/a2a/spec/PasswordOAuthFlow.java
index 424a4817f..e5de924cb 100644
--- a/spec/src/main/java/io/a2a/spec/PasswordOAuthFlow.java
+++ b/spec/src/main/java/io/a2a/spec/PasswordOAuthFlow.java
@@ -2,16 +2,11 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
import io.a2a.util.Assert;
/**
* Defines configuration details for the OAuth 2.0 Resource Owner Password flow.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record PasswordOAuthFlow(String refreshUrl, Map scopes, String tokenUrl) {
public PasswordOAuthFlow {
diff --git a/spec/src/main/java/io/a2a/spec/PushNotificationAuthenticationInfo.java b/spec/src/main/java/io/a2a/spec/PushNotificationAuthenticationInfo.java
index 1ef29ccd4..6263ac990 100644
--- a/spec/src/main/java/io/a2a/spec/PushNotificationAuthenticationInfo.java
+++ b/spec/src/main/java/io/a2a/spec/PushNotificationAuthenticationInfo.java
@@ -1,16 +1,11 @@
package io.a2a.spec;
import java.util.List;
-
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Defines authentication details for a push notification endpoint.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record PushNotificationAuthenticationInfo(List schemes, String credentials) {
public PushNotificationAuthenticationInfo {
diff --git a/spec/src/main/java/io/a2a/spec/PushNotificationConfig.java b/spec/src/main/java/io/a2a/spec/PushNotificationConfig.java
index fcffa2c7f..b5a9e1131 100644
--- a/spec/src/main/java/io/a2a/spec/PushNotificationConfig.java
+++ b/spec/src/main/java/io/a2a/spec/PushNotificationConfig.java
@@ -1,17 +1,11 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.core.type.TypeReference;
import io.a2a.util.Assert;
/**
* Defines the configuration for setting up push notifications for task updates.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record PushNotificationConfig(String url, String token, PushNotificationAuthenticationInfo authentication, String id) {
- public static final TypeReference TYPE_REFERENCE = new TypeReference<>() {};
public PushNotificationConfig {
Assert.checkNotNullParam("url", url);
diff --git a/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java b/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java
index c618e2b78..7397acd74 100644
--- a/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java
+++ b/spec/src/main/java/io/a2a/spec/PushNotificationNotSupportedError.java
@@ -2,16 +2,9 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* An A2A-specific error indicating that the agent does not support push notifications.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class PushNotificationNotSupportedError extends JSONRPCError {
public final static Integer DEFAULT_CODE = -32003;
@@ -20,11 +13,10 @@ public PushNotificationNotSupportedError() {
this(null, null, null);
}
- @JsonCreator
public PushNotificationNotSupportedError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ Integer code,
+ String message,
+ Object data) {
super(
defaultIfNull(code, DEFAULT_CODE),
defaultIfNull(message, "Push Notification is not supported"),
diff --git a/spec/src/main/java/io/a2a/spec/SecurityScheme.java b/spec/src/main/java/io/a2a/spec/SecurityScheme.java
index b3cc104e3..a39dfd314 100644
--- a/spec/src/main/java/io/a2a/spec/SecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/SecurityScheme.java
@@ -2,22 +2,6 @@
import static io.a2a.spec.APIKeySecurityScheme.API_KEY;
-import com.fasterxml.jackson.annotation.JsonSubTypes;
-import com.fasterxml.jackson.annotation.JsonTypeInfo;
-
-@JsonTypeInfo(
- use = JsonTypeInfo.Id.NAME,
- include = JsonTypeInfo.As.EXISTING_PROPERTY,
- property = "type",
- visible = true
-)
-@JsonSubTypes({
- @JsonSubTypes.Type(value = APIKeySecurityScheme.class, name = API_KEY),
- @JsonSubTypes.Type(value = HTTPAuthSecurityScheme.class, name = HTTPAuthSecurityScheme.HTTP),
- @JsonSubTypes.Type(value = OAuth2SecurityScheme.class, name = OAuth2SecurityScheme.OAUTH2),
- @JsonSubTypes.Type(value = OpenIdConnectSecurityScheme.class, name = OpenIdConnectSecurityScheme.OPENID_CONNECT),
- @JsonSubTypes.Type(value = MutualTLSSecurityScheme.class, name = MutualTLSSecurityScheme.MUTUAL_TLS)
-})
/**
* Defines a security scheme that can be used to secure an agent's endpoints.
* This is a discriminated union type based on the OpenAPI 3.0 Security Scheme Object.
diff --git a/spec/src/main/java/io/a2a/spec/SendMessageRequest.java b/spec/src/main/java/io/a2a/spec/SendMessageRequest.java
index d31f364e4..a58ce0890 100644
--- a/spec/src/main/java/io/a2a/spec/SendMessageRequest.java
+++ b/spec/src/main/java/io/a2a/spec/SendMessageRequest.java
@@ -4,25 +4,28 @@
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
import io.a2a.util.Assert;
/**
* Used to send a message request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class SendMessageRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "message/send";
- @JsonCreator
- public SendMessageRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") MessageSendParams params) {
+ /**
+ * Constructs a SendMessageRequest with the specified JSON-RPC fields.
+ *
+ * This constructor is used for JSON deserialization and validates
+ * that the method name is exactly "SendMessage".
+ *
+ * @param jsonrpc the JSON-RPC version (must be "2.0")
+ * @param id the request correlation identifier (String, Integer, or null)
+ * @param method the method name (must be {@value #METHOD})
+ * @param params the message send parameters (required)
+ * @throws IllegalArgumentException if validation fails
+ */
+ public SendMessageRequest(String jsonrpc, Object id, String method, MessageSendParams params) {
if (jsonrpc == null || jsonrpc.isEmpty()) {
throw new IllegalArgumentException("JSON-RPC protocol version cannot be null or empty");
}
diff --git a/spec/src/main/java/io/a2a/spec/SendMessageResponse.java b/spec/src/main/java/io/a2a/spec/SendMessageResponse.java
index 901beba90..14d3d5197 100644
--- a/spec/src/main/java/io/a2a/spec/SendMessageResponse.java
+++ b/spec/src/main/java/io/a2a/spec/SendMessageResponse.java
@@ -1,23 +1,11 @@
package io.a2a.spec;
-import static io.a2a.util.Utils.defaultIfNull;
-
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import io.a2a.util.Assert;
-
/**
* The response after receiving a send message request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class SendMessageResponse extends JSONRPCResponse {
- @JsonCreator
- public SendMessageResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") EventKind result, @JsonProperty("error") JSONRPCError error) {
+ public SendMessageResponse(String jsonrpc, Object id, EventKind result, JSONRPCError error) {
super(jsonrpc, id, result, error, EventKind.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/SendStreamingMessageRequest.java b/spec/src/main/java/io/a2a/spec/SendStreamingMessageRequest.java
index c4ebe8315..de3abf950 100644
--- a/spec/src/main/java/io/a2a/spec/SendStreamingMessageRequest.java
+++ b/spec/src/main/java/io/a2a/spec/SendStreamingMessageRequest.java
@@ -2,10 +2,6 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
import io.a2a.util.Assert;
import java.util.UUID;
@@ -13,15 +9,11 @@
/**
* Used to initiate a task with streaming.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class SendStreamingMessageRequest extends StreamingJSONRPCRequest {
public static final String METHOD = "message/stream";
- @JsonCreator
- public SendStreamingMessageRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") MessageSendParams params) {
+ public SendStreamingMessageRequest(String jsonrpc, Object id, String method, MessageSendParams params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/SendStreamingMessageResponse.java b/spec/src/main/java/io/a2a/spec/SendStreamingMessageResponse.java
index 0ed6ca80d..d76ea9aef 100644
--- a/spec/src/main/java/io/a2a/spec/SendStreamingMessageResponse.java
+++ b/spec/src/main/java/io/a2a/spec/SendStreamingMessageResponse.java
@@ -1,21 +1,11 @@
package io.a2a.spec;
-
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* The response after receiving a request to initiate a task with streaming.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class SendStreamingMessageResponse extends JSONRPCResponse {
- @JsonCreator
- public SendStreamingMessageResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") StreamingEventKind result, @JsonProperty("error") JSONRPCError error) {
+ public SendStreamingMessageResponse(String jsonrpc, Object id, StreamingEventKind result, JSONRPCError error) {
super(jsonrpc, id, result, error, StreamingEventKind.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigRequest.java b/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigRequest.java
index 7d53083a1..3007112ff 100644
--- a/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigRequest.java
+++ b/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigRequest.java
@@ -4,25 +4,16 @@
import java.util.UUID;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
import io.a2a.util.Assert;
/**
* Used to set a task push notification request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class SetTaskPushNotificationConfigRequest extends NonStreamingJSONRPCRequest {
public static final String METHOD = "tasks/pushNotificationConfig/set";
- @JsonCreator
- public SetTaskPushNotificationConfigRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") TaskPushNotificationConfig params) {
+ public SetTaskPushNotificationConfigRequest(String jsonrpc, Object id, String method, TaskPushNotificationConfig params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigResponse.java b/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigResponse.java
index c40f18f18..1b5bd2e52 100644
--- a/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigResponse.java
+++ b/spec/src/main/java/io/a2a/spec/SetTaskPushNotificationConfigResponse.java
@@ -1,21 +1,11 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* The response after receiving a set task push notification request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class SetTaskPushNotificationConfigResponse extends JSONRPCResponse {
- @JsonCreator
- public SetTaskPushNotificationConfigResponse(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("result") TaskPushNotificationConfig result,
- @JsonProperty("error") JSONRPCError error) {
+ public SetTaskPushNotificationConfigResponse(String jsonrpc, Object id, TaskPushNotificationConfig result, JSONRPCError error) {
super(jsonrpc, id, result, error, TaskPushNotificationConfig.class);
}
diff --git a/spec/src/main/java/io/a2a/spec/StreamingEventKind.java b/spec/src/main/java/io/a2a/spec/StreamingEventKind.java
index b8c16b00a..73c141953 100644
--- a/spec/src/main/java/io/a2a/spec/StreamingEventKind.java
+++ b/spec/src/main/java/io/a2a/spec/StreamingEventKind.java
@@ -1,25 +1,34 @@
package io.a2a.spec;
-import static io.a2a.spec.Message.MESSAGE;
-import static io.a2a.spec.Task.TASK;
-import static io.a2a.spec.TaskArtifactUpdateEvent.ARTIFACT_UPDATE;
-import static io.a2a.spec.TaskStatusUpdateEvent.STATUS_UPDATE;
-
-import com.fasterxml.jackson.annotation.JsonSubTypes;
-import com.fasterxml.jackson.annotation.JsonTypeInfo;
-
-@JsonTypeInfo(
- use = JsonTypeInfo.Id.NAME,
- include = JsonTypeInfo.As.EXISTING_PROPERTY,
- property = "kind",
- visible = true
-)
-@JsonSubTypes({
- @JsonSubTypes.Type(value = Task.class, name = TASK),
- @JsonSubTypes.Type(value = Message.class, name = MESSAGE),
- @JsonSubTypes.Type(value = TaskStatusUpdateEvent.class, name = STATUS_UPDATE),
- @JsonSubTypes.Type(value = TaskArtifactUpdateEvent.class, name = ARTIFACT_UPDATE)
-})
+/**
+ * Sealed interface for events that can be emitted during streaming A2A Protocol operations.
+ *
+ * StreamingEventKind represents events suitable for asynchronous, progressive updates during
+ * agent task execution. Streaming allows agents to provide incremental feedback as work progresses,
+ * rather than waiting until task completion.
+ *
+ * Streaming events use polymorphic JSON serialization with the "kind" discriminator to determine
+ * the concrete type during deserialization.
+ *
+ * Permitted implementations:
+ *
+ * - {@link Task} - Complete task state (typically the final event in a stream)
+ * - {@link Message} - Full message (complete message in the stream)
+ * - {@link TaskStatusUpdateEvent} - Incremental status updates (e.g., SUBMITTED → WORKING → COMPLETED)
+ * - {@link TaskArtifactUpdateEvent} - Incremental artifact updates (partial results, chunks)
+ *
+ *
+ * Streaming events enable patterns like:
+ *
+ * - Progressive text generation (chunks of response as generated)
+ * - Status notifications (task state transitions)
+ * - Partial results (early artifacts before task completion)
+ *
+ *
+ * @see Event
+ * @see EventKind
+ * @see UpdateEvent
+ */
public sealed interface StreamingEventKind extends Event permits Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent {
String getKind();
diff --git a/spec/src/main/java/io/a2a/spec/StreamingJSONRPCRequest.java b/spec/src/main/java/io/a2a/spec/StreamingJSONRPCRequest.java
index 7642c41d2..9cbb5e4c6 100644
--- a/spec/src/main/java/io/a2a/spec/StreamingJSONRPCRequest.java
+++ b/spec/src/main/java/io/a2a/spec/StreamingJSONRPCRequest.java
@@ -1,15 +1,9 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
-
/**
* Represents a streaming JSON-RPC request.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
-@JsonDeserialize(using = StreamingJSONRPCRequestDeserializer.class)
+
public abstract sealed class StreamingJSONRPCRequest extends JSONRPCRequest permits TaskResubscriptionRequest,
SendStreamingMessageRequest {
diff --git a/spec/src/main/java/io/a2a/spec/StreamingJSONRPCRequestDeserializer.java b/spec/src/main/java/io/a2a/spec/StreamingJSONRPCRequestDeserializer.java
deleted file mode 100644
index b66533620..000000000
--- a/spec/src/main/java/io/a2a/spec/StreamingJSONRPCRequestDeserializer.java
+++ /dev/null
@@ -1,41 +0,0 @@
-package io.a2a.spec;
-
-import java.io.IOException;
-
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.DeserializationContext;
-import com.fasterxml.jackson.databind.JsonNode;
-
-public class StreamingJSONRPCRequestDeserializer extends JSONRPCRequestDeserializerBase> {
-
- public StreamingJSONRPCRequestDeserializer() {
- this(null);
- }
-
- public StreamingJSONRPCRequestDeserializer(Class vc) {
- super(vc);
- }
-
- @Override
- public StreamingJSONRPCRequest deserialize(JsonParser jsonParser, DeserializationContext context)
- throws IOException, JsonProcessingException {
- JsonNode treeNode = jsonParser.getCodec().readTree(jsonParser);
- String jsonrpc = getAndValidateJsonrpc(treeNode, jsonParser);
- String method = getAndValidateMethod(treeNode, jsonParser);
- Object id = getAndValidateId(treeNode, jsonParser);
- JsonNode paramsNode = treeNode.get("params");
-
- switch (method) {
- case TaskResubscriptionRequest.METHOD -> {
- return new TaskResubscriptionRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, TaskIdParams.class));
- }
- case SendStreamingMessageRequest.METHOD -> {
- return new SendStreamingMessageRequest(jsonrpc, id, method,
- getAndValidateParams(paramsNode, jsonParser, treeNode, MessageSendParams.class));
- }
- default -> throw new MethodNotFoundJsonMappingException("Invalid method", getIdIfPossible(treeNode, jsonParser));
- }
- }
-}
diff --git a/spec/src/main/java/io/a2a/spec/Task.java b/spec/src/main/java/io/a2a/spec/Task.java
index 873f23431..b3b886e5b 100644
--- a/spec/src/main/java/io/a2a/spec/Task.java
+++ b/spec/src/main/java/io/a2a/spec/Task.java
@@ -3,12 +3,6 @@
import java.util.List;
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
-import com.fasterxml.jackson.core.type.TypeReference;
import io.a2a.util.Assert;
import static io.a2a.spec.Task.TASK;
@@ -16,13 +10,8 @@
/**
* Represents a single, stateful operation or conversation between a client and an agent.
*/
-@JsonTypeName(TASK)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class Task implements EventKind, StreamingEventKind {
- public static final TypeReference TYPE_REFERENCE = new TypeReference<>() {};
-
public static final String TASK = "task";
private final String id;
private final String contextId;
@@ -37,10 +26,9 @@ public Task(String id, String contextId, TaskStatus status, List artif
this(id, contextId, status, artifacts, history, metadata, TASK);
}
- @JsonCreator
- public Task(@JsonProperty("id") String id, @JsonProperty("contextId") String contextId, @JsonProperty("status") TaskStatus status,
- @JsonProperty("artifacts") List artifacts, @JsonProperty("history") List history,
- @JsonProperty("metadata") Map metadata, @JsonProperty("kind") String kind) {
+ public Task(String id, String contextId, TaskStatus status,
+ List artifacts, List history,
+ Map metadata, String kind) {
Assert.checkNotNullParam("id", id);
Assert.checkNotNullParam("contextId", contextId);
Assert.checkNotNullParam("status", status);
diff --git a/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java b/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java
index 1e1cad947..426a3da92 100644
--- a/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java
+++ b/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java
@@ -2,11 +2,6 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.TaskArtifactUpdateEvent.ARTIFACT_UPDATE;
@@ -15,9 +10,6 @@
* An event sent by the agent to notify the client that an artifact has been
* generated or updated. This is typically used in streaming models.
*/
-@JsonTypeName(ARTIFACT_UPDATE)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class TaskArtifactUpdateEvent implements EventKind, StreamingEventKind, UpdateEvent {
public static final String ARTIFACT_UPDATE = "artifact-update";
@@ -33,13 +25,7 @@ public TaskArtifactUpdateEvent(String taskId, Artifact artifact, String contextI
this(taskId, artifact, contextId, append, lastChunk, metadata, ARTIFACT_UPDATE);
}
- @JsonCreator
- public TaskArtifactUpdateEvent(@JsonProperty("taskId") String taskId, @JsonProperty("artifact") Artifact artifact,
- @JsonProperty("contextId") String contextId,
- @JsonProperty("append") Boolean append,
- @JsonProperty("lastChunk") Boolean lastChunk,
- @JsonProperty("metadata") Map metadata,
- @JsonProperty("kind") String kind) {
+ public TaskArtifactUpdateEvent(String taskId, Artifact artifact, String contextId, Boolean append, Boolean lastChunk, Map metadata, String kind) {
Assert.checkNotNullParam("taskId", taskId);
Assert.checkNotNullParam("artifact", artifact);
Assert.checkNotNullParam("contextId", contextId);
diff --git a/spec/src/main/java/io/a2a/spec/TaskIdParams.java b/spec/src/main/java/io/a2a/spec/TaskIdParams.java
index 237fe727a..096c9a8a0 100644
--- a/spec/src/main/java/io/a2a/spec/TaskIdParams.java
+++ b/spec/src/main/java/io/a2a/spec/TaskIdParams.java
@@ -2,15 +2,11 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* Defines parameters containing a task ID, used for simple task operations.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record TaskIdParams(String id, Map metadata) {
public TaskIdParams {
diff --git a/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java b/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java
index 50d32c385..d9b77bca0 100644
--- a/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java
+++ b/spec/src/main/java/io/a2a/spec/TaskNotCancelableError.java
@@ -2,16 +2,9 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* An A2A-specific error indicating that the task is in a state where it cannot be canceled.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class TaskNotCancelableError extends JSONRPCError {
public final static Integer DEFAULT_CODE = -32002;
@@ -20,18 +13,17 @@ public TaskNotCancelableError() {
this(null, null, null);
}
- @JsonCreator
public TaskNotCancelableError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ Integer code,
+ String message,
+ Object data) {
super(
defaultIfNull(code, DEFAULT_CODE),
defaultIfNull(message, "Task cannot be canceled"),
data);
}
- public TaskNotCancelableError(@JsonProperty("message") String message) {
+ public TaskNotCancelableError(String message) {
this(null, message, null);
}
diff --git a/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java b/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java
index c21998d2d..40a1528f7 100644
--- a/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java
+++ b/spec/src/main/java/io/a2a/spec/TaskNotFoundError.java
@@ -1,33 +1,21 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
import static io.a2a.util.Utils.defaultIfNull;
/**
* An A2A-specific error indicating that the requested task ID was not found.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class TaskNotFoundError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32001;
+ public final static Integer DEFAULT_CODE = A2AErrorCodes.TASK_NOT_FOUND_ERROR_CODE;
public TaskNotFoundError() {
this(null, null, null);
}
- @JsonCreator
-
- public TaskNotFoundError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ public TaskNotFoundError(Integer code, String message, Object data) {
super(
- defaultIfNull(code, DEFAULT_CODE),
+ defaultIfNull(code, A2AErrorCodes.TASK_NOT_FOUND_ERROR_CODE),
defaultIfNull(message, "Task not found"),
data);
}
diff --git a/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java b/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java
index 4cda7a8f3..23a7fc0c4 100644
--- a/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java
+++ b/spec/src/main/java/io/a2a/spec/TaskPushNotificationConfig.java
@@ -1,14 +1,10 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
/**
* A container associating a push notification configuration with a specific task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record TaskPushNotificationConfig(String taskId, PushNotificationConfig pushNotificationConfig) {
public TaskPushNotificationConfig {
diff --git a/spec/src/main/java/io/a2a/spec/TaskQueryParams.java b/spec/src/main/java/io/a2a/spec/TaskQueryParams.java
index 92c2453c5..f119bd14b 100644
--- a/spec/src/main/java/io/a2a/spec/TaskQueryParams.java
+++ b/spec/src/main/java/io/a2a/spec/TaskQueryParams.java
@@ -1,8 +1,5 @@
package io.a2a.spec;
-
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
import io.a2a.util.Assert;
import java.util.Map;
import org.jspecify.annotations.Nullable;
@@ -14,9 +11,6 @@
* @param historyLength the maximum number of items of history for the task to include in the response
* @param metadata additional properties
*/
-
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record TaskQueryParams(String id, int historyLength, @Nullable Map metadata) {
public TaskQueryParams {
diff --git a/spec/src/main/java/io/a2a/spec/TaskResubscriptionRequest.java b/spec/src/main/java/io/a2a/spec/TaskResubscriptionRequest.java
index de0c88c62..951615d53 100644
--- a/spec/src/main/java/io/a2a/spec/TaskResubscriptionRequest.java
+++ b/spec/src/main/java/io/a2a/spec/TaskResubscriptionRequest.java
@@ -2,10 +2,6 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
import io.a2a.util.Assert;
import java.util.UUID;
@@ -13,15 +9,11 @@
/**
* Used to resubscribe to a task.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class TaskResubscriptionRequest extends StreamingJSONRPCRequest {
public static final String METHOD = "tasks/resubscribe";
- @JsonCreator
- public TaskResubscriptionRequest(@JsonProperty("jsonrpc") String jsonrpc, @JsonProperty("id") Object id,
- @JsonProperty("method") String method, @JsonProperty("params") TaskIdParams params) {
+ public TaskResubscriptionRequest(String jsonrpc, Object id, String method, TaskIdParams params) {
if (jsonrpc != null && ! jsonrpc.equals(JSONRPC_VERSION)) {
throw new IllegalArgumentException("Invalid JSON-RPC protocol version");
}
diff --git a/spec/src/main/java/io/a2a/spec/TaskState.java b/spec/src/main/java/io/a2a/spec/TaskState.java
index 655d20919..413044810 100644
--- a/spec/src/main/java/io/a2a/spec/TaskState.java
+++ b/spec/src/main/java/io/a2a/spec/TaskState.java
@@ -1,8 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonValue;
-
/**
* Defines the lifecycle states of a Task.
*/
@@ -29,7 +26,14 @@ public enum TaskState {
this.isFinal = isFinal;
}
- @JsonValue
+ /**
+ * Returns the string representation of this task state for JSON serialization.
+ *
+ * This method is used to serialize TaskState values to their
+ * wire format (e.g., "working", "completed").
+ *
+ * @return the string representation of this state
+ */
public String asString() {
return state;
}
@@ -38,7 +42,16 @@ public boolean isFinal(){
return isFinal;
}
- @JsonCreator
+ /**
+ * Deserializes a string value into a TaskState enum constant.
+ *
+ * This method is used to deserialize TaskState values from their
+ * wire format during JSON parsing.
+ *
+ * @param state the string representation of the state
+ * @return the corresponding TaskState enum constant
+ * @throws IllegalArgumentException if the state string is not recognized
+ */
public static TaskState fromString(String state) {
return switch (state) {
case "submitted" -> SUBMITTED;
diff --git a/spec/src/main/java/io/a2a/spec/TaskStatus.java b/spec/src/main/java/io/a2a/spec/TaskStatus.java
index 0b9bed654..a94d54580 100644
--- a/spec/src/main/java/io/a2a/spec/TaskStatus.java
+++ b/spec/src/main/java/io/a2a/spec/TaskStatus.java
@@ -3,19 +3,13 @@
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
-import com.fasterxml.jackson.annotation.JsonFormat;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-
import io.a2a.util.Assert;
/**
* Represents the status of a task at a specific point in time.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public record TaskStatus(TaskState state, Message message,
- @JsonFormat(shape = JsonFormat.Shape.STRING) OffsetDateTime timestamp) {
+ OffsetDateTime timestamp) {
public TaskStatus {
Assert.checkNotNullParam("state", state);
diff --git a/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java b/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java
index 25e2cd170..409510c54 100644
--- a/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java
+++ b/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java
@@ -1,12 +1,8 @@
package io.a2a.spec;
+import com.google.gson.annotations.SerializedName;
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.TaskStatusUpdateEvent.STATUS_UPDATE;
@@ -15,15 +11,13 @@
* An event sent by the agent to notify the client of a change in a task's status.
* This is typically used in streaming or subscription models.
*/
-@JsonTypeName(STATUS_UPDATE)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public final class TaskStatusUpdateEvent implements EventKind, StreamingEventKind, UpdateEvent {
public static final String STATUS_UPDATE = "status-update";
private final String taskId;
private final TaskStatus status;
private final String contextId;
+ @SerializedName("final")
private final boolean isFinal;
private final Map metadata;
private final String kind;
@@ -34,10 +28,7 @@ public TaskStatusUpdateEvent(String taskId, TaskStatus status, String contextId,
this(taskId, status, contextId, isFinal, metadata, STATUS_UPDATE);
}
- @JsonCreator
- public TaskStatusUpdateEvent(@JsonProperty("taskId") String taskId, @JsonProperty("status") TaskStatus status,
- @JsonProperty("contextId") String contextId, @JsonProperty("final") boolean isFinal,
- @JsonProperty("metadata") Map metadata, @JsonProperty("kind") String kind) {
+ public TaskStatusUpdateEvent(String taskId, TaskStatus status, String contextId, boolean isFinal, Map metadata, String kind) {
Assert.checkNotNullParam("taskId", taskId);
Assert.checkNotNullParam("status", status);
Assert.checkNotNullParam("contextId", contextId);
@@ -65,7 +56,6 @@ public String getContextId() {
return contextId;
}
- @JsonProperty("final")
public boolean isFinal() {
return isFinal;
}
diff --git a/spec/src/main/java/io/a2a/spec/TextPart.java b/spec/src/main/java/io/a2a/spec/TextPart.java
index ade2047ee..0d44a3c6a 100644
--- a/spec/src/main/java/io/a2a/spec/TextPart.java
+++ b/spec/src/main/java/io/a2a/spec/TextPart.java
@@ -2,11 +2,6 @@
import java.util.Map;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.annotation.JsonTypeName;
import io.a2a.util.Assert;
import static io.a2a.spec.TextPart.TEXT;
@@ -14,9 +9,6 @@
/**
* Represents a text segment within a message or artifact.
*/
-@JsonTypeName(TEXT)
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class TextPart extends Part {
public static final String TEXT = "text";
@@ -28,8 +20,7 @@ public TextPart(String text) {
this(text, null);
}
- @JsonCreator
- public TextPart(@JsonProperty("text") String text, @JsonProperty("metadata") Map metadata) {
+ public TextPart(String text, Map metadata) {
Assert.checkNotNullParam("text", text);
this.text = text;
this.metadata = metadata;
diff --git a/spec/src/main/java/io/a2a/spec/TransportProtocol.java b/spec/src/main/java/io/a2a/spec/TransportProtocol.java
index d6c2922d2..3b3446238 100644
--- a/spec/src/main/java/io/a2a/spec/TransportProtocol.java
+++ b/spec/src/main/java/io/a2a/spec/TransportProtocol.java
@@ -1,8 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonValue;
-
/**
* Supported A2A transport protocols.
*/
@@ -17,12 +14,26 @@ public enum TransportProtocol {
this.transport = transport;
}
- @JsonValue
+ /**
+ * Returns the string representation of this transport protocol.
+ *
+ * Used for JSON serialization.
+ *
+ * @return the transport protocol name as a string
+ */
public String asString() {
return transport;
}
- @JsonCreator
+ /**
+ * Parses a string into a {@link TransportProtocol} enum constant.
+ *
+ * Used for JSON deserialization.
+ *
+ * @param transport the transport protocol string (e.g., "JSONRPC", "GRPC", "HTTP+JSON")
+ * @return the corresponding TransportProtocol enum constant
+ * @throws IllegalArgumentException if the transport string is not recognized
+ */
public static TransportProtocol fromString(String transport) {
return switch (transport) {
case "JSONRPC" -> JSONRPC;
diff --git a/spec/src/main/java/io/a2a/spec/UnsupportedOperationError.java b/spec/src/main/java/io/a2a/spec/UnsupportedOperationError.java
index 9fe055e9c..edcb381b0 100644
--- a/spec/src/main/java/io/a2a/spec/UnsupportedOperationError.java
+++ b/spec/src/main/java/io/a2a/spec/UnsupportedOperationError.java
@@ -2,27 +2,16 @@
import static io.a2a.util.Utils.defaultIfNull;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
/**
* An A2A-specific error indicating that the requested operation is not supported by the agent.
*/
-@JsonInclude(JsonInclude.Include.NON_ABSENT)
-@JsonIgnoreProperties(ignoreUnknown = true)
public class UnsupportedOperationError extends JSONRPCError {
- public final static Integer DEFAULT_CODE = -32004;
+ public final static Integer DEFAULT_CODE = A2AErrorCodes.UNSUPPORTED_OPERATION_ERROR_CODE;
- @JsonCreator
- public UnsupportedOperationError(
- @JsonProperty("code") Integer code,
- @JsonProperty("message") String message,
- @JsonProperty("data") Object data) {
+ public UnsupportedOperationError(Integer code, String message, Object data) {
super(
- defaultIfNull(code, DEFAULT_CODE),
+ defaultIfNull(code, A2AErrorCodes.UNSUPPORTED_OPERATION_ERROR_CODE),
defaultIfNull(message, "This operation is not supported"),
data);
}
diff --git a/spec/src/main/java/io/a2a/util/Utils.java b/spec/src/main/java/io/a2a/util/Utils.java
index 07143ab6a..f374f302e 100644
--- a/spec/src/main/java/io/a2a/util/Utils.java
+++ b/spec/src/main/java/io/a2a/util/Utils.java
@@ -2,29 +2,63 @@
import java.util.ArrayList;
import java.util.List;
-import java.util.logging.Logger;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import com.google.gson.Gson;
+import io.a2a.json.JsonProcessingException;
+import io.a2a.json.JsonUtil;
import io.a2a.spec.Artifact;
-import io.a2a.spec.Part;
import io.a2a.spec.Task;
import io.a2a.spec.TaskArtifactUpdateEvent;
+import io.a2a.spec.Part;
+import java.util.logging.Logger;
+
+
+/**
+ * Utility class providing common helper methods for A2A Protocol operations.
+ *
+ * This class contains static utility methods for JSON serialization/deserialization,
+ * null-safe operations, artifact management, and other common tasks used throughout
+ * the A2A Java SDK.
+ *
+ * Key capabilities:
+ *
+ * - JSON processing with pre-configured {@link Gson}
+ * - Null-safe value defaults via {@link #defaultIfNull(Object, Object)}
+ * - Artifact streaming support via {@link #appendArtifactToTask(Task, TaskArtifactUpdateEvent, String)}
+ * - Type-safe exception rethrowing via {@link #rethrow(Throwable)}
+ *
+ *
+ * @see Gson for JSON processing
+ * @see TaskArtifactUpdateEvent for streaming artifact updates
+ */
public class Utils {
- public static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
private static final Logger log = Logger.getLogger(Utils.class.getName());
- static {
- // needed for date/time types
- OBJECT_MAPPER.registerModule(new JavaTimeModule());
+
+ /**
+ * Deserializes JSON string into a typed object using Gson.
+ *
+ * This method uses the pre-configured {@link #OBJECT_MAPPER} to parse JSON.
+ *
+ * @param the target type
+ * @param data JSON string to deserialize
+ * @param typeRef class reference specifying the target type
+ * @return deserialized object of type T
+ * @throws JsonProcessingException if JSON parsing fails
+ */
+ public static T unmarshalFrom(String data, Class typeRef) throws JsonProcessingException {
+ return JsonUtil.fromJson(data, typeRef);
}
- public static T unmarshalFrom(String data, TypeReference typeRef) throws JsonProcessingException {
- return OBJECT_MAPPER.readValue(data, typeRef);
+ public static String toJsonString(Object data) {
+ try {
+ return JsonUtil.toJson(data);
+ } catch (JsonProcessingException e) {
+ throw new RuntimeException("Failed to serialize to JSON", e);
+ }
}
public static T defaultIfNull(T value, T defaultValue) {
@@ -38,6 +72,29 @@ public static void rethrow(Throwable t) throws T {
throw (T) t;
}
+ /**
+ * Appends or updates an artifact in a task based on a {@link TaskArtifactUpdateEvent}.
+ *
+ * This method handles streaming artifact updates, supporting both:
+ *
+ * - Adding new artifacts to the task
+ * - Replacing existing artifacts (when {@code append=false})
+ * - Appending parts to existing artifacts (when {@code append=true})
+ *
+ *
+ * The {@code append} flag in the event determines the behavior:
+ *
+ * - {@code false} or {@code null}: Replace/add the entire artifact
+ * - {@code true}: Append the new artifact's parts to an existing artifact with matching {@code artifactId}
+ *
+ *
+ * @param task the current task to update
+ * @param event the artifact update event containing the new/updated artifact
+ * @param taskId the task ID (for logging purposes)
+ * @return a new Task instance with the updated artifacts list
+ * @see TaskArtifactUpdateEvent for streaming artifact updates
+ * @see Artifact for artifact structure
+ */
public static Task appendArtifactToTask(Task task, TaskArtifactUpdateEvent event, String taskId) {
// Append artifacts
List artifacts = task.getArtifacts() == null ? new ArrayList<>() : new ArrayList<>(task.getArtifacts());
@@ -94,12 +151,18 @@ public static Task appendArtifactToTask(Task task, TaskArtifactUpdateEvent event
}
- public static String toJsonString(Object o) {
- try {
- return OBJECT_MAPPER.writeValueAsString(o);
- } catch (JsonProcessingException ex) {
- throw new RuntimeException(ex);
- }
- }
+ /**
+ * Get the first defined URL in the supported interaces of the agent card.
+ *
+ * @param agentCard the agentcard where the interfaces are defined.
+ * @return the first defined URL in the supported interaces of the agent card.
+ * @throws A2AClientException
+ */
+// public static String getFavoriteInterface(AgentCard agentCard) throws A2AClientException {
+// if (agentCard.supportedInterfaces() == null || agentCard.supportedInterfaces().isEmpty()) {
+// throw new A2AClientException("No server interface available in the AgentCard");
+// }
+// return agentCard.supportedInterfaces().get(0).url();
+// }
}
diff --git a/spec/src/test/java/io/a2a/spec/JSONRPCErrorSerializationTest.java b/spec/src/test/java/io/a2a/spec/JSONRPCErrorSerializationTest.java
index 24251a879..9c83f0806 100644
--- a/spec/src/test/java/io/a2a/spec/JSONRPCErrorSerializationTest.java
+++ b/spec/src/test/java/io/a2a/spec/JSONRPCErrorSerializationTest.java
@@ -1,7 +1,5 @@
package io.a2a.spec;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import java.util.List;
@@ -9,10 +7,13 @@
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import io.a2a.json.JsonProcessingException;
+import io.a2a.json.JsonUtil;
+
+
public class JSONRPCErrorSerializationTest {
@Test
- public void shouldDeserializeToCorrectJSONRPCErrorSubclass() {
- ObjectMapper objectMapper = new ObjectMapper();
+ public void shouldDeserializeToCorrectJSONRPCErrorSubclass() throws JsonProcessingException {
String jsonTemplate = """
{"code": %s, "message": "error", "data": "anything"}
""";
@@ -36,12 +37,7 @@ record ErrorCase(int code, Class clazz) {}
for (ErrorCase errorCase : cases) {
String json = jsonTemplate.formatted(errorCase.code());
- JSONRPCError error;
- try {
- error = objectMapper.readValue(json, JSONRPCError.class);
- } catch (JsonProcessingException e) {
- throw new RuntimeException(e);
- }
+ JSONRPCError error = JsonUtil.fromJson(json, JSONRPCError.class);
assertInstanceOf(errorCase.clazz(), error);
assertEquals("error", error.getMessage());
assertEquals("anything", error.getData().toString());
diff --git a/spec/src/test/java/io/a2a/spec/SubTypeSerializationTest.java b/spec/src/test/java/io/a2a/spec/SubTypeSerializationTest.java
index a4571f923..0a5a898d7 100644
--- a/spec/src/test/java/io/a2a/spec/SubTypeSerializationTest.java
+++ b/spec/src/test/java/io/a2a/spec/SubTypeSerializationTest.java
@@ -1,15 +1,11 @@
package io.a2a.spec;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.module.SimpleModule;
-import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import io.a2a.json.JsonProcessingException;
+import io.a2a.json.JsonUtil;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
-import java.util.HashMap;
import java.util.Map;
import java.util.stream.Stream;
@@ -23,24 +19,12 @@ public class SubTypeSerializationTest {
.status(new TaskStatus(TaskState.SUBMITTED))
.build();
- private static final TypeReference> MAP_TYPE_REFERENCE = new TypeReference<>() {
- };
-
- private static final ObjectMapper OBJECT_MAPPER;
-
- static {
- OBJECT_MAPPER = new ObjectMapper();
- SimpleModule module = new SimpleModule();
- module.addAbstractTypeMapping(Map.class, SingleKeyHashMap.class);
- OBJECT_MAPPER.registerModule(module);
- OBJECT_MAPPER.registerModule(new JavaTimeModule());
- }
-
@ParameterizedTest
@MethodSource("serializationTestCases")
void testSubtypeSerialization(Object objectToSerialize, String typePropertyName, String expectedTypeValue) throws JsonProcessingException {
- Map map = OBJECT_MAPPER.readValue(OBJECT_MAPPER.writeValueAsString(objectToSerialize),
- MAP_TYPE_REFERENCE);
+ String json = JsonUtil.toJson(objectToSerialize);
+ @SuppressWarnings("unchecked")
+ Map map = JsonUtil.fromJson(json, Map.class);
assertEquals(expectedTypeValue, map.get(typePropertyName));
}
@@ -115,15 +99,4 @@ private static Stream serializationTestCases() {
);
}
- private static class SingleKeyHashMap extends HashMap {
- @Override
- public V put(K key, V value) {
- if (containsKey(key)) {
- throw new IllegalArgumentException("duplicate key " + key
- + " with value " + get(key) + " and new value " + value);
- }
- return super.put(key, value);
- }
- }
-
}
diff --git a/spec/src/test/java/io/a2a/spec/TaskDeserializationTest.java b/spec/src/test/java/io/a2a/spec/TaskDeserializationTest.java
deleted file mode 100644
index fa67b59f5..000000000
--- a/spec/src/test/java/io/a2a/spec/TaskDeserializationTest.java
+++ /dev/null
@@ -1,90 +0,0 @@
-package io.a2a.spec;
-
-import com.fasterxml.jackson.databind.ObjectMapper;
-import org.junit.jupiter.api.Test;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-public class TaskDeserializationTest {
- private final ObjectMapper objectMapper = new ObjectMapper();
-
- @Test
- void testTaskWithMissingHistoryAndArtifacts() throws Exception {
- // JSON without history and artifacts fields (common server response)
- String json = """
- {
- "id": "task-123",
- "contextId": "context-456",
- "status": {
- "state": "completed"
- },
- "kind": "task"
- }
- """;
-
- Task task = objectMapper.readValue(json, Task.class);
-
- assertNotNull(task.getHistory(), "history should not be null");
- assertNotNull(task.getArtifacts(), "artifacts should not be null");
-
- assertTrue(task.getHistory().isEmpty(), "history should be empty list when not provided");
- assertTrue(task.getArtifacts().isEmpty(), "artifacts should be empty list when not provided");
- }
-
- @Test
- void testTaskWithExplicitNullValues() throws Exception {
- // JSON with explicit null values
- String json = """
- {
- "id": "task-123",
- "contextId": "context-456",
- "status": {
- "state": "completed"
- },
- "history": null,
- "artifacts": null,
- "kind": "task"
- }
- """;
-
- Task task = objectMapper.readValue(json, Task.class);
-
- // Should never be null even with explicit null in JSON
- assertNotNull(task.getHistory(), "history should not be null even when JSON contains null");
- assertNotNull(task.getArtifacts(), "artifacts should not be null even when JSON contains null");
-
- assertTrue(task.getHistory().isEmpty());
- assertTrue(task.getArtifacts().isEmpty());
- }
-
- @Test
- void testTaskWithPopulatedArrays() throws Exception {
- String json = """
- {
- "id": "task-123",
- "contextId": "context-456",
- "status": {
- "state": "completed"
- },
- "history": [
- {
- "role": "user",
- "parts": [{"kind": "text", "text": "hello"}],
- "messageId": "msg-1",
- "kind": "message"
- }
- ],
- "artifacts": [],
- "kind": "task"
- }
- """;
-
- Task task = objectMapper.readValue(json, Task.class);
-
- assertNotNull(task.getHistory());
- assertEquals(1, task.getHistory().size());
-
- assertNotNull(task.getArtifacts());
- assertTrue(task.getArtifacts().isEmpty());
- }
-}
diff --git a/spec/src/test/java/io/a2a/spec/TaskSerializationTest.java b/spec/src/test/java/io/a2a/spec/TaskSerializationTest.java
new file mode 100644
index 000000000..12bfcf508
--- /dev/null
+++ b/spec/src/test/java/io/a2a/spec/TaskSerializationTest.java
@@ -0,0 +1,713 @@
+package io.a2a.spec;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.time.OffsetDateTime;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+import io.a2a.json.JsonProcessingException;
+import io.a2a.json.JsonUtil;
+
+/**
+ * Tests for Task serialization and deserialization using Gson.
+ */
+class TaskSerializationTest {
+
+ @Test
+ void testBasicTaskSerialization() throws JsonProcessingException {
+ // Create a basic task
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.SUBMITTED))
+ .build();
+
+ // Serialize to JSON
+ String json = JsonUtil.toJson(task);
+
+ // Verify JSON contains expected fields
+ assertNotNull(json);
+ assertTrue(json.contains("\"id\":\"task-123\""));
+ assertTrue(json.contains("\"state\":\"submitted\""));
+
+ // Deserialize back to Task
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify deserialized task matches original
+ assertEquals(task.getId(), deserialized.getId());
+ assertEquals(task.getStatus().state(), deserialized.getStatus().state());
+ }
+
+ @Test
+ void testTaskWithTimestamp() throws JsonProcessingException {
+ OffsetDateTime timestamp = OffsetDateTime.now();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.WORKING, null, timestamp))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify OffsetDateTime timestamp is preserved
+ assertNotNull(deserialized.getStatus().timestamp());
+ assertEquals(task.getStatus().timestamp(), deserialized.getStatus().timestamp());
+ }
+
+ @Test
+ void testTaskWithArtifacts() throws JsonProcessingException {
+ Artifact artifact = new Artifact.Builder()
+ .artifactId("artifact-1")
+ .name("Test Artifact")
+ .description("Description of artifact")
+ .parts(List.of(
+ new TextPart("Hello"),
+ new TextPart("World")
+ ))
+ .build();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.COMPLETED))
+ .artifacts(List.of(artifact))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Verify JSON contains artifact data
+ assertTrue(json.contains("\"artifactId\":\"artifact-1\""));
+ assertTrue(json.contains("Hello"));
+ assertTrue(json.contains("World"));
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify artifacts are preserved
+ assertNotNull(deserialized.getArtifacts());
+ assertEquals(1, deserialized.getArtifacts().size());
+ assertEquals("artifact-1", deserialized.getArtifacts().get(0).artifactId());
+ assertEquals(2, deserialized.getArtifacts().get(0).parts().size());
+ }
+
+ @Test
+ void testTaskWithHistory() throws JsonProcessingException {
+ Message message = new Message.Builder()
+ .role(Message.Role.USER)
+ .parts(List.of(new TextPart("Test message")))
+ .build();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.WORKING))
+ .history(List.of(message))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Verify JSON contains history data
+ assertTrue(json.contains("\"role\":\"user\""));
+ assertTrue(json.contains("Test message"));
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify history is preserved
+ assertNotNull(deserialized.getHistory());
+ assertEquals(1, deserialized.getHistory().size());
+ assertEquals(Message.Role.USER, deserialized.getHistory().get(0).getRole());
+ assertEquals(1, deserialized.getHistory().get(0).getParts().size());
+ }
+
+ @Test
+ void testTaskWithAllFields() throws JsonProcessingException {
+ OffsetDateTime timestamp = OffsetDateTime.now();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-789")
+ .status(new TaskStatus(TaskState.WORKING, null, timestamp))
+ .history(List.of(
+ new Message.Builder()
+ .role(Message.Role.USER)
+ .parts(List.of(new TextPart("User message")))
+ .build(),
+ new Message.Builder()
+ .role(Message.Role.AGENT)
+ .parts(List.of(new TextPart("Agent response")))
+ .build()
+ ))
+ .artifacts(List.of(
+ new Artifact.Builder()
+ .artifactId("artifact-1")
+ .parts(List.of(new TextPart("Artifact content")))
+ .build()
+ ))
+ .metadata(Map.of("key1", "value1", "key2", 42))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify all fields are preserved
+ assertEquals(task.getId(), deserialized.getId());
+ assertEquals(task.getContextId(), deserialized.getContextId());
+ assertEquals(task.getStatus().state(), deserialized.getStatus().state());
+ assertEquals(task.getStatus().timestamp(), deserialized.getStatus().timestamp());
+ assertEquals(task.getHistory().size(), deserialized.getHistory().size());
+ assertEquals(task.getArtifacts().size(), deserialized.getArtifacts().size());
+ assertNotNull(deserialized.getMetadata());
+ assertEquals("value1", deserialized.getMetadata().get("key1"));
+ }
+
+ @Test
+ void testTaskWithDifferentStates() throws JsonProcessingException {
+ for (TaskState state : TaskState.values()) {
+ Task task = new Task.Builder()
+ .id("task-" + state.asString())
+ .contextId("context-123")
+ .status(new TaskStatus(state))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Verify state is serialized correctly
+ assertTrue(json.contains("\"state\":\"" + state.asString() + "\""));
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify state is preserved
+ assertEquals(state, deserialized.getStatus().state());
+ }
+ }
+
+ @Test
+ void testTaskWithNullOptionalFields() throws JsonProcessingException {
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.SUBMITTED))
+ // artifacts, history, metadata not set
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify required fields are present
+ assertEquals("task-123", deserialized.getId());
+ assertEquals("context-456", deserialized.getContextId());
+ assertEquals(TaskState.SUBMITTED, deserialized.getStatus().state());
+
+ // Verify optional lists default to empty
+ assertNotNull(deserialized.getArtifacts());
+ assertEquals(0, deserialized.getArtifacts().size());
+ assertNotNull(deserialized.getHistory());
+ assertEquals(0, deserialized.getHistory().size());
+ }
+
+ @Test
+ void testTaskWithFilePartBytes() throws JsonProcessingException {
+ FilePart filePart = new FilePart(new FileWithBytes("application/pdf", "document.pdf", "base64data"));
+
+ Artifact artifact = new Artifact.Builder()
+ .artifactId("file-artifact")
+ .parts(List.of(filePart))
+ .build();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.COMPLETED))
+ .artifacts(List.of(artifact))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Verify JSON contains file part data
+ assertTrue(json.contains("\"kind\":\"file\""));
+ assertTrue(json.contains("document.pdf"));
+ assertTrue(json.contains("application/pdf"));
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify file part is preserved
+ Part part = deserialized.getArtifacts().get(0).parts().get(0);
+ assertTrue(part instanceof FilePart);
+ FilePart deserializedFilePart = (FilePart) part;
+ assertTrue(deserializedFilePart.getFile() instanceof FileWithBytes);
+ FileWithBytes fileWithBytes = (FileWithBytes) deserializedFilePart.getFile();
+ assertEquals("document.pdf", fileWithBytes.name());
+ assertEquals("application/pdf", fileWithBytes.mimeType());
+ }
+
+ @Test
+ void testTaskWithFilePartUri() throws JsonProcessingException {
+ FilePart filePart = new FilePart(new FileWithUri("image/png", "photo.png", "https://example.com/photo.png"));
+
+ Artifact artifact = new Artifact.Builder()
+ .artifactId("uri-artifact")
+ .parts(List.of(filePart))
+ .build();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.COMPLETED))
+ .artifacts(List.of(artifact))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Verify JSON contains URI
+ assertTrue(json.contains("https://example.com/photo.png"));
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify file part URI is preserved
+ Part part = deserialized.getArtifacts().get(0).parts().get(0);
+ assertTrue(part instanceof FilePart);
+ FilePart deserializedFilePart = (FilePart) part;
+ assertTrue(deserializedFilePart.getFile() instanceof FileWithUri);
+ FileWithUri fileWithUri = (FileWithUri) deserializedFilePart.getFile();
+ assertEquals("https://example.com/photo.png", fileWithUri.uri());
+ }
+
+ @Test
+ void testTaskWithDataPart() throws JsonProcessingException {
+ DataPart dataPart = new DataPart(Map.of("temperature", 22.5, "humidity", 65));
+
+ Artifact artifact = new Artifact.Builder()
+ .artifactId("data-artifact")
+ .parts(List.of(dataPart))
+ .build();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.COMPLETED))
+ .artifacts(List.of(artifact))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Verify JSON contains data part
+ assertTrue(json.contains("\"kind\":\"data\""));
+ assertTrue(json.contains("temperature"));
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify data part is preserved
+ Part part = deserialized.getArtifacts().get(0).parts().get(0);
+ assertTrue(part instanceof DataPart);
+ DataPart deserializedDataPart = (DataPart) part;
+ assertNotNull(deserializedDataPart.getData());
+ }
+
+ @Test
+ void testTaskRoundTrip() throws JsonProcessingException {
+ // Create a comprehensive task with all part types
+ OffsetDateTime timestamp = OffsetDateTime.now();
+
+ Task original = new Task.Builder()
+ .id("task-123")
+ .contextId("context-789")
+ .status(new TaskStatus(TaskState.WORKING, null, timestamp))
+ .history(List.of(
+ new Message.Builder()
+ .role(Message.Role.USER)
+ .parts(List.of(
+ new TextPart("Text"),
+ new FilePart(new FileWithBytes("text/plain", "file.txt", "data")),
+ new DataPart(Map.of("key", "value"))
+ ))
+ .build()
+ ))
+ .artifacts(List.of(
+ new Artifact.Builder()
+ .artifactId("artifact-1")
+ .parts(List.of(new TextPart("Content")))
+ .build()
+ ))
+ .metadata(Map.of("meta1", "value1"))
+ .build();
+
+ // Serialize to JSON
+ String json = JsonUtil.toJson(original);
+
+ // Deserialize back to Task
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Serialize again
+ String json2 = JsonUtil.toJson(deserialized);
+
+ // Deserialize again
+ Task deserialized2 = JsonUtil.fromJson(json2, Task.class);
+
+ // Verify multiple round-trips produce identical results
+ assertEquals(deserialized.getId(), deserialized2.getId());
+ assertEquals(deserialized.getContextId(), deserialized2.getContextId());
+ assertEquals(deserialized.getStatus().state(), deserialized2.getStatus().state());
+ assertEquals(deserialized.getHistory().size(), deserialized2.getHistory().size());
+ assertEquals(deserialized.getArtifacts().size(), deserialized2.getArtifacts().size());
+ }
+
+ @Test
+ void testTaskStatusWithMessage() throws JsonProcessingException {
+ Message statusMessage = new Message.Builder()
+ .role(Message.Role.AGENT)
+ .parts(List.of(new TextPart("Processing complete")))
+ .build();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.COMPLETED, statusMessage, null))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Verify JSON contains status message
+ assertTrue(json.contains("\"state\":\"completed\""));
+ assertTrue(json.contains("Processing complete"));
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify status message is preserved
+ assertEquals(TaskState.COMPLETED, deserialized.getStatus().state());
+ assertNotNull(deserialized.getStatus().message());
+ assertEquals(Message.Role.AGENT, deserialized.getStatus().message().getRole());
+ assertTrue(deserialized.getStatus().message().getParts().get(0) instanceof TextPart);
+ }
+
+ @Test
+ void testDeserializeTaskFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "submitted"
+ },
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ assertEquals("context-456", task.getContextId());
+ assertEquals(TaskState.SUBMITTED, task.getStatus().state());
+ assertNull(task.getStatus().message());
+ // TaskStatus automatically sets timestamp to current time if not provided
+ assertNotNull(task.getStatus().timestamp());
+ }
+
+ @Test
+ void testDeserializeTaskWithArtifactsFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "completed"
+ },
+ "artifacts": [
+ {
+ "artifactId": "artifact-1",
+ "name": "Result",
+ "parts": [
+ {
+ "kind": "text",
+ "text": "Hello World"
+ }
+ ]
+ }
+ ],
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ assertEquals(TaskState.COMPLETED, task.getStatus().state());
+ assertEquals(1, task.getArtifacts().size());
+ assertEquals("artifact-1", task.getArtifacts().get(0).artifactId());
+ assertEquals("Result", task.getArtifacts().get(0).name());
+ assertEquals(1, task.getArtifacts().get(0).parts().size());
+ assertTrue(task.getArtifacts().get(0).parts().get(0) instanceof TextPart);
+ assertEquals("Hello World", ((TextPart) task.getArtifacts().get(0).parts().get(0)).getText());
+ }
+
+ @Test
+ void testDeserializeTaskWithFilePartBytesFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "completed"
+ },
+ "artifacts": [
+ {
+ "artifactId": "file-artifact",
+ "parts": [
+ {
+ "kind": "file",
+ "file": {
+ "mimeType": "application/pdf",
+ "name": "document.pdf",
+ "bytes": "base64encodeddata"
+ }
+ }
+ ]
+ }
+ ],
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ assertEquals(1, task.getArtifacts().size());
+ Part part = task.getArtifacts().get(0).parts().get(0);
+ assertTrue(part instanceof FilePart);
+ FilePart filePart = (FilePart) part;
+ assertTrue(filePart.getFile() instanceof FileWithBytes);
+ FileWithBytes fileWithBytes = (FileWithBytes) filePart.getFile();
+ assertEquals("application/pdf", fileWithBytes.mimeType());
+ assertEquals("document.pdf", fileWithBytes.name());
+ assertEquals("base64encodeddata", fileWithBytes.bytes());
+ }
+
+ @Test
+ void testDeserializeTaskWithFilePartUriFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "completed"
+ },
+ "artifacts": [
+ {
+ "artifactId": "uri-artifact",
+ "parts": [
+ {
+ "kind": "file",
+ "file": {
+ "mimeType": "image/png",
+ "name": "photo.png",
+ "uri": "https://example.com/photo.png"
+ }
+ }
+ ]
+ }
+ ],
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ Part part = task.getArtifacts().get(0).parts().get(0);
+ assertTrue(part instanceof FilePart);
+ FilePart filePart = (FilePart) part;
+ assertTrue(filePart.getFile() instanceof FileWithUri);
+ FileWithUri fileWithUri = (FileWithUri) filePart.getFile();
+ assertEquals("image/png", fileWithUri.mimeType());
+ assertEquals("photo.png", fileWithUri.name());
+ assertEquals("https://example.com/photo.png", fileWithUri.uri());
+ }
+
+ @Test
+ void testDeserializeTaskWithDataPartFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "completed"
+ },
+ "artifacts": [
+ {
+ "artifactId": "data-artifact",
+ "parts": [
+ {
+ "kind": "data",
+ "data": {
+ "temperature": 22.5,
+ "humidity": 65
+ }
+ }
+ ]
+ }
+ ],
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ Part part = task.getArtifacts().get(0).parts().get(0);
+ assertTrue(part instanceof DataPart);
+ DataPart dataPart = (DataPart) part;
+ assertNotNull(dataPart.getData());
+ }
+
+ @Test
+ void testDeserializeTaskWithHistoryFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "working"
+ },
+ "history": [
+ {
+ "role": "user",
+ "parts": [
+ {
+ "kind": "text",
+ "text": "User message"
+ }
+ ]
+ },
+ {
+ "role": "agent",
+ "parts": [
+ {
+ "kind": "text",
+ "text": "Agent response"
+ }
+ ]
+ }
+ ],
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ assertEquals(2, task.getHistory().size());
+ assertEquals(Message.Role.USER, task.getHistory().get(0).getRole());
+ assertEquals(Message.Role.AGENT, task.getHistory().get(1).getRole());
+ assertTrue(task.getHistory().get(0).getParts().get(0) instanceof TextPart);
+ assertEquals("User message", ((TextPart) task.getHistory().get(0).getParts().get(0)).getText());
+ }
+
+ @Test
+ void testDeserializeTaskWithTimestampFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "working",
+ "timestamp": "2023-10-01T12:00:00.234-05:00"
+ },
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ assertEquals(TaskState.WORKING, task.getStatus().state());
+ assertNotNull(task.getStatus().timestamp());
+ assertEquals("2023-10-01T12:00:00.234-05:00", task.getStatus().timestamp().toString());
+ }
+
+ @Test
+ void testDeserializeTaskWithMetadataFromJson() throws JsonProcessingException {
+ String json = """
+ {
+ "id": "task-123",
+ "contextId": "context-456",
+ "status": {
+ "state": "completed"
+ },
+ "metadata": {
+ "key1": "value1",
+ "key2": 42
+ },
+ "kind": "task"
+ }
+ """;
+
+ Task task = JsonUtil.fromJson(json, Task.class);
+
+ assertEquals("task-123", task.getId());
+ assertNotNull(task.getMetadata());
+ assertEquals("value1", task.getMetadata().get("key1"));
+ }
+
+ @Test
+ void testTaskWithMixedPartTypes() throws JsonProcessingException {
+ Artifact artifact = new Artifact.Builder()
+ .artifactId("mixed-artifact")
+ .parts(List.of(
+ new TextPart("Text content"),
+ new FilePart(new FileWithBytes("application/json", "data.json", "{}")),
+ new DataPart(Map.of("result", 42)),
+ new FilePart(new FileWithUri("image/png", "image.png", "https://example.com/img.png"))
+ ))
+ .build();
+
+ Task task = new Task.Builder()
+ .id("task-123")
+ .contextId("context-456")
+ .status(new TaskStatus(TaskState.COMPLETED))
+ .artifacts(List.of(artifact))
+ .build();
+
+ // Serialize
+ String json = JsonUtil.toJson(task);
+
+ // Deserialize
+ Task deserialized = JsonUtil.fromJson(json, Task.class);
+
+ // Verify all part types are preserved
+ List> parts = deserialized.getArtifacts().get(0).parts();
+ assertEquals(4, parts.size());
+ assertTrue(parts.get(0) instanceof TextPart);
+ assertTrue(parts.get(1) instanceof FilePart);
+ assertTrue(parts.get(2) instanceof DataPart);
+ assertTrue(parts.get(3) instanceof FilePart);
+ }
+}
diff --git a/spec/src/test/java/io/a2a/spec/TaskStatusTest.java b/spec/src/test/java/io/a2a/spec/TaskStatusTest.java
deleted file mode 100644
index 7c4a9db8a..000000000
--- a/spec/src/test/java/io/a2a/spec/TaskStatusTest.java
+++ /dev/null
@@ -1,94 +0,0 @@
-package io.a2a.spec;
-
-import com.fasterxml.jackson.databind.DeserializationFeature;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
-import org.junit.jupiter.api.Test;
-
-import java.time.OffsetDateTime;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertNotNull;
-import static org.junit.jupiter.api.Assertions.assertThrows;
-
-public class TaskStatusTest {
-
- private static final ObjectMapper OBJECT_MAPPER;
-
- private static final String REPLACE_TIMESTAMP_PATTERN = ".*\"timestamp\":\"([^\"]+)\",?.*";
-
- static {
- OBJECT_MAPPER = new ObjectMapper();
- OBJECT_MAPPER.registerModule(new JavaTimeModule());
- OBJECT_MAPPER.configure(DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE, false);
- }
-
- @Test
- public void testTaskStatusWithSetTimestamp() {
- TaskState state = TaskState.WORKING;
- OffsetDateTime offsetDateTime = OffsetDateTime.parse("2023-10-01T12:00:00Z");
- TaskStatus status = new TaskStatus(state, offsetDateTime);
-
- assertNotNull(status.timestamp());
- assertEquals(offsetDateTime, status.timestamp());
- }
-
- @Test
- public void testTaskStatusWithProvidedTimestamp() {
- OffsetDateTime providedTimestamp = OffsetDateTime.parse("2024-01-01T00:00:00Z");
- TaskState state = TaskState.COMPLETED;
- TaskStatus status = new TaskStatus(state, providedTimestamp);
-
- assertEquals(providedTimestamp, status.timestamp());
- }
-
- @Test
- public void testTaskStatusSerializationUsesISO8601Format() throws Exception {
- OffsetDateTime expectedTimestamp = OffsetDateTime.parse("2023-10-01T12:00:00.234-05:00");
- TaskState state = TaskState.WORKING;
- TaskStatus status = new TaskStatus(state, expectedTimestamp);
-
- String json = OBJECT_MAPPER.writeValueAsString(status);
-
- String expectedJson = "{\"state\":\"working\",\"timestamp\":\"2023-10-01T12:00:00.234-05:00\"}";
- assertEquals(expectedJson, json);
- }
-
- @Test
- public void testTaskStatusDeserializationWithValidISO8601Format() throws Exception {
- String validJson = "{"
- + "\"state\": \"auth-required\","
- + "\"timestamp\": \"2023-10-01T12:00:00.10+03:00\""
- + "}";
-
- TaskStatus result = OBJECT_MAPPER.readValue(validJson, TaskStatus.class);
- assertEquals(TaskState.AUTH_REQUIRED, result.state());
- assertNotNull(result.timestamp());
- assertEquals(OffsetDateTime.parse("2023-10-01T12:00:00.100+03:00"), result.timestamp());
- }
-
- @Test
- public void testTaskStatusDeserializationWithInvalidISO8601FormatFails() {
- String invalidJson = "{"
- + "\"state\": \"completed\","
- + "\"timestamp\": \"2023/10/01 12:00:00\""
- + "}";
-
- assertThrows(
- com.fasterxml.jackson.databind.exc.InvalidFormatException.class,
- () -> OBJECT_MAPPER.readValue(invalidJson, TaskStatus.class)
- );
- }
-
- @Test
- public void testTaskStatusJsonTimestampMatchesISO8601Regex() throws Exception {
- TaskState state = TaskState.WORKING;
- OffsetDateTime expectedTimestamp = OffsetDateTime.parse("2023-10-01T12:00:00.234Z");
- TaskStatus status = new TaskStatus(state, expectedTimestamp);
-
- String json = OBJECT_MAPPER.writeValueAsString(status);
-
- String timestampValue = json.replaceAll(REPLACE_TIMESTAMP_PATTERN, "$1");
- assertEquals(expectedTimestamp, OffsetDateTime.parse(timestampValue));
- }
-}
diff --git a/tck/pom.xml b/tck/pom.xml
index 6b4002b03..06aab7b63 100644
--- a/tck/pom.xml
+++ b/tck/pom.xml
@@ -30,7 +30,7 @@