feat(spec): Switch to bufbuild protoc-gen-jsonschema for JSON Schema generation by muscariello · Pull Request #1205 · a2aproject/A2A

muscariello · 2025-11-13T22:20:41Z

Summary

Switch from protoc-gen-openapi to bufbuild's protoc-gen-jsonschema plugin for cleaner and more standards-compliant JSON Schema generation.

Changes

Replace protoc-gen-openapi with bufbuild's protoc-gen-jsonschema plugin
Generate JSON Schema 2020-12 compliant bundle with camelCase field names
Bundle all 49 message definitions with clean names (no a2a.v1. prefix)
Update devcontainer setup.sh to install new plugin
Update specification/json/README.md with new generation pipeline
Add codespace to spelling allowlist

Benefits

Cleaner JSON Schema output with proper camelCase field names
Supports latest JSON Schema 2020-12 standard
All 49 message definitions included in single bundle
Clean definition names without package prefixes

related to #1160

gemini-code-assist · 2025-11-13T22:21:02Z

Summary of Changes

Hello @muscariello, 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 Schema generation pipeline by replacing the protoc-gen-openapi tool with bufbuild/protoc-gen-jsonschema. This change aims to produce a more modern, standards-compliant, and user-friendly JSON Schema output, featuring camelCase field names and a consolidated bundle of all message definitions with simplified naming. The development environment and documentation have been updated to reflect this new approach, streamlining the process for generating and consuming A2A protocol schemas.

Highlights

JSON Schema Generation Tooling: Switched from protoc-gen-openapi to bufbuild/protoc-gen-jsonschema for generating JSON Schemas from Protocol Buffers, improving the generation process.
Schema Compliance and Formatting: The new generation process produces JSON Schema 2020-12 compliant output with proper camelCase field names, enhancing readability and adherence to modern standards.
Bundled Definitions: All 49 message definitions are now bundled into a single JSON Schema file, featuring clean, package-prefix-free names for easier consumption.
Development Environment Updates: The devcontainer setup has been updated to include the new protoc-gen-jsonschema plugin, and related documentation has been revised to reflect these changes.
Spelling Allowlist Expansion: New terms such as codespace, jqlang, mcr, mikefarah, pylance, and winget have been added to the spelling allowlist.

Ignored Files

