Guidance on x-ms-enum for extensibility

[JonKohler]

Hey Azure team!

As part of some API design activities at our company, we've been looking into ways to have extensible enums, instead of the traditional enum that openapi provides.

As such, earlier this year, I posted a feature request to openapi upstream, here: OAI/OpenAPI-Specification#1552

Specifically around upstream adopting some sort of extensible enum support. I came across x-ms-enum, and (gut feeling) it feels right. IMHO, I really like the what that Azure has approached this problem, as not only do you work around the static enum issues that have plagued coding styles forever, but you get the opportunity to add even more extensibility than just a simple growable list.

that said, OpenAPI has come back with the comment, here: OAI/OpenAPI-Specification#1552 (comment)

@JonKohler from the documentation you linked to (emphasis mine):

For this reason, enums are not automatically turned into strongly typed enum types - instead they are rendered in the documentation comments for the property or parameter to indicate allowed values. To indicate that an enum will rarely change and that C#/Java enum semantics are desired, use the x-ms-enum exension.

Which seems to be the opposite way around to the intent of this issue? It seems the problem here is lack of consistency and flexibility in two or more code-generation tools and (enum value descriptions notwithstanding) not an issue with the spec itself.

If I'm reading this documentation right, is Azure saying that x-ms-enum is not extensible, such that any additions to x-ms-enum would be a breaking change? Or are we saying that you CAN extend x-ms-enum and NOT have a breaking change?

I'm curious to get your teams sage guidance on this, and see if there is a way to potentially parlay all of these efforts together to come up with a single community standard, that then we could perhaps help the openapi upstream community adopt.

Lemme know!

jon@nutanix.com, github.com/nutanix

[fearthecowboy]

Whether an individual code-generator creates extensible enums is really dependent on the language and the intent that the generator is after.

OpenAPI isn't so much about "Code generation" as it is documenting a remote interface. Since it uses JSON Schema to describe things, it inherits it's strangeness--including using the word "enum" to represent possible values.

Generators will of course, look at enum and try to generate some sort of language-specific support for it that is appropriate.

x-ms-enum is an extension hint to the code generator to guide it towards a desired outcome.

In Azure, when we mark an enum with x-ms-enum and modelAsString:true we're telling the generator that the list of values can expand later, and it should generate something that won't break (and is tolerant of taking any value, regardless of it being in the set of known values). In strongly typed languages, we usually create a string with some constants (or some variation of that). With modelAsString:false, the code generator can use enum types instead (in c#) -- most of our generators actually use strings/constants all of the time.

The trouble with making a "standard" is that the hints to the code generator don't really belong in the OpenAPI document. Describing the API accurately does.

What it feels like you're really asking for is a standardized way of describing a property as "Here are the known values today, AND there might be others." ... which a code generator could use to make a good decision on how to represent the API in code.

In this case, OAI's desire to use JSON Schema is limiting, since JSON Schema doesn't have a way of describing that.

Not sure where that takes you ❓

[JonKohler]

Thanks @fearthecowboy !

Yes, what I'm really after is this:

What it feels like you're really asking for is a standardized way of describing a property as "Here are the known values today, AND there might be others." ... which a code generator could use to make a good decision on how to represent the API in code.

The challenge we have is that our product feature set is growing and growing a mile a minute, not unlike other companies I'm sure, and as we both add functionality as well as respond to customer requests for features/enhancements/fixes, its possible that the amount of enums/choices for a given REST api could expand (obviously changing the original values would be breaking).

A crude example would be something like "GET ServiceStatus", where the available services today are
foo
bar

an enhancement request comes along to add "puppy" service, so now the choices are
foo
bar
puppy

Ideally, I'd just like to tack on puppy to the list and be done with it.

[lmazuel]

x-ms-enum is extensible with modelAsString=True, I believe this problem is solved. Please let me know otherwise! Tagging this issue for closing.

[ghost]

Hi, we're sending this friendly reminder because we haven't heard back from you in 7 days. We need more information about this issue to help address it. Please be sure to give us your input. If we don't hear back from you within 14 days of this comment the issue will be automatically closed. Thank you!