String format/pattern recommendation

[rartych]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

Using string format or pattern modifiers simplify implementation and clarify parameter usage.
Recommendation added to section 11.5 Data Definitions.

Which issue(s) this PR fixes:

Fixes #93

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

Changelog input

String format/pattern recommendation added

Additional documentation

https://spec.openapis.org/oas/v3.0.3.html#data-types

[PedroDiez]

@rartych could it be also considered #137 into this PR? Think it makes sense

[rartych]

On general level it is covered as duration is listed in the registry:
https://spec.openapis.org/registry/format/duration.html

The open question is whether it should be mandated to use strings for duration or leave the decision to subprojects (to use integers or object types).

[patrice-conil]

LGTM

[jlurien]

On general level it is covered as duration is listed in the registry: https://spec.openapis.org/registry/format/duration.html

The open question is whether it should be mandated to use strings for duration or leave the decision to subprojects (to use integers or object types).

I agree with @rartych that we still have an open question regarding whether we require duration to be always expressed and formatted as "format: duration", or whether we just allow subprojects to adopt this format, and in this case we recommend to add explicitly the format: duration, but we do not mandate this format to be adopted in all properties dealing with duration.

My feeling is that we still don't have enough consensus in issue #137 to require all APIs to adopt RFC 3339 format for next meta, as that measure would impact many APIs, breaking backward compatibility.

[PedroDiez]

After review I agree with that.
We need to reach consensus on that.

From some documentation found in "open internet" ISO 8601 indicates for duration. So as initially using RFC3339 as a reference would fit in our purposes but let's see within Issue #137

In both basic and extended format the complete representation of the expression for duration shall be [PnnW] or [PnnYnnMnnDTnnHnnMnnS].
...

When	an	application	identifies	the	need	for	a	complete	representation	of	a	time	interval	through	its	duration	and	context	information,	with	duration	in	the	format	with	designators,	it	shall	use	an	expression	in	accordance	with	4.4.2	using	a	complete	duration	representation	as	defined	in	4.4.3.2.	
      Basic	and	extended	format:	PnnYnnMnnDTnnHnnMnnS	
                                                        PnnW	
      Example	1:	P2Y10M15DT10H30M20S
      Example	2:	P6W

RFC 3339

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)

[eric-murray]

I know this is inherited from the current text, but ISO 8601 defines date format as YYYY-MM-DD. RFC 3339 expresses formats in ABNF, so does not define an equivalent formatting string, but YYYY-MM-DD is not wrong for RFC 3339.

Suggested change

	- If the format of a string is `date-time`, the following sentence must be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)`
	- If the format of a string is `date-time`, the following sentence must be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is YYYY-MM-DD'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)`

[rartych]

yyyy-MM-dd'T'HH:mm:ss.SSSZ template is typical for java, so it is somehow developer friendly.
As the change would require updating OAS using date-time I would prefer to keep it as it is.

[eric-murray]

OK. I didn't realise this was a Java notation. As far as I can tell, whether the letter placeholder is upper or lower case makes no difference to the allowed values. Adding a reference to the Java definition at some point in the future might help interpret this string.

As format: date is used by some APIs, I will add a line for that as well.

[eric-murray]

Suggested change

	- If the format of a string is `date-time`, the following sentence must be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)`
	- If the format of a string is `date-time`, the following sentence MUST be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)`
	- If the format of a string is `date`, a statement MUST be included in the description that the date be specified using the RFC 3339 / ISO 8601 compliant format YYYY-MM-DD

[PedroDiez]

LGTM