Ignored by pattern: .github/workflows/** (1)
- .github/workflows/generate-a2a-json.yml

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.

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 is a great improvement, switching the JSON Schema generation from protoc-gen-openapi to the more modern bufbuild/protoc-gen-jsonschema. This results in cleaner and more standards-compliant schemas. The addition of a devcontainer is a welcome change for ensuring a consistent development environment. The script updates are logical and the new proto_to_json_schema.sh script is well-implemented. I've identified a couple of minor issues in documentation and a small opportunity for simplification in one of the new setup scripts. Overall, this is a high-quality contribution that enhances the project's tooling.

gemini-code-assist · 2025-11-13T22:22:21Z

.devcontainer/README.md

+
+### Build Tools
+- **protoc** (v28.3) - Protocol Buffers compiler
+- **protoc-gen-openapi** (gnostic) - OpenAPI v3 generator for protobuf


The list of build tools incorrectly mentions protoc-gen-openapi, which is the tool being replaced by this pull request. This should be updated to protoc-gen-jsonschema to accurately reflect the new development environment.

Suggested change

- **protoc-gen-openapi** (gnostic) - OpenAPI v3 generator for protobuf

- **protoc-gen-jsonschema** (bufbuild) - JSON Schema generator for protobuf

gemini-code-assist · 2025-11-13T22:22:21Z

specification/json/README.md

   ```

-3. **Go programming language** (for protoc-gen-openapiv2 plugin)
+3. **Go programming language** (for protoc-gen-openapi plugin)


There's a small typo in the plugin name. It should be protoc-gen-jsonschema to match the new tooling, not protoc-gen-openapi.

Suggested change

3. **Go programming language** (for protoc-gen-openapi plugin)

3. **Go programming language** (for protoc-gen-jsonschema plugin)

gemini-code-assist · 2025-11-13T22:22:21Z

.devcontainer/setup.sh

+if [ -f "$HOME/go/bin/protoc-gen-jsonschema" ]; then
+  sudo cp "$HOME/go/bin/protoc-gen-jsonschema" /usr/local/bin/
+elif [ -f "$(go env GOPATH)/bin/protoc-gen-jsonschema" ]; then
+  sudo cp "$(go env GOPATH)/bin/protoc-gen-jsonschema" /usr/local/bin/
+fi


The logic to find and copy the protoc-gen-jsonschema binary can be simplified. Instead of checking a hardcoded default path before checking the GOPATH from the environment, it's more robust to rely solely on go env GOPATH, which should be the single source of truth in the devcontainer environment.

Suggested change

if [ -f "$HOME/go/bin/protoc-gen-jsonschema" ]; then

sudo cp "$HOME/go/bin/protoc-gen-jsonschema" /usr/local/bin/

elif [ -f "$(go env GOPATH)/bin/protoc-gen-jsonschema" ]; then

sudo cp "$(go env GOPATH)/bin/protoc-gen-jsonschema" /usr/local/bin/

fi

go_bin_path="$(go env GOPATH)/bin/protoc-gen-jsonschema"

if [ -f "$go_bin_path" ]; then

sudo cp "$go_bin_path" /usr/local/bin/

fi

- Replace generate_openapi.sh and extract_json_schema.sh with single proto_to_json_schema.sh - Remove obsolete types/ folder (proto is now the source of truth) - Remove redundant generate-a2a-json GitHub workflow - Update build_docs.sh and build_llms_full.sh to use new unified script - Update specification/json/README.md with new workflow documentation Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Use go env GOPATH as single source of truth instead of checking multiple hardcoded paths. Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Add Debian to allowlist and sort alphabetically. Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

holtskinner · 2025-11-14T16:30:21Z

docs/spec-json.md

The spec-json and spec-proto pages can be combined into a single page and use tabs similar to how specification.md does now

# A2A Definition/Schema === "JSON" The A2A protocol JSON Schema definition (JSON Schema 2020-12 compliant). This schema is automatically generated from the protocol buffer definitions and bundled into a single file with all message definitions. ## Download You can download the schema file directly: [a2a.json](spec-json/a2a.json) ## Schema Definition ```json --8<-- "spec-json/a2a.json" ``` === "gRPC" The normative A2A protocol definition in Protocol Buffers (proto3 syntax). This is the source of truth for the A2A protocol specification. ## Download You can download the proto file directly: [a2a.proto](spec-proto/a2a.proto) ## Protocol Definition ```protobuf --8<-- "spec-proto/a2a.proto" ```

holtskinner

When I tried to run the new build_docs.sh I got errors

$ ./scripts/build_docs.sh
[build_docs] Checking schema freshness...
[build_docs] Regenerating a2a.json from proto
→ Generating JSON Schema from proto...
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=SendMessageConfiguration.json msg_name=SendMessageConfiguration proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=Task.json msg_name=Task proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=TaskStatus.json msg_name=TaskStatus proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=Part.json msg_name=Part proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=FilePart.json msg_name=FilePart proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=DataPart.json msg_name=DataPart proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=Message.json msg_name=Message proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=Artifact.json msg_name=Artifact proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=TaskStatusUpdateEvent.json msg_name=TaskStatusUpdateEvent proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=TaskArtifactUpdateEvent.json msg_name=TaskArtifactUpdateEvent proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=PushNotificationConfig.json msg_name=PushNotificationConfig proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AuthenticationInfo.json msg_name=AuthenticationInfo proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AgentInterface.json msg_name=AgentInterface proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AgentCard.json msg_name=AgentCard proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AgentProvider.json msg_name=AgentProvider proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AgentCapabilities.json msg_name=AgentCapabilities proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AgentExtension.json msg_name=AgentExtension proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AgentSkill.json msg_name=AgentSkill proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AgentCardSignature.json msg_name=AgentCardSignature proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=TaskPushNotificationConfig.json msg_name=TaskPushNotificationConfig proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=StringList.json msg_name=StringList proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=Security.json msg_name=Security proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=SecurityScheme.json msg_name=SecurityScheme proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=APIKeySecurityScheme.json msg_name=APIKeySecurityScheme proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=HTTPAuthSecurityScheme.json msg_name=HTTPAuthSecurityScheme proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=OAuth2SecurityScheme.json msg_name=OAuth2SecurityScheme proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=OpenIdConnectSecurityScheme.json msg_name=OpenIdConnectSecurityScheme proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=MutualTlsSecurityScheme.json msg_name=MutualTlsSecurityScheme proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=OAuthFlows.json msg_name=OAuthFlows proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=AuthorizationCodeOAuthFlow.json msg_name=AuthorizationCodeOAuthFlow proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=ClientCredentialsOAuthFlow.json msg_name=ClientCredentialsOAuthFlow proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=ImplicitOAuthFlow.json msg_name=ImplicitOAuthFlow proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=PasswordOAuthFlow.json msg_name=PasswordOAuthFlow proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=SendMessageRequest.json msg_name=SendMessageRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=GetTaskRequest.json msg_name=GetTaskRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=ListTasksRequest.json msg_name=ListTasksRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=ListTasksResponse.json msg_name=ListTasksResponse proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=CancelTaskRequest.json msg_name=CancelTaskRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=GetTaskPushNotificationConfigRequest.json msg_name=GetTaskPushNotificationConfigRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=DeleteTaskPushNotificationConfigRequest.json msg_name=DeleteTaskPushNotificationConfigRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=SetTaskPushNotificationConfigRequest.json msg_name=SetTaskPushNotificationConfigRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=SubscribeToTaskRequest.json msg_name=SubscribeToTaskRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=ListTaskPushNotificationConfigRequest.json msg_name=ListTaskPushNotificationConfigRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=GetExtendedAgentCardRequest.json msg_name=GetExtendedAgentCardRequest proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=SendMessageResponse.json msg_name=SendMessageResponse proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=StreamResponse.json msg_name=StreamResponse proto_filename=a2a.proto
INFO[0000] Generating JSON-schema for MESSAGE            jsonschema_filename=ListTaskPushNotificationConfigResponse.json msg_name=ListTaskPushNotificationConfigResponse proto_filename=a2a.proto
→ Creating JSON Schema bundle...
jq: error: Could not open file /var/folders/31/njc6g6wx60b9w8cyw2kbfp6h00jt0h/T/tmp.IkxOfFxOUM/*.jsonschema.json: No such file or directory
[build_docs] Warning: proto to JSON schema conversion failed

mkdocs.yml

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

muscariello · 2025-11-17T16:38:51Z

@holtskinner seems ok. Can you check the script in the devcontainer env ? I am not sure why it fails for you but it must not fail in the clean container. Let me know. Thanks !

muscariello requested a review from a team as a code owner November 13, 2025 22:20

gemini-code-assist bot reviewed Nov 13, 2025

View reviewed changes

muscariello added 2 commits November 13, 2025 23:26

chore: provide a dev environment in container for vscode

82d5cb3

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

muscariello force-pushed the feat/jsonschema-build-system branch from 1519bb8 to 82d5cb3 Compare November 13, 2025 22:29

refactor(devcontainer): simplify protoc-gen-jsonschema installation

9064791

Use go env GOPATH as single source of truth instead of checking multiple hardcoded paths. Signed-off-by: Luca Muscariello <muscariello@ieee.org>

muscariello linked an issue Nov 13, 2025 that may be closed by this pull request

Spec Update for Transport Support #1151

Open

muscariello self-assigned this Nov 13, 2025

muscariello requested a review from a team as a code owner November 13, 2025 23:03

muscariello requested a review from darrelmiller November 13, 2025 23:04

muscariello added 5 commits November 14, 2025 09:56

chore: fix warnings

183903a

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: fix warnings

f329dd7

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: sort spelling allowlist

15b73ce

Add Debian to allowlist and sort alphabetically. Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: fix warnings

4262fa1

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: publish spec files

c2ecf40

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

muscariello force-pushed the feat/jsonschema-build-system branch from 2e094f0 to c2ecf40 Compare November 14, 2025 08:56

muscariello added 4 commits November 14, 2025 11:07

chore: publish spec files

c480132

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: publish spec files

ce6ee54

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: publish spec files

f22c1c0

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: publish spec files

0d9f22f

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

muscariello mentioned this pull request Nov 14, 2025

docs(spec): Large refactor of specification to separate application protocol definition from mapping to transports. #1160

Merged

chore: publish spec files

7e2410d

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

holtskinner reviewed Nov 14, 2025

View reviewed changes

holtskinner requested changes Nov 14, 2025

View reviewed changes

mkdocs.yml Show resolved Hide resolved

mkdocs.yml Show resolved Hide resolved

mkdocs.yml Show resolved Hide resolved

muscariello added 5 commits November 15, 2025 21:52

chore: update build

f286d58

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: fix workflow

0447953

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: fix workflow

93c8a5b

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: fix workflow

d65e0ff

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: rename spec.md to definitions.md

3b99dee

muscariello added 3 commits November 17, 2025 17:01

chore: fix workflow

1078162

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: fix workflow

bb446ef

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: fix workflow

39b483f

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

darrelmiller approved these changes Nov 17, 2025

View reviewed changes

amye added this to TSC Review Nov 17, 2025

amye moved this to Backlog in TSC Review Nov 17, 2025

amye removed this from TSC Review Nov 17, 2025

muscariello merged commit ccbb76f into a2aproject:transports Nov 18, 2025
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(spec): Switch to bufbuild protoc-gen-jsonschema for JSON Schema generation#1205

feat(spec): Switch to bufbuild protoc-gen-jsonschema for JSON Schema generation#1205
muscariello merged 21 commits intoa2aproject:transportsfrom
muscariello:feat/jsonschema-build-system

muscariello commented Nov 13, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Nov 13, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Nov 13, 2025

Uh oh!

gemini-code-assist bot Nov 13, 2025

Uh oh!

gemini-code-assist bot Nov 13, 2025

Uh oh!

holtskinner Nov 14, 2025

Uh oh!

muscariello Nov 14, 2025

Uh oh!

holtskinner left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

muscariello commented Nov 17, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	- protoc-gen-openapi (gnostic) - OpenAPI v3 generator for protobuf
	- protoc-gen-jsonschema (bufbuild) - JSON Schema generator for protobuf

	3. Go programming language (for protoc-gen-openapi plugin)
	3. Go programming language (for protoc-gen-jsonschema plugin)

Conversation

muscariello commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Benefits

Uh oh!

gemini-code-assist bot commented Nov 13, 2025

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!

gemini-code-assist bot Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

holtskinner Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

muscariello Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

holtskinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

muscariello commented Nov 17, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

muscariello commented Nov 13, 2025 •

edited

Loading