## Summary
- Adds `docs/topics/custom-protocol-bindings.md`, a dedicated page
documenting custom protocol bindings as a concept distinct from
extensions; covers declaration in the Agent Card, specification
requirements, key areas to address (data type mappings, service
parameters, error mapping, streaming, authentication), and
interoperability testing
- Adds `docs/topics/extension-and-binding-governance.md`, merging the
governance content previously in `extensions.md` with the equivalent
custom protocol binding governance; deduplicates the tiers section into
a single section with a naming table; notes that SDKs SHOULD implement
official custom protocol bindings vs MAY for extensions
- Adds spec section 5.8 defining URI-based custom binding identification
as a SHOULD requirement and updates the section 12.7 Agent Card example
accordingly
- Replaces the verbose inline governance sections in `extensions.md` and
`custom-protocol-bindings.md` with short summaries linking to the new
governance page
- Adds Custom Protocol Bindings and Extension & Binding Governance to
the mkdocs.yml nav
---------
Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Fixes#1612
Section 6.5 examples used `POST /tasks/list` with a JSON body,
contradicting section 11.3.2 which correctly defines list tasks as `GET
/tasks` with query parameters.
## Changes
- **`docs/specification.md` — Section 6.5 (Task Listing and
Management):** Updated all four HTTP examples to use `GET /tasks` with
query parameters instead of `POST /tasks/list` with a request body:
| Example | Before | After |
|---|---|---|
| All tasks from a specific context | `POST /tasks/list` + JSON body |
`GET /tasks?contextId=...&pageSize=10&historyLength=3` |
| All working tasks across all contexts | `POST /tasks/list` + JSON body
| `GET /tasks?status=working&pageSize=20` |
| Pagination | `POST /tasks/list` + JSON body | `GET
/tasks?contextId=...&pageSize=10&pageToken=...` |
| Validation error | `POST /tasks/list` + JSON body | `GET
/tasks?pageSize=150&historyLength=-5&status=running` |
Enum values in query parameters now use the short form (e.g.,
`status=working`) per the field type handling rules already defined in
section 11.5.
<!-- START COPILOT CODING AGENT TIPS -->
---
✨ Let Copilot coding agent [set things up for
you](https://github.com/a2aproject/A2A/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: darrelmiller <447694+darrelmiller@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Closes#1478. Related to #306.
The specification provides caching guidance for Extended Agent Cards
(Sections 3.1.11 and 13.3) but has no equivalent guidance for public
Agent Cards. This creates a gap for SDK and framework implementers —
none of the five official SDKs currently implement Agent Card caching,
and framework implementers have noted the lack of protocol-level
guidance (google/adk-python#3297).
This PR adds SHOULD-level HTTP caching guidance, following the precedent
of OpenID Connect Discovery 1.0 (same `.well-known` URI pattern).
**Changes:**
- **`docs/specification.md`**: Add Section 8.6 "Caching" with normative
guidance on `Cache-Control`, `ETag`, and conditional requests. Placed
after Section 8.5 (Sample Agent Card) to avoid renumbering existing
sections and breaking anchor links.
- **`docs/topics/agent-discovery.md`**: Add "Caching Considerations"
section with practical guidance for implementers.
---------
Co-authored-by: Darrel <darrmi@microsoft.com>
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
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
The previous wording was very barebones. We have explored this area
significantly more, and the specification now reflects further guidance
on how to handle retrieving authorizations and credentials during Task
processing.
This specifically addresses the missing guidance on how clients are
expected to respond to a Task in `TASK_STATE_AUTH_REQUIRED`.
Fixes#1582.
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
As mentioned in the linked issue, defaulting to non-blocking behavior is
counterintuitive and is implemented the opposite way in the SDKs.
Renaming it to `return_immediately` makes default behavior simpler while
advanced scenario requires an extra flag.
---
Previos proposals:
1. `polling` has inaccurate meaning in this context as pointed out in
the comments.
2. `non_blocking` is a negative boolean which leads to confusing
conditional expressions (`not non_blocking`).
Fixes#1453
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
client side context id passing can be supported, server can choose to
reject, client's should know how to fallback accordingly
if server accepts, server must respond with the context id
if server cannot accept client side context id it MUST respond with an
error (i.e. it SHOULD not respond with a task with a different context
id?)
servers may not accept a client side context id for a number of reasons:
clashes, validation errors, not supporting context ids
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
## Summary
Fixes documentation inconsistencies related to Part discriminator field
values, identified in #1365.
## Changes
### `docs/specification.md` — Appendix A.2.1
- **Legacy Part `kind` values**: corrected from PascalCase (`"kind":
"TextPart"`, `"kind": "FilePart"`, `"kind": "DataPart"`) to lowercase
(`"kind": "text"`, `"kind": "file"`, `"kind": "data"`), consistent with
what `whats-new-v1.md` documents as the v0.3.0 format
- **Legacy FilePart structure**: added the missing nested `file` object
wrapper
- **Legacy streaming event `kind` values**: corrected from PascalCase
(`TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`) to camelCase
(`taskStatusUpdate`, `taskArtifactUpdate`)
- **Current `DataPart` migration target**: removed incorrect
double-wrapping (`{ "data": { "data": {...} } }` → `{ "data": {...},
"mediaType": "application/json" }`)
- **Current streaming event member names**: aligned with
`whats-new-v1.md` (`taskStatusUpdate` / `taskArtifactUpdate`)
### `docs/topics/key-concepts.md`
- Updated Part description to use v1.0 terminology, removing references
to the removed `TextPart`, `FilePart`, and `DataPart` types
### `docs/tutorials/python/8-next-steps.md`
- Replaced reference to removed `DataPart` type with v1.0 Part field
names
### `CONTRIBUTING.md`
- Added **Documentation Guidelines** section with correct v1.0 Part
examples (member-presence pattern) and guidance on the correct v0.3.x
lowercase `kind` discriminator values for migration docs
## Related
- Closes#1365
- External community site fix:
https://github.com/sing1ee/a2a-directory/pull/12🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Gijs Walraven <gijs.walraven@delaware.pro>
This corrects the wording so that blocking=True includes terminal and
interrupted states as triggers for returning to the client.
Fixes: #1264
---------
Signed-off-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Pluralize PushNotificationConfig in ListTaskPushNotificationConfig
request and responses.
This is consistent with ListTasks.
Part of #1451
---------
Co-authored-by: Kuba Herczyński <herczyn@google.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
* Removed outdated part format from examples
* Added a missing TaskNotFoundError to non-streaming rpc errors list
* Removed outdated final flag from status update examples
The referenced issues has some other things:
1. Should ListTaskPushNotificationConfig be pluralized into
ListTaskPushNotificationConfigs?
2. Should all request operating on push configs settle on either
configID or ID naming. Create vs (Delete|List|Get) RPCs differ at the
moment.
3. In CreateRequest we have ID based on the request root level and in
config payload. Should the former be removed?
https://github.com/a2aproject/A2A/issues/1451
Convert bespoke `macros.py` to use `proto-schema-parser` and `tabulate`
to display tables
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
In the future, we should probably explore refactoring the docs set to
avoid these becoming out of sync going forward
This pull request updates the project documentation to align with the
v1.0 Agent2Agent (A2A) Protocol Specification defined in
specification/a2a.proto. It ensures that all conceptual guides,
summaries, and tutorials reflect the current normative definitions,
RPC method names, and wire formats.
Summary of Changes
1. RPC Method Naming Updates
Standardized all method references to use the v1.0 PascalCase naming
convention:
* `message/send` → `SendMessage`
* `message/stream` → `SendStreamingMessage`
* `tasks/get` → `GetTask`
* `tasks/list` → `ListTasks`
* `tasks/cancel` → `CancelTask`
* `tasks/pushNotificationConfig/set` →
`CreateTaskPushNotificationConfig`
* `tasks/resubscribe` → `SubscribeToTask`
* `agent/getAuthenticatedExtendedCard` → `GetExtendedAgentCard`
2. JSON Example & Wire Format Corrections
Updated examples across all "Topic" files and the Python Quickstart to
match v1.0 breaking changes:
* Removed `kind` discriminators: Examples for Message, Task, Part, and
StreamResponse now use member-based polymorphism (e.g.,
{"text": "..."} instead of {"kind": "text", "text": "..."}).
* Enum Standardization: Changed role and state enums from
kebab-case/lowercase to SCREAMING_SNAKE_CASE with type prefixes (e.g.,
`"ROLE_USER"`, `"TASK_STATE_COMPLETED"`).
* Response Wrapping: Updated examples to reflect that `SendMessage` and
`SendStreamingMessage` return a unified response object where
the message or task is nested within the result.
3. LLM Context (`docs/llms.txt`)
* Completely refreshed the protocol summary and RPC method list to
ensure LLM-based tools (like Gemini CLI) have an accurate
representation of the v1.0 API surface and error codes.
4. Link & Anchor Maintenance
* Updated internal documentation links and spans to point to the correct
sections in the specification.md (e.g., correcting the
anchor for GetExtendedAgentCard).
Why this is needed
The v1.0 release introduced significant structural improvements for
ProtoJSON compliance and architectural consistency. Documentation
examples were previously showing v0.3.0 patterns which would cause
integration errors for developers using the latest SDKs.
This pull request updates the A2A protocol specification to clarify the
distinction between Messages and Artifacts, and makes a minor adjustment
to protocol negotiation requirements.
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Fixes inconsistent spelling of cancel-related terms across the
specification and documentation. The proto definition uses
TASK_STATE_CANCELLED (double 'l'), but various documentation files were
using single 'l' spelling.
Changes:
- cancelled → canceled
- cancellable → cancelable
- `TaskNotCancellableError` → `TaskNotCancelableError`
Files modified:
- docs/specification.md
- docs/llms.txt
- docs/topics/life-of-a-task.md
All documentation now consistently uses single 'l' to match the proto
definition and JSON naming conventions.
Fixes#1270
Release-As: 1.0.0
---------
Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Updates the specification to clarify that blocking SendMessage calls
must return when tasks reach interrupted states (input_required,
auth_required) in addition to terminal states. This prevents deadlock
scenarios where tasks waiting for user input would cause blocking calls
to hang indefinitely.
Changes:
- specification/grpc/a2a.proto: Updated blocking field comment to
include "terminal or interrupted state"
- specification/grpc/a2a.proto: Fixed AUTH_REQUIRED classification to be
an "interrupted state" (consistent with INPUT_REQUIRED)
- docs/specification.md: Updated blocking behavior description to
include interrupted states and changed "final task state" to "current
task state"
This enables proper client workflows where blocking calls can return on
INPUT_REQUIRED or AUTH_REQUIRED, allowing clients to provide the needed
information and resume with subsequent SendMessage calls.
Fixes#1264
---------
Co-authored-by: madankumarpichamuthu <madankumarpichamuthu@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
This change simplifies the Part message design by:
- Renaming oneof 'part' to 'content' for clarity
- Flattening FilePart fields (file_with_uri -> url, file_with_bytes ->
bytes) directly into Part
- Flattening DataPart by using google.protobuf.Value instead of Struct
- Moving media_type and filename to Part level (available for all
content types)
- Removing separate FilePart and DataPart messages
Also updated migration guidance documentation to reference ancillary
documents instead of requiring an in-spec appendix.
Related to issue #1255
Replaces PR #1363
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Updates specification to use ProtoJSON enum format
(SCREAMING_SNAKE_CASE) instead of kebab-case, aligning with ADR-001
decision.
Changes:
- Updated Section 5.5 enum value formatting rules
- Added reference to ADR-001 and ProtoJSON specification
- Updated all JSON examples to use SCREAMING_SNAKE_CASE enums:
- Role enums: user -> ROLE_USER, agent -> ROLE_AGENT
- Task state enums: working -> TASK_STATE_WORKING, completed ->
TASK_STATE_COMPLETED, etc.
This aligns the specification with the TSC-approved ADR-001 decision to
leverage ProtoJSON for JSON serialization.
Fixes#1344
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
Terminal states (COMPLETED, FAILED, CANCELLED, REJECTED) already
indicate task completion, making the final field redundant. This creates
consistency across streaming, polling, and push notification
communication patterns.
Changes:
- Removed final field (field 4) from TaskStatusUpdateEvent in proto
- Updated examples to remove final: true references
- Clarified that streams close upon terminal states
- Added migration guidance in Appendix A.2.2
Fixes#1232
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
# Description
Provides clarity on server generated task ids in the specification
documentation to address underspecification of Message payloads and
expected error handling.
Fixes: #1406
Co-authored-by: Darrel <darrmi@microsoft.com>
Bypassing tech-writing review as it is a simple rename and the majority of the changes are in the specification. Changes to conceptual docs are just for aligning names.
Restores the intentional rename from "Set" to "Create" for push
notification configuration methods that was lost during refactoring.
When the protocol was updated to support multiple Push Notification
Configurations, the method was changed from "Set" (which implies
replacing a single config) to "Create" (which implies creating a new
instance among many).
Changes across all documentation and proto files:
- specification/grpc/a2a.proto: Renamed RPC method and request message
- docs/specification.md: Updated all references, section titles, and
method tables
- docs/topics/streaming-and-async.md: Updated links and text
- docs/llms.txt: Updated method reference
Fixes#1394
---------
Co-authored-by: madankumarpichamuthu <madankumarpichamuthu@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Updates specification documentation to align with proto file changes by
removing /v1/ prefix from all HTTP REST endpoint URLs.
Changes:
- Updated all HTTP endpoint examples (POST, GET, DELETE)
- Updated API operation reference table
- Removed /v1/ from 41 occurrences throughout the specification
Fixes#1350
Update security scheme example to use the correct key for the security
schemes instead of the `type` field.
This fixes#1355
Signed-off-by: Jeff Mesnil <jmesnil@redhat.com>
Relocates `supports_extended_agent_card` from AgentCard to
AgentCapabilities for architectural consistency. All optional features
that enable specific operations now reside in the capabilities object.
Rationale:
- Consistent placement: streaming, push_notifications, and
state_transition_history are all in AgentCapabilities
- Improved discoverability: developers naturally check capabilities for
optional features
- Semantic correctness: extended agent card support is a capability
Changes:
- Proto: Removed field 13 from AgentCard, added field 5 to
AgentCapabilities
- Field renamed: supports_extended_agent_card → extended_agent_card
- Updated all references: AgentCard.supportsExtendedAgentCard →
AgentCard.capabilities.extendedAgentCard
- Updated JSON examples to reflect new structure
- Added migration guidance in Appendix A.2.2 of specification
Breaking change: Clients and agents must update capability checking
logic. See specification Appendix A.2.2 for migration steps.
Fixes#1229
---------
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
This PR combines two fixes for the ListTaskRequest last_updated_after
field one changes the field to a timestamp type and one renames it and
clarifies the ordering of the task list result.
Original PR for the timestamp type fix was:
https://github.com/a2aproject/A2A/pull/1288Fixes: #1287Fixes: #1206
---------
Co-authored-by: Yaroslav Shevchuk <yarolegovich@gmail.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Fixes#1258
### High level summary of changes:
- protocolVersion in AgentCard is now an array called protocolVersions
- Servers are expected to return UnsupportedVersionError if they get a
request with an A2A-Version header higher than they support.
- Clients are expected to fallback to a supported version if that is
acceptable to them. Tooling should help here.
- Not every minor version needs to be enumerated in the protocolVersions
array. 2.2 infers support for 2.1 and 2.0.
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Sam Betts <1769706+Tehsmash@users.noreply.github.com>
Minor patch to `security_scheme` reference to `securityScheme` and added
a missing anchor tag for `Security`. Another docs change should be added
to clarify usage of `Security`. Opened
https://github.com/a2aproject/A2A/discussions/1278 for clarification.
Fixes https://github.com/a2aproject/A2A/issues/1280
Co-authored-by: Luca Muscariello <muscariello@ieee.org>
Co-authored-by: Darrel <darrmi@microsoft.com>
As v1.0 is a major release and may contain breaking changes this commit
cleans up the deprecated fields in the a2a.proto and references to this
in the spec doc.
Closes: #1227
Fixes naming inconsistency between the agent card property and the
GetExtendedAgentCard method. The property name now matches the method
naming convention.
- Updated proto definition: supports_authenticated_extended_card →
supports_extended_agent_card
- Updated all documentation references across specification.md and
llms.txt
- Maintains semantic meaning while improving consistency
Fixes#1215
We should use the proto_to_table macro for describing inputs/outputs of
operations to avoid having to modify the specification manually after
protobuf definition changes.
Other changes:
- small updates to capitalization/markdown annotations to ensure
consistency with the rest of the specification
- modified proto_to_table to return `None` string if proto is empty
(e.g. `GetExtendedAgentRequest`). We should use macro for this request
even if it's empty, because we may add fields
(https://github.com/a2aproject/A2A/pull/1195).
Fixes https://github.com/a2aproject/A2A/issues/1243🦕
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Darrel Miller <darrel.miller@microsoft.com>
Fixing issue #1240 by providing something more in line with what is
expected.
Fixes https://github.com/a2aproject/A2A/issues/1240🦕
---------
Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
In the currently published specification the data model definitions
include a proto snippet and then have a list of fields under the
snippet. This creates duplicated information. To prevent this
duplication while maintaining an easy to read presentation of the
abstract data models, this PR uses a Python macro to convert the proto
into a markdown table.
Also took the opportunity to do an editorial pass on the comments in the
a2a.proto before the field descriptions were removed from the
specification.md. Some of this content came from the types.ts file that
often had information that was not in a2a.proto.
A preview of the changes can be seen here
https://purple-moss-0838db51e.3.azurestaticapps.net/specification/#41-core-objects
# Proto to Markdown Table Conversion
The macro system provides two main functions (`proto_to_table` and
`proto_enum_to_table`) that convert Protocol Buffer definitions into
formatted markdown tables:
1. **Locates Definitions**: Reads the `.proto` file and uses region
markers (`--8<-- [start:Name]` and `--8<-- [end:Name]`) to extract
specific message or enum definitions.
2. **Parses Structure**: Analyzes the proto content to separate three
sections:
- **Description**: Comments appearing before the message/enum
declaration
- **Fields/Values**: The actual field or enum value definitions with
their inline comments
- **Notes**: Comments appearing after the closing brace
3. **Extracts Field Details**: For each field, it captures:
- Field name (converted from snake_case to camelCase, or using
`json_name` annotation)
- Type (mapped to readable formats like "string", "array of integer",
"map of string")
- Required status (based on `REQUIRED` annotation or `optional` keyword)
- Description (from preceding comment lines)
4. **Generates Output**: Assembles the markdown output with:
- Description text at the top
- A formatted table with columns for Field/Type/Required/Description (or
Value/Description for enums)
- Special notes for `oneof` groups
- Additional notes from comments after the definition
The conversion automatically handles multi-line field definitions, map
types, repeated fields, and filters out protolint directives and region
markers from the output.
---------
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
# Description
Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:
- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- [x] Ensure the tests and linter pass (Run `nox -s format` from the
repository root to format)
- [x] Appropriate docs were updated (if necessary)
- [x] Fix existing linting errors (I guess they were already on the main
upstream)
Fixes#761🦕
---------
Signed-off-by: Eden Reich <eden.reich@gmail.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>
Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Darrel <darrmi@microsoft.com>
Co-authored-by: Amye Scavarda Perrin <amye@amye.org>
### Issues with this approach
- Style updates or link changes relating to other documentation pages
won't be propagated to the specification doc when other pages are
updated.
### Alternatives
- Maintain copies of the specification docs for each minor version
`0.X.0`
- Similar to MCP Docs
https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification
- This would also allow us to not use mike for versioning (would get rid
of `latest` in URLs and could simplify SEO)
Follow-up to #1077