Skip to content

Commit f46bb36

Browse files
committed
feat: Add metadata support to Part types
Add optional metadata field to TextPart, FilePart, and DataPart records to support additional contextual information for message and artifact content parts as specified in the A2A protocol v1.0. Changes: - Add metadata parameter to Part constructors (TextPart, FilePart, DataPart) - Update PartMapper to convert metadata between domain and gRPC proto - Update JsonUtil PartTypeAdapter to serialize/deserialize metadata Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent 2cce2a2 commit f46bb36

12 files changed

Lines changed: 111 additions & 33 deletions

File tree

‎client/transport/spi/src/test/java/io/a2a/client/transport/spi/sse/SSEEventListenerTest.java‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@
1010
import java.util.concurrent.atomic.AtomicBoolean;
1111
import java.util.concurrent.atomic.AtomicReference;
1212
import java.util.function.Consumer;
13-
import java.util.stream.Stream;
1413

1514
import io.a2a.spec.Message;
1615
import io.a2a.spec.StreamingEventKind;
@@ -22,9 +21,7 @@
2221
import org.jspecify.annotations.Nullable;
2322
import org.junit.jupiter.api.Test;
2423
import org.junit.jupiter.params.ParameterizedTest;
25-
import org.junit.jupiter.params.provider.Arguments;
2624
import org.junit.jupiter.params.provider.EnumSource;
27-
import org.junit.jupiter.params.provider.MethodSource;
2825

