- Move a2a.proto to specification/ root - Update build scripts and macros to support new proto location - Fix broken internal links and anchor references in specification.md - Update .gitignore to properly exclude generated SDK docs - Configure Sphinx to suppress external SDK warnings - Fix MkDocs redirects and Python SDK toctree structure --------- Signed-off-by: Luca Muscariello <muscariello@ieee.org>
A2A JSON Artifact
a2a.json is a non-normative build artifact derived from the canonical proto definition at specification/a2a.proto. It is generated during builds and intentionally not committed to source control.
Generation pipeline:
scripts/proto_to_json_schema.shconverts proto directly to JSON Schema using bufbuild'sprotoc-gen-jsonschemaplugin.- The resulting
a2a.json(JSON Schema 2020-12 bundle) is copied todocs/spec/a2a.jsonfor site publishing.
The build uses protoc with protoc-gen-jsonschema plugin and jq for bundling. Only source (a2a.proto) and scripts remain under version control.
The artifact is generated automatically in:
- Local docs builds (
scripts/build_docs.sh)
Do Not Edit
Do NOT edit a2a.json manually. Update the proto instead. The file is transient and will be regenerated.
Building the A2A JSON Artifact Locally
To build the a2a.json artifact locally, you'll need several dependencies depending on your operating system. This is useful for contributors who want to preview changes before submitting pull requests.
macOS/Linux
Prerequisites for macOS/Linux
-
Homebrew (macOS) or apt-get (Debian/Ubuntu)
- macOS: Install from brew.sh
- Debian/Ubuntu:
apt-getis pre-installed.
-
Python with pip
# Verify installation: python3 --version pip3 --version -
Core build tools (
protoc,go,jq)-
macOS:
brew install protobuf go jq -
Debian/Ubuntu:
sudo apt-get update && sudo apt-get install -y protobuf-compiler golang jq
-
-
protoc-gen-jsonschema plugin
# Install via Go (requires Go to be installed first): go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest -
Clone googleapis repository
# Clone to a location like $HOME/googleapis git clone https://github.com/googleapis/googleapis.git $HOME/googleapis export GOOGLEAPIS_DIR=$HOME/googleapis # To persist this, add the export command to your shell profile (e.g., ~/.zshrc or ~/.bashrc) echo 'export GOOGLEAPIS_DIR=$HOME/googleapis' >> ~/.bashrc -
Python documentation dependencies
# Create and activate virtual environment: python3 -m venv .venv-docs source .venv-docs/bin/activate # Install requirements: pip install -r requirements-docs.txt
Building the A2A JSON Artifact on macOS/Linux
Once all prerequisites are installed:
# Run the build script:
./scripts/build_docs.sh
This script handles all necessary steps to generate the a2a.json artifact and build the documentation site.
Windows
Windows Prerequisites
-
Python with pip (for MkDocs)
# Install Python from python.org or via Microsoft Store # Verify installation: python --version pip --version -
Protocol Buffers compiler (protoc)
# Install via WinGet (recommended): winget install Google.Protobuf # Verify installation: protoc --version -
Go programming language (for protoc-gen-jsonschema plugin)
# Install via WinGet: winget install GoLang.Go # Or download from https://golang.org/dl/ # Verify installation: go version -
protoc-gen-jsonschema plugin
# Install via Go (requires Go to be installed first): go install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest # Verify installation (should be in your Go bin directory): protoc-gen-jsonschema --version -
jq (JSON processor)
# Install via WinGet: winget install jqlang.jq # Verify installation: jq --version -
Clone googleapis repository
# Clone to any location and set environment variable: git clone https://github.com/googleapis/googleapis.git C:\path\to\googleapis $env:GOOGLEAPIS_DIR = "C:\path\to\googleapis" # To persist this setting, add the following line to your PowerShell profile. # You can open your profile for editing by running: notepad $PROFILE $env:GOOGLEAPIS_DIR = "C:\path\to\googleapis" -
Python documentation dependencies
# Create and activate virtual environment: python -m venv .venv-docs .\.venv-docs\Scripts\Activate.ps1 # Install requirements: pip install -r requirements-docs.txt
Building the A2A JSON Artifact on Windows
Once all prerequisites are installed:
# Run the build script:
.\scripts\build_docs.ps1
# The documentation will be generated in the ./site directory
# Open site/index.html in your browser to view locally
The build script will:
- Generate JSON Schema from Protocol Buffer definitions
- Build the MkDocs site with all content
Troubleshooting
- protoc errors: Ensure both
protocand the googleapis directory are properly configured - jq not found: Ensure jq is installed and in your
PATH - Python import errors: Activate the virtual environment and ensure all requirements are installed
- Missing schemas: Check that
protoc-gen-jsonschemais in yourPATH(rungo env GOPATHto find Go bin directory)
Future Work
Planned improvements include:
- Optional OpenAPI v3 conversion and publishing a draft 2020-12
components.schemasbundle. - Automatic alias injection for deprecated names (anyOf wrapper) to ease migrations.
- Validation step ensuring no generated artifacts are reintroduced into git.