Clarify meaning of `minDuration` and `maxDuration` for a QoS profile used for QoS Provisioning

[eric-murray]

Problem description
The QoS Provisioning API allows QoS profiles defined by the qos-profiles API to be applied "indefinitely", and yet these profiles may have a minDuration and/or maxDuration parameter defined.

It is not clearly defined if these parameters have any meaning for a QoS profile being applied to QoS Provisioning. In particular, the definition of maxDuration is:

The maximum time period that this profile can be deployed.

This might reasonably be interpreted by an API consumer to mean that the QoS assignment will be automatically deleted after this time without them needing to explicitly delete it.

Expected action
Decide on intended behaviour and document.

Options include:

• QoS profiles with minDuration and/or maxDuration parameters defined CANNOT be used for QoS Provisioning
• The minDuration and maxDuration parameters, if defined, do NOT apply to QoS Provisioning
• The minDuration and maxDuration parameters, if defined, DO apply to QoS Provisioning as follows:
  • If minDuration is defined, the QoS assignment cannot be deleted before this time has elapsed
  • If maxDuration is defined, the QoS assignment will be automatically deleted after this time has elapsed

Additional context
None

[jlurien]

To support the first option above, I think we need to add also an error equivalent to the one existing in QoD for cases when the QoS Profile is not applicable to the service: 422 QOS_PROVISIONING.QOS_PROFILE_NOT_APPLICABLE. This error can apply to any other incompatibilities. I will propose a PR for this, independently of the outcome of the discussion.

Probably the simplest choice is the first option, but I have asked our Product team internally

[hdamker]

First option seems the natural one as long as we don't define it differently (as discussed in our call on Friday, July 25th)

• QoS profiles with minDuration and/or maxDuration parameters defined CANNOT be used for QoS Provisioning (and will be responded with 422 as proposed Add error 422 QOS_PROVISIONING.QOS_PROFILE_NOT_APPLICABLE #476)

[eric-murray]

• QoS profiles with minDuration and/or maxDuration parameters defined CANNOT be used for QoS Provisioning (and will be responded with 422 as proposed Add error 422 QOS_PROVISIONING.QOS_PROFILE_NOT_APPLICABLE #476)

This proposal fits best with my understanding of the scope of the QoS Provisioning API, and avoids the risk that the API consumer misinterprets the minDuration or maxDuration parameters in a profile use for QoS Provisioning. A clarification in the QoS Provisioning documentation would be sufficient for the Fall'25 meta-release.

There are a number of issues we should think about during the next meta-release cycle:

• Discovery
  If some QoS profiles are not applicable to an API that accepts QoS profiles in their configuration, how does the API consumer learn this?
• QoS Profile Bloat
  If we need small variations in QoS profiles for the different APIs that use them (e.g. a profile with minDuration and/or maxDuration for QoD, and without for QoS Provisioning, but otherwise the same) we could end up with several similar profiles that might confuse the API consumer. This is related to QoS profile discovery.
• Bill-Shock Avoidance
  For QoS Provisioning, the expectation is that the API consumer will delete the assignment when no longer required. But they might forget, or might have issues with their credentials to be allowed to delete. When time-based billing is applied (e.g. per day), this could lead to unwanted charges, and contractual disputes.
  This could be handled at the product level separately from the API definition itself, but one option would be to allow QoS assignments to be time limited if that fitted the product definition (e.g. maxDuration does apply), perhaps with a mechanism to push that deletion time back if the API consumer actively confirms they want to keep the QoS assignment active.

Within Vodafone, we continue to analyse how the QualityOnDemand APIs can be used for a product, and I will raise issues related to the above points when our analysis is clearer.

[eric-murray]

@jlurien
Before creating any PR for this issue, can we agree on treatment of minDuration by the QoS Provisioning API?

Options are:

• QoS profiles with minDuration defined are rejected with an error
• QoS profiles with minDuration defined are accepted but with a warning (in the documentation) that any deletion may not come into effect until the minimum profile duration has expired

[jlurien]

@eric-murray for simplicity I prefer the first option. Applying the second option would create additional hassle (a DELETE may not have the expected effect). I expect that QoS profiles intended for QoS Provisioning will not have minDuration but we need to refine the logic to solve the "Discovery" concern above. Currently we don't have a way to discover QoS Profiles suitable for certain service. We may need to introduce new properties and filters, e.g. "applicableTo": [qos-provisioning, qos-booking, qualilty-on-demand], maybe also a negative one "notApplicableTo"

[eric-murray]

OK, thanks

So, for Fall25, I'd propose a simple addition to the "QoS profiles and QoS profile labels" part of the QoS Provisioning API documentation:

Note that QoS profiles for which the minDuration and/or maxDuration parameters are defined are not applicable to this API.

We can look at specifying applicability directly in the QoS profile itself for a later release.

[jlurien]

Reviewing the description of minDuration in QoS Profiles:

        minDuration:
          description: |
            The shortest time period that this profile can be deployed.

What is the expected behaviour for Quality on demand, when a session is created with a duration > minDuration but the session is requested to be deleted prior to minDuration? Because this case would require a similar treatment to what @eric-murray proposed as

QoS profiles with minDuration defined are accepted but with a warning (in the documentation) that any deletion may not come into effect until the minimum profile duration has expired

[hdamker]

One of the motivations to introduce minDuration was the inability to create a session only for very few seconds - so essentially deleting the session automatically before it is setup completely (current minimum in the API is 1 second, which is technically unrealistic). But Eric is right, it might be used also to determine the minimum chargeable unit.

But if we consider minimum duration only as the minimum for deletion via expiry of duration, but not for manual deletion by the API Consumer? There are still some questions (can a session be deleted during within the "requested" state?), but for me that would be natural. In worst case the API Consumer has to pay for the rest of the minimum duration.

[jlurien]

Indeed these considerations regarding minDuration apply almost the same to QoS Provisioning. In practice there will be always some implementation or charging limits, but I assume that not every QoS Profile will indicate explicitly this limit.

So now I doubt about my previous responses and I'm not sure if in some cases APIs with minDuration, or even maxDuration, may be applicable to QoS Provisioning, with some consideration, that may even change between implementation. As Qos Profiles are defined by implementations, it may happen that an operator that supports automatic deletion for QoS Provisioning defines a maxDuration for this purpose, while another one that doesn't implement this mechanism will define all QoS Profiles applicable for QoS Provisioning without maxDuration, and reject any attempt to use a QoS Profile with maxDuration for QoS Provisioning with the new error 422 QOS_PROVISIONING.QOS_PROFILE_NOT_APPLICABLE.

[hdamker]

No changes to M3 release-candidate in M4 based on the current status of discussion. Discussion to be continued towards Spring26 based on experiences with implementation of qos-provisioning and qos-booking. minDuration semantic also relevant for quality-on-demand.

[RandyLevensalor]

Need further discussion in the Sprint26 release. Possibly just better documentation.