Defining Constants for Schemas / Open Enum

[Danielku15]

Hey everyone 👋

I was wondering if anyone ever faced a similar challenge like I am currently, and was able to solve it in a good way also supported by the tooling.

Assume an API which accepts web hooks. You have one endpoint with a schema where one property defines the type of event that happened. This event is a string.

components:
  schemas:
    WebHook:
      type: object
      properties:
          eventId:
            type: string

Now here comes the tricky aspects: not all eventId values are treated the same way. The API understands some special values, while others might be accepted but not treated in any special way. I want to be able to document in a good way some known values for this property like an enum, but not limit the property to this values. In best case these defined values, are also generated then as constants by the code generator so that the client implementing the API might have these special values available instead of duplicating it manually:

components:
  schemas:
    WebHook:
      type: object
      properties:
          eventId:
            type: string
            knownValues: # like an enum definition (would then also support description once this is extended by OAS)
              - Special.Event01
              - Special.Event02
              - Group02.Event01

An output could look like this:

class WebHook
{
    public class KnownValues
    {
        public const string SpecialEvent01 = "Special.Event01";
        public const string SpecialEvent02 = "Special.Event01";
        public const string Group02Event01 = "Group02Event01";
    }
}

I thought of using examples for this case but would also need to extend the code generators for this purpose and it is not really a standard practice.

Different explanation:

Has anybody ever tried to represent "open enums" in Open API Specification? I want to define properties which have predefined enum values, but are not limited to these. Some example use cases:

• An enum listing known webhook event ids which actually trigger a special logic within the API. Once enum values support descriptions this would even make more sense.
• Like in the documentation the colors: you might list some predefined ones, but you might not prevent the client to provide other values like #FF0000

Code generators would behave like:

• The property of the schema would have the plain underlying data type like string or enum.
• The enum would be generated as some type defining the constants so the generated client/server can use them.

[hkosova]

#1552 has some suggestions for extensible enums

[Danielku15]

Thanks for sharing the link on this discussion. It gives some interesting approaches on how to tackle this issue. Unfortunately there does not seem to be a light at the end of the tunnel to officially support this. 😭

[handrews]

As noted, this is being tracked with more info at #1552, so I'm going to close this discussion.