Skip to content

Commit fb52306

Browse files
authored
fix(127): recommend using json_name annotation for consistency with AEP-140 (#331)
Previous versions of aip.dev discouraged the usage of `json_name`: with the change to it's usage to preserve snake_case, this is now encouraged. Fixes #330
1 parent 01c82ef commit fb52306

File tree

1 file changed

+7
-4
lines changed

1 file changed

+7
-4
lines changed

aep/general/0127/aep.md.j2

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# HTTP and gRPC Transcoding
22

3-
APIs that follow [resource-oriented design][resources] are defined using
3+
APIs that follow [resource-oriented design][aep-121] are defined using
44
[RPCs][rpc], but the resource-oriented design framework allows them to also be
55
presented as APIs that largely follow REST/JSON conventions. This is important
66
in order to help developers use their existing knowledge: over 80% of the
@@ -84,8 +84,10 @@ message CreateBookRequest {
8484
- The `body` **must not** contain a nested field (or use the `.` character),
8585
- The `body` **must not** be the same as a URI parameter.
8686
- The `body` **must not** be a `repeated` field.
87-
- Fields **should not** use the `json_name` annotation to alter the field
88-
name in JSON, unless doing so for backwards-compatibility reasons.
87+
- In accordance with the [field name casing guidelines][field case], fields
88+
**should** use the `json_name` annotation to specify the snake_case form
89+
when the default JSON conversion would differ, unless this would break
90+
backwards compatibility.
8991

9092
**Note:** Bi-directional streaming RPCs should not include a `google.api.http`
9193
annotation at all. If feasible, the service **should** provide non-streaming
@@ -121,7 +123,8 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
121123

122124
<!-- prettier-ignore-start -->
123125
[json encoding]: https://developers.google.com/protocol-buffers/docs/proto3#json
124-
[resources]: ./0121.md
126+
[aep-121]: ./0121.md
127+
[field case]: ./0140.md#case
125128
[rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call
126129
[google.api.http]: https://buf.build/googleapis/googleapis/docs/main:google.api#google.api.Http
127130
<!-- prettier-ignore-end -->

0 commit comments

Comments
 (0)