Skip to content

String format/pattern recommendation#330

Merged
rartych merged 2 commits intocamaraproject:mainfrom
rartych:string_format
Dec 20, 2024
Merged

String format/pattern recommendation#330
rartych merged 2 commits intocamaraproject:mainfrom
rartych:string_format

Conversation

@rartych
Copy link
Contributor

@rartych rartych commented Nov 6, 2024

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

Co-authored-by: Eric Murray <eric.murray@vodafone.com>
@PedroDiez
Copy link
Contributor

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

@rartych
Copy link
Contributor Author

rartych commented Nov 12, 2024

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).

@rartych rartych added documentation Improvements or additions to documentation Spring25 labels Nov 18, 2024
Copy link
Contributor

@patrice-conil patrice-conil left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@jlurien
Copy link
Contributor

jlurien commented Nov 26, 2024

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
Copy link
Contributor

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)

- Data type (String, Integer, Object…).
- If the format of a string is date-time 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 data type is string it is recommended to use appropriate modifier property `format` and/or `pattern` whenever possible. The [OpenAPI Initiative Formats Registry](https://spec.openapis.org/registry/format/) contains the list of formats used in OpenAPI specifications.
- 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)`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)`

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- Data type (String, Integer, Object…).
- If the format of a string is date-time 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 data type is string it is recommended to use appropriate modifier property `format` and/or `pattern` whenever possible. The [OpenAPI Initiative Formats Registry](https://spec.openapis.org/registry/format/) contains the list of formats used in OpenAPI specifications.
- 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)`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@PedroDiez PedroDiez left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation Spring25

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Specify string format whenever possible

5 participants