Skip to content

feat(140): make snake_case ubiquitous #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

feat(140): make snake_case ubiquitous #297

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f5e7ba3
feat(140): make snake_case ubiquitous
hudlow May 9, 2025
5c73678
Fixes from code review
hudlow May 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 24 additions & 9 deletions aep/general/0140/aep.md.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,32 @@ 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
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.

{% tab oas %}

Field definitions in OAS schemas **must** use `camelCase` names.

{% endtabs %}
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]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need "Regrettably"? Feels a bit editorial for the otherwise dry tone of the AEPs.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm certainly not married to it, but I generally prefer to keep things a bit human? Happy to defer to consensus.

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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a super nit, but these Note and Important blocks are related to each other -- but we aren't really representing that in the Markdown. I doubt we can nest an Important inside a Note, but maybe we just make this all one Important block? WDYT?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently aside blocks don't seem to support more than one paragraph and it seemed unruly as a single paragraph so I did my best.

`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.

[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
Expand Down