Open APIs

Hello,

Can anyone comment on how the TimePeriod (the validFor) field is intended to be used in the TMF646 Appointment API?

The OpenAPI swagger says a TimePeriod is "A period of time, either as a deadline (endDateTime only) a startDateTime only, or both"
But is then contradicted by this line: "Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end"
And both of these seem to be contradicted by the conformance profile that marks both startDateTime and endDateTime as mandatory.

The specification has one example like this:
"validFor": { "startDateTime": "2018-02-01T14:40:43.000Z", "endDateTime": "" }
Which maybe implies that the startDateTime and endDateTime fields are mandatory, but they can be empty strings?

regards, Alasdair

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Hi Alasdair

TimePeriod is a common data type used in many Open APIs.
In my opinion, a period can be open-ended in either direction, so that start or end (but not both) can be empty.
I have opened a project JIRA to ask for the description to be fixed accordingly.

An individual API may see fit to restrict this and require one or both fields to be mandatory, in which case the API documentation should explain such in its schema where the time period used, and the conformance profile should reflect that. For Appointment, I refer you to @Gregoire Laurent who leads this API​ and perhaps he can clarify for you.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------

Original Message:
Sent: Mar 17, 2020 12:49
From: Alasdair MacLeod
Subject: Contradictory statements about TimePeriod in TMF646 Appointment API

Hello,

Can anyone comment on how the TimePeriod (the validFor) field is intended to be used in the TMF646 Appointment API?

The OpenAPI swagger says a TimePeriod is "A period of time, either as a deadline (endDateTime only) a startDateTime only, or both"
But is then contradicted by this line: "Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end"
And both of these seem to be contradicted by the conformance profile that marks both startDateTime and endDateTime as mandatory.

The specification has one example like this:
"validFor": { "startDateTime": "2018-02-01T14:40:43.000Z", "endDateTime": "" }
Which maybe implies that the startDateTime and endDateTime fields are mandatory, but they can be empty strings?

regards, Alasdair

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Thanks Jonathon,

I will follow up with Gregoire.

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Original Message:
Sent: Mar 18, 2020 03:08
From: Jonathan Goldberg
Subject: Contradictory statements about TimePeriod in TMF646 Appointment API

Hi Alasdair

TimePeriod is a common data type used in many Open APIs.
In my opinion, a period can be open-ended in either direction, so that start or end (but not both) can be empty.
I have opened a project JIRA to ask for the description to be fixed accordingly.

An individual API may see fit to restrict this and require one or both fields to be mandatory, in which case the API documentation should explain such in its schema where the time period used, and the conformance profile should reflect that. For Appointment, I refer you to @Gregoire Laurent who leads this API​ and perhaps he can clarify for you.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Mar 17, 2020 12:49
From: Alasdair MacLeod
Subject: Contradictory statements about TimePeriod in TMF646 Appointment API

Hello,

Can anyone comment on how the TimePeriod (the validFor) field is intended to be used in the TMF646 Appointment API?

The OpenAPI swagger says a TimePeriod is "A period of time, either as a deadline (endDateTime only) a startDateTime only, or both"
But is then contradicted by this line: "Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end"
And both of these seem to be contradicted by the conformance profile that marks both startDateTime and endDateTime as mandatory.

The specification has one example like this:
"validFor": { "startDateTime": "2018-02-01T14:40:43.000Z", "endDateTime": "" }
Which maybe implies that the startDateTime and endDateTime fields are mandatory, but they can be empty strings?

regards, Alasdair

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Hello Alasdair, 

thank you for your remarks. You noticed 2 different points in your message :
- The inconsistency concerning the startDateTime's description. This point has already been taken into account for the next version, in order to allow  timePeriod to have only a startDateTime or an endDateTime, or both. 
- The conformance profile should also be modified. Indeed, with the above statement, it appears that both startDateTime and endDateTime are optional (but at least one of them is requested). I will create a JIRA to take this remark into account for the next version.

In the end, the rule is that for Appointment resource, you must have at least one of startDateTime and/or endDateTime present in the validFor structure.

Best regards,

------------------------------
Gregoire Laurent
Orange
My answer are my own & don't represent necessarily my company or the TMF.
------------------------------

Original Message:
Sent: Mar 17, 2020 12:49
From: Alasdair MacLeod
Subject: Contradictory statements about TimePeriod in TMF646 Appointment API

Hello,

Can anyone comment on how the TimePeriod (the validFor) field is intended to be used in the TMF646 Appointment API?

The OpenAPI swagger says a TimePeriod is "A period of time, either as a deadline (endDateTime only) a startDateTime only, or both"
But is then contradicted by this line: "Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end"
And both of these seem to be contradicted by the conformance profile that marks both startDateTime and endDateTime as mandatory.

The specification has one example like this:
"validFor": { "startDateTime": "2018-02-01T14:40:43.000Z", "endDateTime": "" }
Which maybe implies that the startDateTime and endDateTime fields are mandatory, but they can be empty strings?

regards, Alasdair

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Thanks Gregoire

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------

Original Message:
Sent: Mar 18, 2020 10:24
From: Gregoire Laurent
Subject: Contradictory statements about TimePeriod in TMF646 Appointment API

Hello Alasdair,

thank you for your remarks. You noticed 2 different points in your message :
- The inconsistency concerning the startDateTime's description. This point has already been taken into account for the next version, in order to allow  timePeriod to have only a startDateTime or an endDateTime, or both.
- The conformance profile should also be modified. Indeed, with the above statement, it appears that both startDateTime and endDateTime are optional (but at least one of them is requested). I will create a JIRA to take this remark into account for the next version.

In the end, the rule is that for Appointment resource, you must have at least one of startDateTime and/or endDateTime present in the validFor structure.

Best regards,

------------------------------
Gregoire Laurent
Orange
My answer are my own & don't represent necessarily my company or the TMF.

Original Message:
Sent: Mar 17, 2020 12:49
From: Alasdair MacLeod
Subject: Contradictory statements about TimePeriod in TMF646 Appointment API

Hello,

Can anyone comment on how the TimePeriod (the validFor) field is intended to be used in the TMF646 Appointment API?

The OpenAPI swagger says a TimePeriod is "A period of time, either as a deadline (endDateTime only) a startDateTime only, or both"
But is then contradicted by this line: "Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end"
And both of these seem to be contradicted by the conformance profile that marks both startDateTime and endDateTime as mandatory.

The specification has one example like this:
"validFor": { "startDateTime": "2018-02-01T14:40:43.000Z", "endDateTime": "" }
Which maybe implies that the startDateTime and endDateTime fields are mandatory, but they can be empty strings?

regards, Alasdair

------------------------------
Alasdair MacLeod
BT Group plc
------------------------------