[Question/Clarification] Is enum with empty list of values considered to be valid OAS3 schema?

[lzemskov]

Newbie to this, so my apologies if this is not the right format/forum please advise what would be a better way to ask/clarify.

We are building an OAS representation for an existing 20 year old API which comes with some quirks and challenges. One of the challenges is around expressing Schemas with field data types which represented on the backend as Enums/Picklist data types. The challenge is multifold:

1. The set of available values is dynamic and could get very large (up to 3K items and growing).
2. There are multiple Schemas (3K and growing) which can have multiple fields of the types above.
   Combined this has a potential for blowing up the overall size of schema which we are hoping to avoid.

As one of the solutions we were considering mapping those types to an Enum with an empty set, and adding a description with a pointer to the doc/API which can be used to obtain the list of possible values. But currently looks like some of the existing validators flag this as an invalid OAS3 schema. I tried looking through the OAS3 spec documentation but it does not mention anywhere that enum must have at least one item, so was wondering if there is such limitation?

[karenetheridge]

No, the enum array may be empty:

The value of this keyword MUST be an array. This array SHOULD have at least one element. Elements in the array SHOULD be unique.

https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.2

[lzemskov]

Thanks for the pointer @karenetheridge , misread your original response, so updating the comment.
Based on your answer my assumption was correct and then it's the issue inside the corresponding validator which flags the schema as invalid.

[webron]

Looks like you might have hit an edge case with validation tools. OAS3 depends on "draft 6" which was intended to be re-release of "draft 4" as "draft 4" was expired at the time. It was our understanding that those two versions were pretty much the same. Looking at the enum definition though, it seems that's where there's a difference between the two versions, where "draft 4" required at least one element in the array.

Interesting enough, the migration guide between those two versions doesn't even mention the difference in the enum definition which is likely another source for confusion.

While less than ideal, given the amount of values you're referring to and the fact you mentioned the list is actually dynamic - you might want to consider this as an open value field instead of specifying it as an empty enum and then reference the list of possible values elsewhere.

[lzemskov]

Thanks a lot for the feedback @webron , i do feel that either representation 'is not quite right'.
If i am scanning through the spec definition and see the following 2 entries, each representing the Enum/Picklist type:

"Field1" : { "type" : "string" }, "Field2" : { "type" : "string", "enum" : [] }

It feels more clear that the second one is not an ordinary string type but rather something bounded by a set of values.

Granted that either representation would still need additional information to convey / point to a source which describes the list of available values.

Are there any drawbacks from using the empty enum[] for this usecase?

[webron]

Not entirely sure that's how json schema actually works, but the way I read an empty enum - no value is valid and validators would blow on any value to that field. You might think that doesn't make sense because why would anyone define something like that, but it's actually quite easy to write json schemas where nothing would validate against them (not a criticism just a mention of facts).

[lzemskov]

Thanks again for the feedback @webron , want to make sure i understand your point.

'the way I read an empty enum - no value is valid and validators would blow on any value to that field'

So you are saying if i used the generated schema (which has an 'enum []' definition) and used a valid json input which has any value in that field even when the value provided is from the specified/valid set which we point a consumer to be it via info inside the description field or some other means that Json would fail validations against the schema because the enum set is empty.

[webron]

Correct. That said, @karenetheridge is definitely more knowledgeable about JSON Schema than me, and she can give you a more accurate answer.

[lzemskov]

Sounds good, thanks again for clarifications and input which was very helpful @webron , @karenetheridge
Given that the original question here has been answered i will go ahead and close this 'Issue' unless you think i should keep it open for further discussions.