Enums "enabled" by a boolean VS enums with a "disabled" value entry

[pjhac]

Dear Commonalities group,

(disclaimer: the below represent my personal views, not that from my company).

I am wondering if there is, in CAMARA, a consensus about using enums covered by a boolean VS enums with an additional "disabled" value. Let me explain, and apologies if that was discussed in the past and I missed it (and if so, please ignore this post, and if you have a reference to any existing source having discussed this, it would be appreciated, at least for my own knowledge).

Let's take the following example: we have an attribute that is an enum with values A, B, C and D. However, we only consider those values as being valid if another boolean attribute is set to true. In cases where the latter is false, the enum values have no meaning, whatever their value. The expected requirement for this is to put the boolean attribute to mandatory and the enum attribute to optional since it may not be defined in the case where the boolean is set to false.

I found at least one case following a recent discussion in ICM about ConsentInfo. Here is the code for reference: https://github.com/camaraproject/ConsentInfo/blob/main/code/API_definitions/consent-info.yaml#L314 to 331. (Please note I'm only discussing the need for boolean with respect to the present discussion, not any issue bound to that specific repo.)

I totally understand the intent, but from an implementation standpoint, this brings some challenges:

• input validation needs to check the boolean flag to know if the enum field has to be validated in turn or not, putting a requirement on field order evaluation.
• if the boolean flag is false, and the enum is not provided at all (it's not mandatory), what value should be considered? Or shoud the call be rejected with a 400?
• mapping the input to an object (for example in Java) will be tricky, as code implementations in general are not fond of optional fields (and for the evaluation order indicated in the first item).
• an enum is, in general, represented by a scalar value; if the enum is absent and this is acceptable from the code standpoint, only languages supporting a "null" value for enums as objects will work, and this then requires null checking.

In order to simplify this, an additional "disabled" enum value can be added to the list of valid enum values. This brings the following advantages:

• the enum field becomes mandatory, and "disabled" value acts like the false value of the boolean flag.
• input validation becomes simpler
• crafting the payload is more straightforward, as the intent is put in a single attribute, not two.
  In the ConsentInfo example above, the "consentStatus" enum would have the following values: NOT_REQUIRED, PENDING, ACTIVE, REVOKED, EXPIRED.

I am not saying that this is what should / must be done, I'm rather wondering what you are thinking about it, if this makes sense, and if it would be worth considering. Whatever the set of values used for the enum is, it shouldn't be a breaking change if implemented properly, with the exception that the enum field becomes mandatory (removing the boolean one won't break things, it will simply be ignored if provided); that said, since most implementations see fields as "present" or "not present", this shouldn't be big issue (the enum field still has to be listed in your object class anyway).

Please note that if the enum values are strictly mapped to a fixed dictionary (DPV, for example), then the proposal will not be applicable unless the DPV itself provides a "disabled" or "ignore" value.

Posted in Commonalities as it is something that may go into the Guidelines.

Please let me know what you think. Thank you in advance.

Best regards,
Pierre

[eric-murray]

Hi @pjhac

The fundamental issue is the lack of "conditionally required" syntax in OAS. Discriminators and anyOf can do some of the work, and are used by APIs in CAMARA, but these are not rendered properly by the Swagger editor, and are anyway not a complete solution.

Conditional requirements can be indicated within the OAS using a proprietary syntax without upsetting either the Swagger or ReDoc viewers. For example:

    PrivacyStatusObject:
      type: object
      required:
        - scopes
        - purpose
        - consentRequired
        - consentStatus
          - consentRequired[true]

However, this is not guaranteed to be true in future as the viewers are updated, and no tools would recognise this syntax (and may even be upset by it). But my preference would still be proper conditionally required support in OAS using a syntax such as the above.

[pjhac]

Hi @eric-murray

Thank you for your comment.

I understand the lack of conditionally required syntax and how things were done to mitigate it, and I'm not saying anything against that. What I am trying to understand is the reason behind the use of a conditionally required field when this conditional field is an enum that could be augmented with a NOT_REQUIRED value (if we reuse the example of ConsentInfo), hence making the boolean flag redundant. In short, why using two fields when there are, in my opinion, valid alternatives that only need a single one. To me, the latter approach is less error prone, and makes the intent clear since the information is only conveyed in a single element.

As I indicated, programmatically-speaking conditionally-required fields might bring some challenges. Furthermore, even without the possibility of adding a new value to the enum, the sole absence of the field might be enough to understand that it is not required or doesn't apply (and translate to null, which is perfectly valid in most languages). If I had to make an analogy, I would use the last element of a pointer-based linked list: no one is going to define a boolean flag in each element saying that this element is the last or not; instead, one would set the "next" pointer to null in the last element, which conveys the same information.

To be clear, I'm simply trying to understand the "why", independently of what OAS permits or not. That also helps developers understanding the context when implementing such constructs in objects, especially if there was no choice alternative.

Best regards,
Pierre

[eric-murray]

I think this is just a design pattern adopted by some APIs, I guess because it better follows the API consumer's own logic:

• is consent required?
• if so, what is the consent status?

You can try and change this on a case by case basis, but my concern would be to think about evolution without requiring breaking changes. For example, what if, at some future point, additional status information is made available when consent is not required?

[pjhac]

Thank you @eric-murray, you answered my question.

I agree, there are potential implications if we want to grow the scope of information.

Thanks again for your feedback.

Best regards,
Pierre

[jpengar]

@pjhac I agree with @eric-murray . Also, for the Consent Info API in particular, you can find a similar argument in camaraproject/ConsentInfo#22 (comment).

[pjhac]

Thank you @jpengar for your reply and the pointer.

Thanks again @eric-murray for your replies.

I'm closing this discussion as I got the answers I needed.

Best regards,
Pierre