From f5e7ba3a0e9cf08e2ac2c0684a043d3975baa2a3 Mon Sep 17 00:00:00 2001 From: Dan Hudlow Date: Fri, 9 May 2025 13:30:26 -0500 Subject: [PATCH 1/2] feat(140): make snake_case ubiquitous --- aep/general/0140/aep.md.j2 | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/aep/general/0140/aep.md.j2 b/aep/general/0140/aep.md.j2 index 2b1290c6..bce5a664 100644 --- a/aep/general/0140/aep.md.j2 +++ b/aep/general/0140/aep.md.j2 @@ -29,17 +29,31 @@ they are appropriately descriptive and of suitable length. ### Case -{% tab proto %} - -Field definitions in protobuf files **must** use `lower_snake_case` names. -These names are mapped to an appropriate naming convention in JSON and in -generated code. - -{% tab oas %} - -Field definitions in OAS schemas **must** use `camelCase` names. - -{% endtabs %} +JSON and protobuf fields **must** use `lower_snake_case` names. These names are +**may** be mapped to an idiomatic naming convention in generated code. + +Over-the-wire references to fields in other contexts (such as query parameters, +path segments, and embedded CEL expressions) **must** not be transformed in any +way. The only exception to this is the rare scenario where a field name is also +used as a header name, in which case it **must** be transformed by substituting +hyphens (`-`) for underscores (`_`), emitted in lowercase, and parsed +case-insensitively. + +**Note:** Regrettably, [ProtoJSON][proto-json] and [gRPC-Gateway][grpc-gateway] +both transform `lower_snake_case` protobuf field names into `lowerCamelCase` +JSON field names by default and an earlier draft of this AEP _required_ that +JSON field names be in `lowerCamelCase` (whether or not they are backed by +equivalent protobufs). + +**Important:** While APIs compliant with this AEP are required to use +`lower_snake_case` JSON field names, because of the history, tools for +producing or consuming AEP-compliant APIs **may** support `lowerCamelCase` JSON +fields in a non-default configuration and first-party tools (those included +in the AEP project) **must** do so until the end of official support for the +AEP 1.x standard. + +[proto-json]: https://protobuf.dev/programming-guides/json +[grpc-gateway]: https://grpc-ecosystem.github.io/grpc-gateway/ **Note:** Examples throughout this AEP use `snake_case`. This should not be taken to mean that this guidance is protobuf-specific. Any guidance not in a From 5c736784dbf877555f8d14f21c2913b5b530ad6f Mon Sep 17 00:00:00 2001 From: Dan Hudlow Date: Fri, 9 May 2025 17:16:50 -0500 Subject: [PATCH 2/2] Fixes from code review --- aep/general/0140/aep.md.j2 | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/aep/general/0140/aep.md.j2 b/aep/general/0140/aep.md.j2 index bce5a664..43785973 100644 --- a/aep/general/0140/aep.md.j2 +++ b/aep/general/0140/aep.md.j2 @@ -29,8 +29,9 @@ they are appropriately descriptive and of suitable length. ### Case -JSON and protobuf fields **must** use `lower_snake_case` names. These names are -**may** be mapped to an idiomatic naming convention in generated code. +JSON and protobuf fields **must** use `lower_snake_case` names. These names +**may** be mapped to a language-specific idiomatic naming convention in +generated code. Over-the-wire references to fields in other contexts (such as query parameters, path segments, and embedded CEL expressions) **must** not be transformed in any @@ -46,11 +47,11 @@ JSON field names be in `lowerCamelCase` (whether or not they are backed by equivalent protobufs). **Important:** While APIs compliant with this AEP are required to use -`lower_snake_case` JSON field names, because of the history, tools for +`lower_snake_case` JSON field names, because of this history, tools for producing or consuming AEP-compliant APIs **may** support `lowerCamelCase` JSON -fields in a non-default configuration and first-party tools (those included -in the AEP project) **must** do so until the end of official support for the -AEP 1.x standard. +fields in a non-default configuration and first-party tools (those included in +the AEP project) **must** do so until the end of official support for the AEP +1.x standard. [proto-json]: https://protobuf.dev/programming-guides/json [grpc-gateway]: https://grpc-ecosystem.github.io/grpc-gateway/