idea: normalizing to snake_case across the board

[toumorokoshi]

Today, we have a few different cases, still in use in the aeps today:

• kebab-case, which is used for path elements, and also as examples for the resource singular in patterns (see https://aep.dev/4/#annotating-resource-types)
• snake_case, which is recommended as the value for variable names in both proto and json (see feat(140): make snake_case ubiquitous #309).

This bifurcation causes a few minor usability issues. They are not blocking, but nontheless introduce some usability friction, primarily in translation - client and uses must a few more string replacements, rather than copy-paste things like the resource singular directly.

This causes issues in:

• when you refer to a resource via a variable (e.g. book_store, you have to convert it to it's resource singular (book-store) if you want to look up it's type.

So - why do we have this split? is it valuable?

Previously, the snake case was decided upon due to the fact that:

• it was already used in protobuf.
• json had no strict requirements on variable naming.

There are also other advantages over kebab-case. For example, all languages generally support snake_case variables (even if they are not recommended).

Making the change

The actual approach to perform this normalization is actually fairly straightforward:

• modify path guidance to use snake_case.
• modify the x-aep-resource annotation examples and syntax to also use snake_case.

If desired, we could make this a should, with the caveat that existing APIs may not be able to break this precedent. But for new API I don't know if there's a good reason to not standardize.

Thoughts?

[thegagne]

If we have paths with underscores, they are no longer DNS safe, which is currently a should from AEP-122.

This really touches on the difficulty of casing, which I'm sure we all have suffered from.

Currently, my understanding is:

Resource Names: kebab-case e.g. `crypto-key`
Paths: kebab-case e.g. `/crypto-keys/abc-123`
Path Segment Parameter Names: snake_case e.g. `/crypto-keys/{crypto_key_id}`
Body Properties: snake_case e.g. `{ "crypto_key_algorithm": "RSA256" }`

But this does require a conversion when you want to cross reference a resource from another resource. Are there other scenarios causing pain here? It might be worth thinking through all the scenarios and seeing if we can address them.

We could do something with a standard field for linked_resources, like this:

{
...
  "linked_resources": [
      {
        "resource_type": "author-name",
        "resource_path": "author-names/yusuke-tsutsumi"
      },
      {
        "resource_type": "author-name",
        "resource_path": "author-names/david-gagne"
      },
      {
        "resource_type": "publisher-name",
        "resource_path": "publisher-names/abc"
      },
   ]
}   

This is kind of verbose, but demonstrates a way around the kebabs being properties and forces them into values. (kebab author-name resource type used for demonstration purposes).

[rofrankel]

Using snake_case rather than kebab-case in path elements would have generated extremely passionate negative feedback at Roblox.

We also made multi-word API names (i.e. subdomains) kebab-case as well because it looked weird to have snake_case in a URL (the Google AIPs didn't specify this at all IIRC).

Does anyone use snake_case in URLs? I don't think we should make URLs jarringly ugly for the sake of consistency with unrelated things like field names.

[toumorokoshi]

I think convention (no one uses snake case in paths) is a good argument. I'd argue not as strong as a technical argument, but a valid one.

for the sake of consistency with unrelated things like field names.

I'd say that field names are related, in the sense that we request the usage of the resource singular to refer to a resource. e.g, the right field name for a book-edition would be book_edition. It's not a a huge leap to make this transformation, but it is a modification that has to be made.

[rambleraptor]

I think @thegagne's DNS point should make the decision. We cannot have must AEPs conflict with should AEPs.

That being said, JSON body properties should continue to be snake_case. It's enough of a convention that libraries like Pydantic rely on snake_case.

[toumorokoshi]

Thanks for all the engagement!

If we have paths with underscores, they are no longer DNS safe, which is currently a should from AEP-122.

I don't know if we completely understand the motivation for AEP-122's requirement for dns-compatible resource ids. I'm not saying that's a reason to ignore the guidance, but I think it's worth scrutinizing the original motivation.

I'd like to point out that URIs do not ban the use of an underscore: https://datatracker.ietf.org/doc/html/rfc3986#section-2.3.

[thegagne]

Good to know. I was curious if there was strong motivation for the DNS safe requirements or the other requirements. The RFCs listed on 122 may be somewhat confusing to reference as a "reason" if we don't spell it out a bit more.

FWIW, in the past I made a decision to use the character set ^[a-z0-9._-]+$ - but that was for files/urls stored in S3 and downloaded, and it served me well.

I really think this particular conversation revolves around the four use cases I listed above, and what is appropriate for each.

It's maybe a style thing, but I don't prefer the resource names with underscores, or underscores in the path.

`/book-authors/david-gagne` -> I like this
`/book_authors/david_gagne` -> I don't like this as much

Though I don't mind if the path parameters are underscore because they are just placeholders

/book-authors/{book_author} -> I don't mind this
/book-authors/{book-author} -> a variable with a hyphen in it seems weird to me, and may cause problems somewhere?

For field names, I do think we should stick with snake_case.

Here's a table with what I'm suggesting, which is pretty much what we have now, it's just not clearly stated.

Use Case	Recommended Casing	Reason / Notes	Example
URL Path Elements	kebab-case	DNS-safe, widely used in URLs, better readability	/crypto-keys/abc-123
Resource Names	kebab-case	Consistent with path elements, easy human recognition	author-name
Path Segment Parameters	snake_case	Matches variable naming conventions, clearer in code	/crypto-keys/{crypto_key_id}
JSON Body Properties	snake_case	Standard for JSON/protobuf, supported by most libs	{ "crypto_key_algorithm": "RSA256" }
Linked Resource References	kebab-case (resource-type), but cannot use as a "key" only as a "value"	Keep resource_type kebab-case for URLs; parameters snake_case	{ "resource_type": "author-name", "resource_path": "author-names/jane-doe" }
Resource IDs	kebab-case	used in URL path, needs to work with UUIDs. These could be loosened to also allow underscores? How prescriptive can we be for Ids? Also consider Ids might be integers?	abc-123

[toumorokoshi]

Thanks for enumerating those! I think that's probably where we'll end up.

There's one more piece to the puzzle too - the patterns field in the x-aep-resource annotation: https://aep.dev/4/#annotating-resource-types.

I think this will also end up similar to path / path segment parameters:

/crypto-keys/{crypto_key_id}.

@rofrankel I know you have concerns about underscores in the path segments - but any concerns with naming the variables in the pattern / path with underscores?

[thegagne]

Another to consider, the OperationIds/RPC names.

https://aep.dev/130/#operationids-and-rpc-names

These are PascalCase. For OAS, the norm I believe is camelCase, but we are suggesting PascalCase. Should we change that?

[toumorokoshi]

For OAS, the norm I believe is camelCase,

Do you have some examples? We landed on PascalCase for those to match proto / grpc - there wasn't much of a reason not to at the time, and spot-checking in a few clients, we found that in tools like openapi-generator they resolved to the same value. So it didn't seem worth bifurcating between proto / oas. Somewhat similar to the rationale for snake_case for property names.

[thegagne]

https://spec.openapis.org/oas/latest.html#operation-object

operationId | string | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.

The spec itself does not enforce a casing convention, only speaks to it being case sensitive.

The examples on the site are camelCase, for example: https://learn.openapis.org/examples/v3.0/api-with-examples.html

The examples on the swagger site also use camelCase. https://swagger.io/docs/specification/v2_0/paths-and-operations/?sbsearch=operationIds

Here's some others I went and looked at:

• Cloudflare: kebab-case
• Stripe: PascalCase
• Github: kebab with slashes
• OpenAI: camelCase
• Azure: Pascal with underscores

FWIW in TypeSpec, it's a little goofy. You can let TypeSpec derive it from the namespace + operation, but this results in some ugly operationIds with a mix of Pascal and camel, separated by underscore. https://typespec.io/docs/getting-started/getting-started-rest/02-operations-responses/#example-operation-id-in-openapi-spec. They do allow you to specify the operationId and use whatever you want, which is what I prefer to do for a cleaner operationId.

This one seems to be a bit all over the place. My current opinion is that we should either be prescriptive with camelCase to closely follow the examples from OAS, or alternatively use PascalCase, or leave it open ended but suggest that each org adopt their own convention for it based on their needs. From the little research I did, a couple of them had some sense of organization with the concept of namespace + operationId.

Because these operationIds will likely get used in downstream automation, the naming convention probably does matter to some degree, but I don't have the foresight to pick a winner here.

[rambleraptor]

I might've lost the thread somewhere.

OAS OperationIDs aren't really in our jurisdiction, right? We'll make sure that our tooling generates them properly, but ultimately, we won't include anything about them in the spec.

[thegagne]

https://aep.dev/130/#operationids-and-rpc-names

It currently is in the spec. Whether it should be or not? Not sure.

[toumorokoshi]

We do document our expectations around operationIds, as not specifying the operationId might lead to inconsistent client (SDK) generation.

w.r.t. to adopting camelCase on operation IDs - I think we'd have to justify the value of deviating from consistent operation names across grpc and openapi in the spec. I'm not strongly opinionated, but I think we should have a reason stronger than a convention.

[toumorokoshi]

We had a discussion in one of the weekly meetings, and have landed on the following deltas from existing guidance:

• switching patterns to use the underscore case (e.g. /books/{book_id}/book-editions/{book_edition_id}
• switching openapi paths to also use _id values: /books/{book_id}/book-editions/{book_edition_id}
  This enables consistency in the usage of the term "resource id", as well as referring to variables via the snake_case standard.

[toumorokoshi]

PR in question: #321