Not clear how to describe a “flag” parameter in OpenAPI

[Rinzwind]

More of a question that an issue report: having gone through the OpenAPI specification, and issue #1573, it's not clear to me how to describe what in issue #1573 is termed a “flag” parameter.

The API I want to describe has some query parameters that can be either present or not present. They do not, and cannot, take a value (also excluding the empty value). So for example, /mailboxes/inbox/emails and /mailboxes/inbox/emails?starred might be valid URLs, but neither /mailboxes/inbox/emails?starred=xyz nor /mailboxes/inbox/emails?starred= would be valid URLs.

I'm not sure how best to describe a parameter like “starred” in OpenAPI. Should I simply use “allowEmptyValue”, even though its use is, as per issue #1573, not recommended? It also doesn't quite seem to imply “takes no value”.

Am I overlooking something and is there another way to handle this in OpenAPI? Or should I resort to relying on a specification extension of our own?

[hkosova]

Related: Support for arbitrary query strings

[Rinzwind]

The example I gave above doesn't illustrate well that the query string of the URLs does follow “form encoded” syntax for parameters that take a value. To extend the example: /mailboxes/inbox/emails?starred&[email protected]&read&year=2018 might be a valid URL. Again, /mailboxes/inbox/emails?read=&year=2018 would not be valid as read is a flag and should not be followed by =. The case in issue #1502 seems more complicated as the query string there does not follow “form encoded” syntax at all, so I'm not sure whether the ideas discussed there are the way to go in my case.

[Rinzwind]

For now, I've resorted to using a specification extension and added support for it to swagger-ui (Yesplan/swagger-ui@21e3e9d). Here's an attempt to describe it as an extension of the OpenAPI specification for parameter objects:

Field Name	Type	Description
x-isFlag	boolean	Default value is false. The value true is only valid if in is query, required is false, allowEmptyValue is true, and schema is omitted. The parameter can optionally be appended to the URL, but should not be followed by a value assignment.

Or at least the above is how I initially thought about it, but I now realize it might make more sense to say that required should be true, schema should be {"type":"boolean"} and allowEmptyValue should be false; and to treat a flag using a specialized serialization rule where its boolean value determines whether the parameter gets appended to the URL or not (instead of being included as flag=false or flag=true). I’m not really sure at this point whether the OpenAPI specification allows for an extension defined in this way though.

[MikeRalphson]

A specification extension means whatever you want it to mean, and there's no reason why that should not include enforcing values for other properties.

[Rinzwind]

Sure, but with an eye on remaining compatible with the non-extended specification, my original proposal (using required: false) probably did make more sense than the alternative I wrote up afterwards (using required: true).

[MikeRalphson]

I see. Just another note, on parameters either schema or content is required, but schema can be {}.

[MidnightLightning]

I just ran into this issue as well, a few years later. I'd love to see as part of the specification, either a { "type": "flag" } (which behaves like "boolean" in that it can be "on" or "off", but the off-state is "not present in the query string", and the on-state is "present in the query string with no value set".

Or switch allowEmptyValue being a boolean to be emptyValue as an enum of "never" (default), "optional" (current behavior of allowEmptyValue; an empty value is "allowed" but not forced), or "always" (the only valid setting for this parameter is to be empty or not included in the query string at all).

[handrews]

This is effectively a duplicate of #1502 (Support for arbitrary query strings) because "flag" parameters of this sort are not part of the application/x-www-form-urlencoded format. Including them effectively defines a different format, for which you need #1502.

I've linked this issue to that one and noted the use case, so I'm going to close this so we track the problem in only one place.