fix!: rewrite PartTypeAdapter to use flat JSON format for Part serialization

[ehsavoie]

Replace the nested "file" wrapper with flat fields (raw, url, filename, mediaType) aligned with the proto Part message schema and A2A spec.

Fixes #689 🦕

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the JSON serialization and deserialization of Part objects, particularly FilePart, to adopt a flat JSON structure. This change eliminates the nested 'file' wrapper, directly exposing content fields like 'raw', 'url', 'filename', and 'mediaType'. The primary goal is to standardize the JSON format for Part objects, ensuring better alignment with the A2A specification and protobuf message schemas, which simplifies integration and improves data consistency across systems. The update also includes adjustments to gRPC serialization to ensure all fields are consistently printed.

Highlights

• PartTypeAdapter Refactoring: The PartTypeAdapter in JsonUtil.java was completely rewritten to serialize and deserialize FilePart objects using a flat JSON structure, replacing the previously nested 'file' wrapper object.
• Flat JSON Format for FilePart: FilePart serialization now uses direct fields such as 'raw', 'url', 'filename', and 'mediaType' at the top level of the Part object, aligning with the A2A specification and proto schema.
• Improved Deserialization Robustness: The deserialization logic for PartTypeAdapter was enhanced to gracefully handle JSON formats where multiple content keys might be present, but only one is populated, common in proto serialization.
• gRPC Serialization Update: The JsonFormat.printer() in JSONRPCUtils.java was updated to use alwaysPrintFieldsWithNoPresence() instead of includingDefaultValueFields() for more consistent JSON output from gRPC payloads.
• Comprehensive Test Coverage: A new test file, PartTypeAdapterTest.java, was added to provide extensive test coverage for the serialization and deserialization of TextPart, FilePart (both FileWithBytes and FileWithUri), and DataPart with the new flat JSON format, including round-trip tests and metadata handling.

Changelog

• jsonrpc-common/src/main/java/io/a2a/jsonrpc/common/json/JsonUtil.java
  • Removed the import for io.a2a.spec.FilePart.FILE.
  • Introduced new constants RAW, URL, FILENAME, and MEDIA_TYPE for the flat JSON fields.
  • Updated the VALID_KEYS set to include RAW and URL as content discriminators.
  • Added private helper methods writeMetadata and writeNonEmpty to streamline JSON writing.
  • Rewrote the write method in PartTypeAdapter to serialize FilePart instances into a flat JSON structure based on FileWithBytes or FileWithUri.
  • Modified the read method in PartTypeAdapter to deserialize FilePart from the new flat JSON format, using RAW or URL as discriminators.
  • Implemented a stringOrEmpty helper method for robust retrieval of string values during deserialization.
• jsonrpc-common/src/test/java/io/a2a/jsonrpc/common/json/TaskSerializationTest.java
  • Updated the testTaskWithFilePartBytes method to assert the presence of the raw field instead of the file wrapper in the serialized JSON.
  • Modified the JSON string in testDeserializeTaskWithFilePartBytesFromJson to reflect the new flat format for FileWithBytes.
  • Adjusted the JSON string in testDeserializeTaskWithFilePartUriFromJson to reflect the new flat format for FileWithUri.
• spec-grpc/src/main/java/io/a2a/grpc/utils/JSONRPCUtils.java
  • Changed JsonFormat.printer().includingDefaultValueFields() to JsonFormat.printer().alwaysPrintFieldsWithNoPresence() in toJsonRPCRequest and toJsonRPCResultResponse methods to ensure all fields are printed.
• spec-grpc/src/test/java/io/a2a/grpc/utils/PartTypeAdapterTest.java
  • Added a new test file to validate the PartTypeAdapter's functionality.
  • Included tests for TextPart serialization, deserialization, and round-trip with and without metadata.
  • Added tests for FilePart with FileWithBytes serialization, deserialization, and round-trip, including metadata handling.
  • Added tests for FilePart with FileWithUri serialization, deserialization, and round-trip, including metadata handling.
  • Included tests for DataPart serialization, deserialization, and round-trip for various data types (object, array, string, number), including metadata handling.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request refactors the PartTypeAdapter to serialize Part objects, especially FilePart, into a flat JSON format, aligning with the A2A specification and protobuf schema. The changes involve updating the serialization and deserialization logic in JsonUtil.java, modifying related tests, and adding new comprehensive tests for the PartTypeAdapter. The use of alwaysPrintFieldsWithNoPresence for protobuf serialization is a good improvement for robustness. No security vulnerabilities were identified. A high-severity issue was found in the PartTypeAdapter's write method where a new private writeMetadata helper is used inconsistently and incorrectly, potentially leading to serialization errors if metadata contains Part objects. A suggestion has been provided to fix this by consistently using the existing static JsonUtil.writeMetadata method.

[jmesnil]

When I look at the test, I wonder if we should improve the FileWithBytes class to take in parameter a java.io.File and handles the Base64 conversion from the file's bytes internally?
That'd make for a much simpler UX. wdyt?

[ehsavoie]

I've created #702 to track your suggestion