Proposal to add a standard for defining durations for API Design guidelines

[mhfoo]

Problem description Proposal to add a standard for defining durations for CAMARA APIs.

Possible evolution

Use ISO 8601 Durations as the definition for duration. Under API Design Guidelines: 11.5 Data Definitions, add a bullet point to define duration, with reference to ISO 8601 Durations, with the following type and format.

• type: string
• format: duration

If the format of a string is duration, the following sentence must be present in the description: 'It must follow ISO 8601 Durations'

Alternative solution N.A

Additional context Have a common definition for duration when designing CAMARA APIs. Example: Searching or querying records for the previous stated time duration:

• 7 days: P7D
• 14 hours: PT14H
• 2 minutes: PT2M

PS. Referring to wikipedia

[mhfoo]

@jpengar FYI above

[rartych]

The duration format proposed by OpenAPI Initiative refers to - RFC3339,

Durations:
   dur-second        = 1*DIGIT "S"
   dur-minute        = 1*DIGIT "M" [dur-second]
   dur-hour          = 1*DIGIT "H" [dur-minute]
   dur-time          = "T" (dur-hour / dur-minute / dur-second)
   dur-day           = 1*DIGIT "D"
   dur-week          = 1*DIGIT "W"
   dur-month         = 1*DIGIT "M" [dur-day]
   dur-year          = 1*DIGIT "Y" [dur-month]
   dur-date          = (dur-day / dur-month / dur-year) [dur-time]
   duration          = "P" (dur-date / dur-time / dur-week)

It is more related to OAS 3.1 as indicated here: https://github.com/camaraproject/Commonalities/issues/93#issuecomment-1841531161

[mhfoo]

@rartych

Thanks for pointing it out in your comment: Formats Registry.

What is your recommendation for duration format to refer to?

• RFC3339, Appendix A ISO 8601 Collected ABNF, Durations
• OpenAPI Initiative Registry, Formats Registry, Duration

[hdamker]

Without presenting an own opinion I would like to mention two use cases of "duration" which we are currently using in QualityOnDemand (and the sub project is aware that this need to consolidated, see https://github.com/camaraproject/QualityOnDemand/issues/249):

• Parameter duration in QoSSessions, defined as an integer.

  • Maybe easier to handle as the duration format proposed above at least with the current expectations that such sessions shouldn't exceed 24 hours (86400 seconds).
  • The timestamps for startedAt and expiresAtwithin SessionInfo are also given as integer, "in seconds since Unix epoch", a common format used by developers
  • My understanding is that 86400 seconds could be expressed in the proposed duration format above as "P1D" (but could be 24, 23 or 25 hours, if there is change of daylight saving time within the day), "PT24H", "PT86400S", ... not sure if that is really developer friendly.

• Schema 'Duration', defined as object with value and unit (enum with "Days" down to "Nanoseconds") within QoSProfiles

  • The rational here was that the same schema is also used within parameters like 'jitter' and 'packetDelayBudget' which both require sub second values
  • Most probably we will need to use two different schemata going forward: Aligning the schema for minDuration and maxDuration with duration of a session and define a new one for jitter and packetDelayBudget (I don't think that "PT0.005S" is a developer friendly option to express 20 msec).

[hdamker]

The duration format proposed by OpenAPI Initiative refers to - RFC3339,

It is maybe worth to note that RFC3339 explicitly does not cover time periods but only timestamps:

Description of time periods, or intervals, is not covered here.

The grammar given in Annex A is informal. In addition is the duration format on its own ambiguous regarding the total number of days in a calendar year and calendar month if not used within a "period" (with defined start or end timestamp).

A way forward could be to use duration format with the restrictions defined within the Java Class Duration, but without the minus signs:

Obtains a Duration from a text string such as PnDTnHnMn.nS.

This will parse a textual representation of a duration, including the string produced by toString(). The formats accepted are based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours.

The string starts with an optional sign, denoted by the ASCII negative or positive symbol. If negative, the whole period is negated. The ASCII letter "P" is next in upper or lower case. There are then four sections, each consisting of a number and a suffix. The sections have suffixes in ASCII of "D", "H", "M" and "S" for days, hours, minutes and seconds, accepted in upper or lower case. The suffixes must occur in order. The ASCII letter "T" must occur before the first occurrence, if any, of an hour, minute or second section. At least one of the four sections must be present, and if "T" is present there must be at least one section after the "T". The number part of each section must consist of one or more ASCII digits. The number may be prefixed by the ASCII negative or positive symbol. The number of days, hours and minutes must parse to an long. The number of seconds must parse to an long with optional fraction. The decimal point may be either a dot or a comma. The fractional part may have from zero to 9 digits.

The leading plus/minus sign, and negative values for other units are not part of the ISO-8601 standard.

[mhfoo]

Discussion #144

[rartych]

@Kevsy Definitions of duration similar to QoD QoSProfiles are also present in Connectivity Insights subproject. Is string duration format suitable for this use case?