2926
/**
3027
* Tests for BaseSSEEventListener abstract class.

‎jsonrpc-common/src/main/java/io/a2a/jsonrpc/common/json/JsonUtil.java‎

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,15 @@
2222
import java.time.OffsetDateTime;
2323
import java.time.format.DateTimeFormatter;
2424
import java.time.format.DateTimeParseException;
25+
import java.util.Map;
2526
import java.util.Set;
2627

2728
import com.google.gson.Gson;
2829
import com.google.gson.GsonBuilder;
2930
import com.google.gson.JsonSyntaxException;
3031
import com.google.gson.ToNumberPolicy;
3132
import com.google.gson.TypeAdapter;
33+
import com.google.gson.reflect.TypeToken;
3234
import com.google.gson.stream.JsonReader;
3335
import com.google.gson.stream.JsonToken;
3436
import com.google.gson.stream.JsonWriter;
@@ -543,10 +545,18 @@ public void write(JsonWriter out, Message.Role value) throws java.io.IOException
543545
static class PartTypeAdapter extends TypeAdapter<Part<?>> {
544546

545547
private static final Set<String> VALID_KEYS = Set.of(TEXT, FILE, DATA);
548+
private static final Type MAP_TYPE = new TypeToken<Map<String, Object>>(){}.getType();
546549

547550
// Create separate Gson instance without the Part adapter to avoid recursion
548551
private final Gson delegateGson = createBaseGsonBuilder().create();
549552

553+
private void writeMetadata(JsonWriter out, @Nullable Map<String, Object> metadata) throws java.io.IOException {
554+
if (metadata != null && !metadata.isEmpty()) {
555+
out.name("metadata");
556+
delegateGson.toJson(metadata, MAP_TYPE, out);
557+
}
558+
}
559+
550560
@Override
551561
public void write(JsonWriter out, Part<?> value) throws java.io.IOException {
552562
if (value == null) {
@@ -560,14 +570,17 @@ public void write(JsonWriter out, Part<?> value) throws java.io.IOException {
560570
// TextPart: { "text": "value" } - direct string value
561571
out.name(TEXT);
562572
out.value(textPart.text());
573+
writeMetadata(out, textPart.metadata());
563574
} else if (value instanceof FilePart filePart) {
564575
// FilePart: { "file": {...} }
565576
out.name(FILE);
566577
delegateGson.toJson(filePart.file(), FileContent.class, out);
578+
writeMetadata(out, filePart.metadata());
567579
} else if (value instanceof DataPart dataPart) {
568580
// DataPart: { "data": <any JSON value> }
569581
out.name(DATA);
570582
delegateGson.toJson(dataPart.data(), Object.class, out);
583+
writeMetadata(out, dataPart.metadata());
571584
} else {
572585
throw new JsonSyntaxException("Unknown Part subclass: " + value.getClass().getName());
573586
}
@@ -591,24 +604,34 @@ Part<?> read(JsonReader in) throws java.io.IOException {
591604

592605
com.google.gson.JsonObject jsonObject = jsonElement.getAsJsonObject();
593606

607+
// Extract metadata if present
608+
Map<String, Object> metadata = null;
609+
if (jsonObject.has("metadata")) {
610+
metadata = delegateGson.fromJson(jsonObject.get("metadata"), new TypeToken<Map<String, Object>>(){}.getType());
611+
}
612+
594613
// Check for member name discriminators (v1.0 protocol)
595614
Set<String> keys = jsonObject.keySet();
596-
if (keys.size() != 1) {
597-
throw new JsonSyntaxException(format("Part object must have exactly one key, which must be one of: %s (found: %s)", VALID_KEYS, keys));
615+
if (keys.size() < 1 || keys.size() > 2) {
616+
throw new JsonSyntaxException(format("Part object must have one content key from %s and optionally 'metadata' (found: %s)", VALID_KEYS, keys));
598617
}
599618

600-
String discriminator = keys.iterator().next();
619+
// Find the discriminator (should be one of TEXT, FILE, DATA)
620+
String discriminator = keys.stream()
621+
.filter(VALID_KEYS::contains)
622+
.findFirst()
623+
.orElseThrow(() -> new JsonSyntaxException(format("Part must have one of: %s (found: %s)", VALID_KEYS, keys)));
601624

602625
return switch (discriminator) {
603-
case TEXT -> new TextPart(jsonObject.get(TEXT).getAsString());
604-
case FILE -> new FilePart(delegateGson.fromJson(jsonObject.get(FILE), FileContent.class));
626+
case TEXT -> new TextPart(jsonObject.get(TEXT).getAsString(), metadata);
627+
case FILE -> new FilePart(delegateGson.fromJson(jsonObject.get(FILE), FileContent.class), metadata);
605628
case DATA -> {
606629
// DataPart supports any JSON value: object, array, primitive, or null
607630
Object data = delegateGson.fromJson(
608631
jsonObject.get(DATA),
609632
Object.class
610633
);
611-
yield new DataPart(data);
634+
yield new DataPart(data, metadata);
612635
}
613636
default ->
614637
throw new JsonSyntaxException(format("Part must have one of: %s (found: %s)", VALID_KEYS, discriminator));

‎pom.xml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@
6969
<rest-assured.version>5.5.1</rest-assured.version>
7070
<slf4j.version>2.0.17</slf4j.version>
7171
<logback.version>1.5.18</logback.version>
72+
<version.testcontainers>1.21.4</version.testcontainers>
7273
<error-prone.version>2.47.0</error-prone.version>
7374
<nullaway.version>0.13.1</nullaway.version>
7475
<error-prone.flag>-XDaddTypeAnnotationsToSymbol=true</error-prone.flag>
@@ -226,6 +227,13 @@
226227
<type>pom</type>
227228
<scope>import</scope>
228229
</dependency>
230+
<dependency>
231+
<groupId>org.testcontainers</groupId>
232+
<artifactId>testcontainers-bom</artifactId>
233+
<version>${version.testcontainers}</version>
234+
<type>pom</type>
235+
<scope>import</scope>
236+
</dependency>
229237
<dependency>
230238
<groupId>io.quarkus</groupId>
231239
<artifactId>quarkus-bom</artifactId>

‎server-common/src/main/java/io/a2a/server/util/ArtifactUtils.java‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
package io.a2a.server.util;
22

33
import java.util.List;
4-
import java.util.Map;
54
import java.util.UUID;
65

76
import io.a2a.spec.Artifact;

‎server-common/src/test/java/io/a2a/server/tasks/PushNotificationSenderTest.java‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@
2323
import io.a2a.jsonrpc.common.json.JsonUtil;
2424
import io.a2a.spec.Artifact;
2525
import io.a2a.spec.Message;
26-
import io.a2a.spec.Part;
2726
import io.a2a.spec.PushNotificationConfig;
2827
import io.a2a.spec.StreamingEventKind;
2928
import io.a2a.spec.Task;

‎server-common/src/test/java/io/a2a/server/tasks/ResultAggregatorTest.java‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
import static org.junit.jupiter.api.Assertions.assertEquals;
44
import static org.junit.jupiter.api.Assertions.assertNotNull;
55
import static org.junit.jupiter.api.Assertions.assertTrue;
6-
import static org.mockito.Mockito.atLeast;
76
import static org.mockito.Mockito.atMost;
87
import static org.mockito.Mockito.times;
98
import static org.mockito.Mockito.verify;
@@ -29,7 +28,6 @@
2928
import io.a2a.spec.TaskState;
3029
import io.a2a.spec.TaskStatus;
3130
import io.a2a.spec.TextPart;
32-
import org.junit.jupiter.api.AfterEach;
3331
import org.junit.jupiter.api.BeforeEach;
3432
import org.junit.jupiter.api.Test;
3533
import org.mockito.Mock;

‎spec-grpc/src/main/java/io/a2a/grpc/mapper/PartMapper.java‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
import io.a2a.spec.InvalidRequestError;
1313
import io.a2a.spec.Part;
1414
import io.a2a.spec.TextPart;
15+
import java.util.Map;
1516
import org.mapstruct.Mapper;
1617

1718
/**
@@ -46,6 +47,7 @@ default io.a2a.grpc.Part toProto(Part<?> domain) {
4647

4748
if (domain instanceof TextPart textPart) {
4849
builder.setText(textPart.text());
50+
builder.setMetadata(A2ACommonFieldMapper.INSTANCE.metadataToProto(textPart.metadata()));
4951
} else if (domain instanceof FilePart filePart) {
5052
FileContent fileContent = filePart.file();
5153

@@ -68,10 +70,12 @@ default io.a2a.grpc.Part toProto(Part<?> domain) {
6870
builder.setMediaType(fileWithUri.mimeType());
6971
}
7072
}
73+
builder.setMetadata(A2ACommonFieldMapper.INSTANCE.metadataToProto(filePart.metadata()));
7174
} else if (domain instanceof DataPart dataPart) {
7275
// Map data to google.protobuf.Value (supports object, array, primitive, or null)
7376
Value dataValue = A2ACommonFieldMapper.INSTANCE.objectToValue(dataPart.data());
7477
builder.setData(dataValue);
78+
builder.setMetadata(A2ACommonFieldMapper.INSTANCE.metadataToProto(dataPart.metadata()));
7579
}
7680

7781
return builder.build();
@@ -85,26 +89,26 @@ default Part<?> fromProto(io.a2a.grpc.Part proto) {
8589
if (proto == null) {
8690
return null;
8791
}
88-
92+
Map<String, Object> metadata = A2ACommonFieldMapper.INSTANCE.metadataFromProto(proto.getMetadata());
8993
if (proto.hasText()) {
90-
return new TextPart(proto.getText());
94+
return new TextPart(proto.getText(), metadata);
9195
} else if (proto.hasRaw()) {
9296
// raw bytes → FilePart(FileWithBytes)
9397
String bytes = Base64.getEncoder().encodeToString(proto.getRaw().toByteArray());
9498
String mimeType = proto.getMediaType().isEmpty() ? null : proto.getMediaType();
9599
String name = proto.getFilename().isEmpty() ? null : proto.getFilename();
96-
return new FilePart(new FileWithBytes(mimeType, name, bytes));
100+
return new FilePart(new FileWithBytes(mimeType, name, bytes), metadata);
97101
} else if (proto.hasUrl()) {
98102
// url → FilePart(FileWithUri)
99103
String uri = proto.getUrl();
100104
String mimeType = proto.getMediaType().isEmpty() ? null : proto.getMediaType();
101105
String name = proto.getFilename().isEmpty() ? null : proto.getFilename();
102-
return new FilePart(new FileWithUri(mimeType, name, uri));
106+
return new FilePart(new FileWithUri(mimeType, name, uri), metadata);
103107
} else if (proto.hasData()) {
104108
// data (google.protobuf.Value containing any JSON value) → DataPart
105109
Value dataValue = proto.getData();
106110
Object data = A2ACommonFieldMapper.INSTANCE.valueToObject(dataValue);
107-
return new DataPart(data);
111+
return new DataPart(data, metadata);
108112
}
109113

110114
throw new InvalidRequestError();

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

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33

44
import io.a2a.util.Assert;
5+
import java.util.HashMap;
6+
import java.util.Map;
57
import org.jspecify.annotations.Nullable;
68

79

@@ -37,11 +39,12 @@
3739
* }</pre>
3840
*
3941
* @param data the structured data (required, supports JSON objects, arrays, primitives, and null)
42+
* @param metadata additional metadata for the part
4043
* @see Part
4144
* @see Message
4245
* @see Artifact
4346
*/
44-
public record DataPart(Object data) implements Part<Object> {
47+
public record DataPart(Object data, @Nullable Map<String, Object> metadata) implements Part<Object> {
4548

4649
/**
4750
* The JSON member name discriminator for data parts: "data".
@@ -64,6 +67,16 @@ public record DataPart(Object data) implements Part<Object> {
6467
Assert.checkNotNullParam("data", data);
6568
}
6669

70+
/**
71+
* Constructor.
72+
*
73+
* @param data the structured data (supports JSON objects, arrays, primitives, and not null)
74+
* @throws IllegalArgumentException if data is null
75+
*/
76+
public DataPart(Object data) {
77+
this(data, null);
78+
}
79+
6780
/**
6881
* Create a new Builder
6982
*
@@ -78,6 +91,7 @@ public static Builder builder() {
7891
*/
7992
public static class Builder {
8093
private @Nullable Object data;
94+
private @Nullable Map<String, Object> metadata;
8195

8296
/**
8397
* Creates a new Builder with all fields unset.
@@ -96,14 +110,25 @@ public Builder data(Object data) {
96110
return this;
97111
}
98112

113+
/**
114+
* Sets the metadata.
115+
*
116+
* @param metadata additional metadata for the part
117+
* @return this builder for method chaining
118+
*/
119+
public Builder metadata(@Nullable Map<String, Object> metadata) {
120+
this.metadata = (metadata == null) ? null : new HashMap<>(metadata);
121+
return this;
122+
}
123+
99124
/**
100125
* Builds a new {@link DataPart} from the current builder state.
101126
*
102127
* @return a new DataPart instance
103128
* @throws IllegalArgumentException if data is null
104129
*/
105130
public DataPart build() {
106-
return new DataPart(Assert.checkNotNullParam("data", data));
131+
return new DataPart(Assert.checkNotNullParam("data", data), metadata);
107132
}
108133
}
109134
}

‎spec/src/main/java/io/a2a/spec/FilePart.java‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33

44
import io.a2a.util.Assert;
5+
import java.util.Map;
6+
import org.jspecify.annotations.Nullable;
57

68

79
/**
@@ -31,12 +33,13 @@
3133
* }</pre>
3234
*
3335
* @param file the file content (required, either FileWithBytes or FileWithUri)
36+
* @param metadata additional metadata for the part
3437
* @see Part
3538
* @see FileContent
3639
* @see FileWithBytes
3740
* @see FileWithUri
3841
*/
39-
public record FilePart(FileContent file) implements Part<FileContent> {
42+
public record FilePart(FileContent file, @Nullable Map<String, Object> metadata) implements Part<FileContent> {
4043

4144
/**
4245
* The JSON member name discriminator for file parts: "file".
@@ -55,4 +58,14 @@ public record FilePart(FileContent file) implements Part<FileContent> {
5558
public FilePart {
5659
Assert.checkNotNullParam("file", file);
5760
}
61+
62+
/**
63+
* Constructor.
64+
*
65+
* @param file the file content (required, either FileWithBytes or FileWithUri)
66+
* @throws IllegalArgumentException if data is null
67+
*/
68+
public FilePart (FileContent file){
69+
this(file, null);
70+
}
5871
}

‎spec/src/main/java/io/a2a/spec/Message.java‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,12 @@
3535
* @see <a href="https://a2a-protocol.org/latest/">A2A Protocol Specification</a>
3636
*/
3737
public record Message(Role role, List<Part<?>> parts,
38-
String messageId, @Nullable
39-
String contextId,
40-
@Nullable
41-
String taskId, @Nullable
42-
List<String> referenceTaskIds,
43-
@Nullable
44-
Map<String, Object> metadata, @Nullable
45-
List<String> extensions
38+
String messageId,
39+
@Nullable String contextId,
40+
@Nullable String taskId,
41+
@Nullable List<String> referenceTaskIds,
42+
@Nullable Map<String, Object> metadata,
43+
@Nullable List<String> extensions
4644
) implements EventKind, StreamingEventKind {
4745

4846
/**

0 commit comments

Comments
 (0)