Open APIs

Dear Community,

various APIs use the type TimePeriod which consists of a left boundary startDateTime and a right boundary endDateTime.

GB922 does not specify whether the boundaries are included in or excluded from the time period.
In v25.0 (Excel) I don't find any definition of TimePeriod anymore.
R18.0 (Excel) defines TimePeriod as "A base / value business entity used to represent a period of time, between two timepoints". Formal interpretation of "between" would indicate the exclusion of the boundaries, an informal ("colloquial") interpretation would indicate their inclusion.

What is the intended semantics of TimePeriod: Which points in time t does a TimePeriod, with both boundaries startDateTime and endDateTime being specified, represent?

1. startDateTime ≤ t ≤ endDateTime, or
2. startDateTime ≤ t < endDateTime, or
3. startDateTime < t ≤ endDateTime, or
4. startDateTime < t < endDateTime?

If I just missed the proper definition in some other document, please point me to the according specification.

Thank you and best regards,
Roland

------------------------------
Roland Laznik
1&1 Versatel GmbH
------------------------------

TM Forum doesn't explicitly say. In the public SID/Base Types and Open API materials, TimePeriod is defined with startDateTime and endDateTime, but there's no normative statement about whether the end points are included or excluded. 

In practice we like to use start ≤ t ≤ end  .

------------------------------
Ameed Jamous
TelecomsXChange (TCXC)
------------------------------

Hi,

I always assumed what I have always seen in the past (crm, billing, campaign tools): start and end were always inclusive.

GB922 ("Common") does have 2 sections describing Allen's interval algebra to descrive temporal relations and RFC 2445 for iCalendar.

Figure BT.02 – I01 Point – Interval Relations
Figure BT.03 – I02 Interval – Interval Relations  👈 this!

the Algebra suggests that that the intervals are half-open [start, end) to avoid overlaps (they would share a boundary instant).

• startDateTime inclusive, endDateTime exclusive.

which is not what I have used so far.

say I have 2 promotions running on day 1 and day 2, promotions cannot be active at the same time (no overlap):

Promo 1	Promo 2
Start = 01/01/2000 00:00	Start = 02/01/2000 00:00
end = 01/01/2000 23:59	end = 02/01/2000 23:59

If a system doesn't support date-time but just date, it would be:

Promo 1	Promo 2
Start = 01/01/2000	Start = 02/01/2000
end = 01/01/2000	end = 02/01/2000

If we use half-open  intervals as GB922 suggests, my promo dates would look weird:

Promo 1	Promo 2
Start = 01/01/2000 (included)	Start = 02/01/2000 (included)
end = 02/01/2000 (excluded)	end = 03/01/2000 (excluded)

but my software don't leave me a choice, the end date is always included and I won't change TMF API to show a different end date than what I see in my CRM, BSS, Campaign tool.

TMF OAS files I use (mostly core commerce APIs) do not spell out boundary semantics either. Given the ambiguity, it looks like we should document a house rule.

Let's wait for an official statement from TM Forum

------------------------------
Kind regards,

Matthieu Hattab
Digital Sales Domain Architect
Lyse Tele AS
------------------------------

Thank you for your answers. Thus, we should go for inclusive boundaries.

I found following example in TMF678 in the meantime, supporting your view:

{
    ...
    "validFor": {
        "endDateTime": "2020-01-00T00:00:00.000Z",
        "startDateTime": "2020-12-31T23:59:59.999Z"
    },
    "@type":"BillCycle"
}

The validFor seem to represent the calendar year 2020, starting at 2020-01-00T00:00:00.000Z and ending at 2020-12-31T23:59:59.999Z. Thus, there is no stop time 2021-01-01T00:00:00Z.

Though tmforum does not prescribe a time granule (at least I didn't find any), the time granule is assumed to be 1 millisecond here.

Thank you all for your insights and best regards,
Roland

------------------------------
Roland Laznik
1&1 Versatel GmbH
------------------------------