fix(spec): Suggest Unique Identifier fields to be UUID by holtskinner · Pull Request #966 · a2aproject/A2A

holtskinner · 2025-08-08T11:12:54Z

No description provided.

…artifactId` `messageId` to be UUID

gemini-code-assist

Summary of Changes

Hello @holtskinner, 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!

I've implemented a specification fix to enforce stricter data type validation for various identifier fields across our core TypeScript types. This change ensures that critical IDs such as taskId, contextId, pushNotificationConfigId, artifactId, and messageId are explicitly defined as UUIDs. The primary purpose of this update is to improve data integrity and consistency within our API specifications, making it clearer that these fields are expected to conform to the UUID format. This helps prevent potential data mismatches and enhances the reliability of our system's identifier handling.

Highlights

Task Interface ID Formatting: I've updated the Task interface to ensure that both id and contextId fields are explicitly formatted as UUIDs.
Event Interface ID Formatting: I've applied UUID formatting requirements to the taskId and contextId fields in both TaskStatusUpdateEvent and TaskArtifactUpdateEvent interfaces.
Task ID Parameters Formatting: I've enforced UUID formatting for the id field in the TaskIdParams interface, which is a base for many task-related operations.
Push Notification Configuration ID Formatting: I've updated the GetTaskPushNotificationConfigParams and DeleteTaskPushNotificationConfigParams interfaces to require pushNotificationConfigId to be a UUID.
Artifact ID Formatting: I've ensured that the artifactId field within the Artifact interface is now formatted as a UUID.
Message Interface ID Formatting: I've added UUID formatting requirements to messageId, taskId, and contextId fields within the Message interface, and specified that referenceTaskIds should be an array of UUIDs.
Push Notification Configuration ID Formatting: I've updated the PushNotificationConfig interface to require its id field to be a UUID.
Task Push Notification Configuration ID Formatting: I've ensured that the taskId field within the TaskPushNotificationConfig interface is now formatted as a UUID.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 or fill out our survey to provide feedback.

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.

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 aims to enforce UUID formats for various ID fields across the A2A specification, which is a valuable improvement for data consistency and validation. The changes in types/src/types.ts correctly add the @format uuid JSDoc annotation to the relevant fields.

However, there are a few critical issues that prevent this PR from achieving its goal:

JSON Schema Not Updated: The generated JSON schema at specification/json/a2a.json has not been updated to include the "format": "uuid" property for the changed fields. This means the primary goal of enforcing this format in the specification is not fully met. Please ensure the schema generation process is run and the updated file is included in this PR.
gRPC Spec Not Updated: Similarly, the gRPC specification at specification/grpc/a2a.proto has not been updated. While protobuf doesn't have a native UUID type, the comments for the ID fields should be updated to indicate they are UUIDs for documentation consistency.
Inconsistent Annotation: In the Message interface, referenceTaskIds has been updated with a comment indicating its items are UUIDs, but lacks a machine-readable annotation, which is inconsistent with the other changes.

I've added a specific comment with a suggestion for referenceTaskIds to address point 3.

types/src/types.ts

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

darrelmiller

Changes look good. It would be helpful in the specification to qualify that UUIDs are formatted as per the serialization described here https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-format

izzyacademy

Looks good to me. Thanks for the PR

specification/grpc/a2a.proto

kthota-g · 2025-08-11T17:22:38Z

hi, this would be a breaking change and won't be backward compatible. The SDKs we build are using UUIDs, but custom implementations that are currently targeting to support 0.3.0 may not be using UUIDs.

…uuid-fields

types/src/types.ts

🤖 I have created a release *beep* *boop* --- ## [1.0.0](v0.3.0...v1.0.0) (2026-03-12) ### ⚠ BREAKING CHANGES * **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](#1500)) * **spec:** remove duplicated ID from the create task push config request ([#1487](#1487)) * **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](#1486)) * **spec:** Add LF prefix to the package. ([#1474](#1474)) * **spec:** Switch to non-complex IDs in requests ([#1389](#1389)) * **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](#1283)) * **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](#1384)) * **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](#1308)) * **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](#1307)) * **spec:** Fixes for the last_updated_after field ([#1358](#1358)) * **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](#1303)) * **spec:** Make "message" field name consistent between protocol bindings ([#1302](#1302)) * **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](#1301)) * **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](#1222)) * **spec:** Remove v1s from a2a url http bindings * **spec:** Large refactor of specification to separate application protocol definition from mapping to transports ### Features * **spec:** Add `tasks/list` method with filtering and pagination to the specification ([0a9f629](0a9f629)) * **spec:** modernize oauth 2.0 flows - remove implicit/password, add device code / pkce ([#1303](#1303)) ([525ff38](525ff38)) * **spec:** Natively Support Multi-tenancy on gRPC through an additional scope field on the request. ([#1195](#1195)) ([cfbce32](cfbce32)), closes [#1148](#1148) * **spec:** Provide ability for SDKs to be backwards compatible. ([#1401](#1401)) ([227e249](227e249)) * **spec:** Remove v1s from a2a url http bindings ([1bd263f](1bd263f)) ### Bug Fixes * Add missing metadata field to Part message in gRPC specification ([#1019](#1019)) ([b3b266d](b3b266d)), closes [#1005](#1005) * Add name field to FilePart protobuf message ([#983](#983)) ([2b7cb6f](2b7cb6f)), closes [#984](#984) * Clarify blocking calls return on interrupted states ([#1403](#1403)) ([0655ff3](0655ff3)) * **doc:** Makes JSON-RPC SendMessage response clearer ([#1241](#1241)) ([5792804](5792804)) * **docs:** Clearer wording around context id. ([#1588](#1588)) ([dec790a](dec790a)) * **grpc:** Fix inconsistent property name between gRPC and JSON-RPC in Message object ([#1100](#1100)) ([2a1f819](2a1f819)) * **grpc:** missing field in gRPC spec - state_transition_history ([#1138](#1138)) ([a2de798](a2de798)), closes [#1139](#1139) * **grpc:** Update `CreateTaskPushNotificationConfig` endpoint to `/v1/{parent=tasks/*/pushNotificationConfigs}` ([#979](#979)) ([911f9b0](911f9b0)) * **proto:** Add icon_url to a2a.proto ([#986](#986)) ([17e7f62](17e7f62)) * **proto:** Adds metadata field to A2A DataPart proto ([#1004](#1004)) ([a8b45dc](a8b45dc)) * Remove unimplemented state_transition_history capability field ([#1396](#1396)) ([c768a44](c768a44)), closes [#1228](#1228) * Restore CreateTaskPushNotificationConfig method naming ([#1402](#1402)) ([d14f410](d14f410)) * Revert "chore(gRPC): Update a2a.proto to include metadata on GetTaskRequest" ([#1000](#1000)) ([e6b8c65](e6b8c65)) * Simplify Part message structure by flattening FilePart and DataPart ([#1411](#1411)) ([bfae8f7](bfae8f7)) * **spec:** Add LF prefix to the package. ([#1474](#1474)) ([a54e809](a54e809)) * **spec:** add metadata to `CancelTaskRequest` ([#1485](#1485)) ([c441b91](c441b91)), closes [#1484](#1484) * **spec:** Added clarification on timestamps in HTTP query params ([#1425](#1425)) ([6292104](6292104)) * **spec:** Added clarifying text around messages and artifacts ([#1424](#1424)) ([b03d141](b03d141)) * **spec:** Adjust field number for `ListTasksRequest.tenant` to prevent missing number ([#1470](#1470)) ([cd16c52](cd16c52)) * **spec:** Clarify contextId behavior when message is sent with taskId but without contextId ([#1309](#1309)) ([a336a5a](a336a5a)) * **spec:** Clarify versioning strategy and client responsibilities in protocol specification ([#1259](#1259)) ([a4afeea](a4afeea)) * **spec:** Fix/1251 clarify authentication scheme ([#1256](#1256)) ([3e6c7db](3e6c7db)) * **spec:** Fixes for the last_updated_after field ([#1358](#1358)) ([0e204bf](0e204bf)) * **spec:** Make "message" field name consistent between protocol bindings ([#1302](#1302)) ([1e5f462](1e5f462)), closes [#1230](#1230) * **spec:** make `history_length` optional ([#1071](#1071)) ([0572953](0572953)) * **spec:** pluralize configs in `ListTaskPushNotificationConfigs` ([#1486](#1486)) ([cf735cb](cf735cb)) * **spec:** Remove config from binding. ([#1587](#1587)) ([010b9cc](010b9cc)) * **spec:** Remove deprecated fields from a2a.proto for v1.0 release ([#1301](#1301)) ([60f83c3](60f83c3)), closes [#1227](#1227) * **spec:** remove duplicated ID from the create task push config request ([#1487](#1487)) ([393898d](393898d)) * **spec:** Remove metadata field from ListTasksRequest ([#1235](#1235)) ([b6ef9ee](b6ef9ee)) * **spec:** Remove reserved and fix tags ordering ([#1494](#1494)) ([1997c9d](1997c9d)) * **spec:** Rename `supportsAuthenticatedExtendedCard` to `supportsExtendedAgentCard` ([#1222](#1222)) ([c196824](c196824)), closes [#1215](#1215) * **spec:** Standardize spelling of "canceled" to use American Spelling throughout ([#1283](#1283)) ([4dd980f](4dd980f)) * **spec:** Suggest Unique Identifier fields to be UUID ([#966](#966)) ([00cf76e](00cf76e)) * **spec:** Switch to non-complex IDs in requests ([#1389](#1389)) ([2596c1c](2596c1c)), closes [#1390](#1390) * **spec:** Update security schemes example ([#1364](#1364)) ([f9a8f5b](f9a8f5b)) * Update the Java tutorials and descriptions ([#1181](#1181)) ([202aa06](202aa06)) ### Documentation * **spec:** Align enum format with ADR-001 ProtoJSON specification ([#1384](#1384)) ([810eaa1](810eaa1)), closes [#1344](#1344) ### Code Refactoring * **spec:** Combine `TaskPushNotificationConfig` and `PushNotificationConfig` ([#1500](#1500)) ([d1ed0da](d1ed0da)) * **spec:** Large refactor of specification to separate application protocol definition from mapping to transports ([b078419](b078419)) * **spec:** Move `extendedAgentCard` field to `AgentCapabilities` ([#1307](#1307)) ([40d6286](40d6286)) * **spec:** Remove redundant `final` field from `TaskStatusUpdateEvent` ([#1308](#1308)) ([5b101cc](5b101cc)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: Amye Scavarda Perrin <amye@amye.org> Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>

fix(spec)!: Require taskId contextId pushNotificationConfigId `…

179cfa3

…artifactId` `messageId` to be UUID

holtskinner requested a review from a team as a code owner August 8, 2025 11:12

chore: Auto-generate a2a.json from types.ts changes

8815ba9

gemini-code-assist bot reviewed Aug 8, 2025

View reviewed changes

types/src/types.ts Show resolved Hide resolved

holtskinner and others added 4 commits August 8, 2025 12:17

Update types/src/types.ts

d31c596

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

chore: Auto-generate a2a.json from types.ts changes

6b2f042

Merge branch 'main' into uuid-fields

33af279

Add UUID validation in gRPC Spec

e7a7bf8

holtskinner mentioned this pull request Aug 8, 2025

[Feat]: Explicitly define allowed ID formats (e.g. taskId, configId, etc.) #869

Open

1 task

Protolint

4e34c67

ognis1205 mentioned this pull request Aug 8, 2025

test: improve test coverage for grpc_client.py a2aproject/a2a-python#306

Merged

4 tasks

holtskinner and others added 3 commits August 8, 2025 17:11

fix protolint

39261e1

Update @items to include string and format

754cecd

chore: Auto-generate a2a.json from types.ts changes

f0cf8cb

darrelmiller approved these changes Aug 9, 2025

View reviewed changes

izzyacademy approved these changes Aug 10, 2025

View reviewed changes

specification/grpc/a2a.proto Outdated Show resolved Hide resolved

holtskinner force-pushed the uuid-fields branch from 8bb14c3 to f0cf8cb Compare August 11, 2025 16:25

izzymsft mentioned this pull request Aug 11, 2025

feat: Add correlation ID support for idempotent task creation #939

Open

holtskinner and others added 10 commits August 12, 2025 22:32

Update spec to suggest UUID in the description, but not require it

05e66ed

chore: Auto-generate a2a.json from types.ts changes

29cea0e

Change back tasks

06e1838

Merge branch 'uuid-fields' of https://github.com/a2aproject/A2A into …

7acbb01

…uuid-fields

Remove extra protolint comment

d16f88a

Get rid of import

941ba75

Undo other changes

5026666

remove extra characters

ee0184c

chore: Auto-generate a2a.json from types.ts changes

03dc1c4

Remove items

0f90031

holtskinner and others added 2 commits August 12, 2025 22:36

Merge branch 'uuid-fields' of https://github.com/a2aproject/A2A into …

dba26f3

…uuid-fields

chore: Auto-generate a2a.json from types.ts changes

18cbac2

holtskinner changed the title ~~fix(spec)!: Require taskId contextId pushNotificationConfigId artifactId messageId to be UUID~~ fix(spec): Suggest Unique Identifier fields to be UUID Aug 12, 2025

Merge branch 'main' into uuid-fields

859b742

kthota-g approved these changes Aug 13, 2025

View reviewed changes

types/src/types.ts Outdated Show resolved Hide resolved

holtskinner commented Aug 13, 2025

View reviewed changes

types/src/types.ts Outdated Show resolved Hide resolved

holtskinner and others added 3 commits August 13, 2025 20:37

Update types/src/types.ts

7e0ed57

chore: Auto-generate a2a.json from types.ts changes

c351ff6

Merge branch 'main' into uuid-fields

cc329ae

holtskinner merged commit 00cf76e into main Aug 13, 2025
4 of 5 checks passed

holtskinner deleted the uuid-fields branch August 13, 2025 19:56

a2a-bot mentioned this pull request Aug 13, 2025

chore(main): release 0.4.0 #974

Closed

a2a-bot mentioned this pull request Nov 21, 2025

chore(main): release 1.0.0 #1221

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(spec): Suggest Unique Identifier fields to be UUID#966

fix(spec): Suggest Unique Identifier fields to be UUID#966
holtskinner merged 26 commits intomainfrom
uuid-fields

holtskinner commented Aug 8, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

darrelmiller left a comment

Uh oh!

izzyacademy left a comment

Uh oh!

Uh oh!

kthota-g commented Aug 11, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

holtskinner commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

darrelmiller left a comment

Choose a reason for hiding this comment

Uh oh!

izzyacademy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kthota-g commented Aug 11, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

holtskinner commented Aug 8, 2025 •

edited

Loading