Use CAMARA Common schema "Date" in network-traffic-analysis.yaml #90

@tanjadegroot The PR(#91) cannot be merged because my local repository failed to sync with the latest Commonalities release (r4.3), so the Date schema definition is missing in my local CAMARA_common.yaml and the validator cannot resolve the reference.

@tanjadegroot Hello, could you please advise on how this synchronization issue should be resolved? This problem has been pending for some time now.

@tanjadegroot @cnzj-Gc

The reason for the error is that there is no CAMARA common schema "Date" within r4.3 of Commonalities, it was only added after r4.3 and will come with r4.4 and can be used when the API updates to r4.4. I recommend to do that in a second release candidate together with the other improvements.

@tanjadegroot @hdamker We investigated this issue and attempted to update the accessDate field to reference ../common/CAMARA_common.yaml#/components/schemas/Date. However, during implementation we discovered that the Date schema is not available in Commonalities r4.3 — it was only added in r4.4 (see camaraproject/Commonalities#645). Therefore, we have decided to close this issue as superseded by #92, where we revert the accessDate field to an inline type: string definition without format: date. We will revisit the shared Date schema reference once Commonalities r4.4 becomes available.

The interim accessDate definition that landed with PR #91 isn't acceptable as-is. It's now:

accessDate:
  type: string
  minLength: 10
  maxLength: 19
  description: |
    The calendar date of the record. Format depends on the requested frequency:
    - For frequency=DAY: YYYY-MM-DD (e.g., "2024-06-07")
    - For frequency=HOUR: YYYY-MM-DD HH:00:00 (e.g., "2024-06-07 14:00:00")

Two problems:

• For frequency=HOUR, the value ("2024-06-07 14:00:00") isn't RFC 3339 — space separator instead of T, and no time zone.
• The format now depends on the frequency parameter, with no format/pattern to constrain either variant.

Before picking a fix, what's the actual purpose of accessDate given each record already carries startDate/endDate? If it's meant to represent the calendar day (or hour) the record buckets to, using DateTime ($ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime", the same schema already used for startDate/endDate) would fix this now rather than waiting for the Date schema in Commonalities r4.4 — it's RFC 3339 / timezone-compliant for both the DAY and HOUR cases, with the meaning of the time-of-day part documented (e.g. always 00:00:00Z for DAY, the hour bucket's start for HOUR).

@hdamker #104
We changed accessDate to reference the CAMARA common DateTime schema instead of the local type: string + format: date definition.

Rationale: accessDate represents the statistical point of each record, whose granularity follows the frequency parameter:

• frequency=DAY: 00:00:00Z of the day
• frequency=HOUR: HH:00:00Z of the hour

The previous local definition could only express YYYY-MM-DD, so it could not represent the hour-level statistical point required by frequency=HOUR, and it was not fully RFC 3339 compliant.

DateTime covers both granularities, is timezone-compliant, and reuses the same schema already used by startDate/endDate.

Note: we deliberately did not use the Date schema here (as originally suggested in this issue) because Date only expresses YYYY-MM-DD and cannot represent the hour-level statistical point. DateTime is the correct fit for the semantics of this field.

x-camara-commonalities has been updated to 0.8.0.