refactor(spec): Update HTTP+JSON error mapping to use google.rpc.Status AIP-193

[mikeas1]

Updates the specification to require use of google.rpc.Status formatted JSON objects for error response bodies in HTTP+JSON mapping.

See related issue for reasoning.

Fixes #1596

[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 refines the specification for HTTP+JSON error responses by adopting the google.rpc.Status structure. This change aims to standardize error handling across the protocol, providing a more consistent and structured approach for communicating errors, which enhances interoperability and clarity for implementers.

Highlights

• Error Mapping Standardized: The HTTP+JSON error mapping has been updated to exclusively use the google.rpc.Status format, replacing the previous RFC 9457 Problem Details specification.
• Simplified Error Table: The HTTP Type URI column was removed from the A2A error type mapping table, as the new google.rpc.Status format handles error identification differently.
• Detailed A2A Error Representation: New guidelines specify how A2A-specific errors should be embedded within google.rpc.Status using google.rpc.ErrorInfo messages, including reason, domain, and metadata fields.
• Updated Example: The HTTP error response example was revised to demonstrate the new google.rpc.Status structure.

Changelog

• docs/specification.md
  • Removed the "HTTP Type URI" column from the A2A error mapping table.
  • Updated the "Error Handling" section to mandate the use of google.rpc.Status for HTTP error responses.
  • Added detailed instructions for representing A2A-specific errors within google.rpc.Status using google.rpc.ErrorInfo.
  • Replaced the RFC 9457 Problem Details example with a google.rpc.Status formatted error response example.

Activity

• No specific activity (comments, reviews, progress) was provided in the context.

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 updates the specification to use google.rpc.Status for HTTP+JSON error responses, replacing the previous RFC 9457 Problem Details format. The changes in docs/specification.md accurately reflect this, including updates to the error mapping table and the error handling section with a new example. My review focuses on maintaining the clarity and consistency of the documentation. I've suggested restoring a couple of internal links for easier navigation and adjusting a key in an example to align with the project's JSON naming conventions.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[darrelmiller]

I will add a note to align the data property of JSONRPC errors with the details property of status code.

Need to confirm with @mikeas1 that removing the outer "error" member that AIP uses will not break transcoding.

[darrelmiller]

@mikeas1 I made a PR into your PR mikeas1#2

[mikeas1]

Need to confirm with @mikeas1 that removing the outer "error" member that AIP uses will not break transcoding.

I will double check this today.

[mikeas1]

I did a quick review of gRPC Gateway, Envoy, and .NET transcoding. All of these seem to directly transcode the google.rpc.Status value into the HTTP response body. gRPC Gateway supports registering a custom error transcoder, but I did not find an equivalent for Envoy.

Google's transcoding system adheres to AIP-193, which puts it at odds with the others.

I'm torn. Google is almost certainly going to be the primary user of gRPC transcoding, so aligning errors to match how that works is very useful. But this will make it harder for anyone else using transcoding to be adherent to the spec. However, it should be possible to be adherent, and with additional SDK support we can paper over this gap. So, I'm inclined to align the spec with AIP-193.

[muscariello]

LGTM