Skip to content

Commit e6c5699

Browse files
darrelmillergemini-code-assist[bot]muscariello
authored
docs: Added adr template and protojson adr (#1214)
Added ADR that captures decision to use ProtoJSON as the normative reference for JSON serialization --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: Luca Muscariello <muscariello@ieee.org>
1 parent a4afeea commit e6c5699

3 files changed

Lines changed: 190 additions & 0 deletions

File tree

‎.github/actions/spelling/allow.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ ACard
66
AClient
77
ACo
88
ADK
9+
ADR
910
AError
1011
AExecutor
1112
AGP
@@ -128,6 +129,8 @@ aboutasha
128129
achat
129130
aconnect
130131
adk
132+
adr
133+
adrs
131134
afet
132135
affef
133136
agentcard
@@ -284,6 +287,7 @@ postgresql
284287
pqr
285288
prefecthq
286289
protoc
290+
protojson
287291
protolint
288292
pyguide
289293
pylance

‎adrs/adr-001-protojson-serialization.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# ADR-001: Leverage ProtoJSON Specification for JSON Serialization
2+
3+
**Status:** Accepted
4+
5+
**Date:** 2025-11-18
6+
7+
**Decision Makers:** Technical Steering Committee (TSC)
8+
9+
**Technical Story:** JSON serialization approach for A2A specification
10+
11+
## Context
12+
13+
The A2A specification defines message structures using Protocol Buffers (proto definitions) but also needs to support JSON serialization for HTTP/REST-based communication and JSONRPC payloads. We needed to establish a normative approach for how JSON payloads should be serialized based on the proto definitions referenced by the specification.
14+
15+
Without a clearly specified approach to JSON serialization from proto definitions, implementers could create incompatible JSON representations, leading to interoperability issues across different A2A implementations.
16+
17+
## Decision Drivers
18+
19+
* Need for a standardized, well-documented approach to JSON serialization
20+
* Ability to leverage existing Protocol Buffer tooling
21+
* Clear specification for handling edge cases and type mappings
22+
* Idiomatic use of JSON conventions
23+
* Coupling of specification to tool chain
24+
25+
## Considered Options
26+
27+
* ProtoJSON (canonical JSON encoding for Protocol Buffers)
28+
* Explicit transformation rules defined in the A2A specification
29+
30+
## Decision Outcome
31+
32+
**Chosen option:** "ProtoJSON specification"
33+
34+
The TSC has decided to leverage the ProtoJSON specification as the normative approach to serializing JSON based on the proto definition referenced by the specification. This provides a well-defined, standardized way to convert Protocol Buffer messages to JSON format.
35+
36+
This decision was made with some reservation due to the dependency on ProtoJSON mechanisms and potential impact on protocol bindings unrelated to protobuf and gRPC. However, the decision is reversible if we identify significant issues during implementation, at which point we can duplicate the ProtoJSON conventions in the A2A specification where applicable and describe differences as needed.
37+
38+
### Consequences
39+
40+
#### Positive
41+
42+
* Standardized approach with clear documentation and specification
43+
* Wide ecosystem support with mature libraries across multiple languages
44+
* Consistent behavior across different implementations
45+
* Reduced ambiguity in JSON representation
46+
* Built-in handling for proto3 types and conventions
47+
* Provides well-defined rules for wire-unsafe changes
48+
* Removes the need to define data type handling rules for dates and numbers in the A2A specification
49+
50+
#### Negative
51+
52+
* **Breaking change**: This decision will result in breaking changes to existing JSON payloads, specifically relating to the casing of enum values (ProtoJSON uses SCREAMING_SNAKE_CASE for enums)
53+
* **Loss of roundtrip capability**: We will not be able to roundtrip unknown values because ProtoJSON doesn't support preserving unknown fields in the JSON representation
54+
* Migration effort required for existing implementations
55+
* **Ugly enums** Developers are not used to seeing enum values in SCREAMING_SNAKE_CASE in JSON, which may lead to confusion or errors during implementation
56+
* Changes to the ProtoJSON specification for the benefit of gRPC could have an impact on other protocol bindings.
57+
* Enums require a "unspecified" value even when they are only used for required fields to meet Proto best practices.
58+
* Certain field names need to have less than optimal names to avoid conflicts with proto keywords. e.g. message.
59+
60+
#### Neutral
61+
62+
* Implementations must follow ProtoJSON specification strictly
63+
* Documentation must clearly communicate the breaking changes
64+
65+
## References
66+
67+
* [ProtoJSON format](https://protobuf.dev/programming-guides/json/)
68+
69+
## Notes
70+
71+
This decision was made to ensure long-term interoperability and maintainability of the A2A specification. While it introduces breaking changes in the short term, the benefits of standardization and ecosystem alignment outweigh the migration costs.
72+
73+
Implementers should be aware that the enum casing change is the most visible breaking change and should plan accordingly for version transitions.

‎adrs/adr-template.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# ADR-[number]: [Title]
2+
3+
**Status:** [Proposed | Accepted | Deprecated | Superseded]
4+
5+
**Date:** YYYY-MM-DD
6+
7+
**Decision Makers:** [List of people involved in the decision]
8+
9+
**Technical Story:** [Optional: Link to related issue/story]
10+
11+
## Context
12+
13+
[Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change?]
14+
15+
## Decision Drivers
16+
17+
* [Driver 1: e.g., performance requirements]
18+
* [Driver 2: e.g., maintainability concerns]
19+
* [Driver 3: e.g., team expertise]
20+
* [Driver 4: e.g., cost considerations]
21+
22+
## Considered Options
23+
24+
* [Option 1]
25+
* [Option 2]
26+
* [Option 3]
27+
28+
## Decision Outcome
29+
30+
**Chosen option:** "[Option X]"
31+
32+
[Describe why this option was selected. What are the expected positive outcomes?]
33+
34+
### Consequences
35+
36+
#### Positive
37+
38+
* [Positive consequence 1]
39+
* [Positive consequence 2]
40+
41+
#### Negative
42+
43+
* [Negative consequence 1]
44+
* [Negative consequence 2]
45+
46+
#### Neutral
47+
48+
* [Neutral consequence 1]
49+
50+
## [Optional] Pros and Cons of the Options
51+
52+
### [Option 1]
53+
54+
[Brief description of option 1]
55+
56+
**Pros:**
57+
58+
* [Advantage 1]
59+
* [Advantage 2]
60+
61+
**Cons:**
62+
63+
* [Disadvantage 1]
64+
* [Disadvantage 2]
65+
66+
### [Option 2]
67+
68+
[Brief description of option 2]
69+
70+
**Pros:**
71+
72+
* [Advantage 1]
73+
* [Advantage 2]
74+
* [Advantage 2]
75+
76+
**Cons:**
77+
78+
* [Disadvantage 1]
79+
* [Disadvantage 2]
80+
81+
### [Option 3]
82+
83+
[Brief description of option 3]
84+
85+
**Pros:**
86+
87+
* [Advantage 1]
88+
* [Advantage 2]
89+
* [Advantage 2]
90+
91+
**Cons:**
92+
93+
* [Disadvantage 1]
94+
* [Disadvantage 2]
95+
96+
## Implementation
97+
98+
[Optional: Describe the implementation plan, timeline, and any specific technical details]
99+
100+
## Related Decisions
101+
102+
* [Link to related ADR 1]
103+
* [Link to related ADR 2]
104+
105+
## References
106+
107+
* [Link to resource 1]
108+
* [Link to resource 2]
109+
* [Link to resource 3]
110+
111+
## Notes
112+
113+
[Any additional notes, follow-up items, or context that doesn't fit elsewhere]

0 commit comments

Comments
 (0)