Repository navigation
[Impl] commitment.flight_start / flight_end have no type or time zone #127
Description
What did you build?
An implementation that parses and validates OpenProposal proposals, line items and commitments end to end.
What you tried to express, and what happened
§ 5.6.1 requires flight_start and flight_end but gives no type, and every example uses a date-only value ("2026-10-06"). With no time-zone rule, the same flight can start up to a day apart depending on whose clock an implementation assumes. That matters at the boundary of a guaranteed flight and when comparing the flight with price_valid_until, which the examples give as full UTC timestamps.
What you did instead
Rejected date-only flights for execution and required full timestamps with an offset.
Suggested resolution: type the two keys as RFC 3339 date-times with an offset, or, if date-only is intended, name the time zone they're read in (for example the seller's or the property's).
Fields involved
commitment.flight_start, commitment.flight_end
How blocking was it?
Workaround required, but it works
Before you submit
- I have read CONTRIBUTING.md and agree my contribution may be published under this repository's licence.
- This contains no confidential or commercially sensitive information — no real rate cards, deal terms, client names or inventory data.
Activity
KonstantinMirin commentedon Oct 27, 2026
Thank you, @EvgenyAndroid. Postindustria (IAB Tech Lab member) supports your first option, written in UTC. @VJAlkimi's examples comment (#37) proposes the same rule: "RFC 3339 UTC at whole-second precision, no offsets, no date-only values". § 1.1 hands programmatic guaranteed and PMP line items to the Deals API. Its
terms.startdateandterms.enddateare a "UTC timestamp in seconds in ISO-8601", so a date-only flight has no instant to send. Suggested rows for § 5.6.1:The line item's
time_zone, from our daypart clock PR (#123), stays the clock fordaypartandfrequency_caponly. A buyer whose flight starts at local midnight converts it once, before committing. Our deal handoff change request maps both rows to the Deals API.Open questions
flight_endthe flight's last instant, as [Comment] § 6 — The examples omit listed keys, never exercise the pricing mechanism, and mix timestamp formats the spec does not define #37's2026-12-21T23:59:59Zand OpenDirect 2.1 read it, or the first instant after the flight? OpenDirect 2.1 reads a date-only end as 11:59:59 PM. The answer: the last second, inclusive, and later thanflight_start.Revised 2026-10-27: The
flight_endrow makes it the flight's last second, inclusive, and later thanflight_start, as @EvgenyAndroid proposed.Analyzed and generated with the help of Claude, fully reviewed by me.
EvgenyAndroid commentedon Oct 27, 2026
Thanks @KonstantinMirin. UTC-only works for me. The Deals API takes UTC seconds anyway, so allowing an offset would only move the conversion to the handoff. I'd take your two rows as written.
On the open question, I'd make
flight_endthe last second of the flight, inclusive. That's how OpenDirect 2.1 reads a date-only end (11:59:59 PM), it's what #37's2026-12-21T23:59:59Zalready shows, and at whole-second precision it leaves no gap. An exclusive end would make every handoff to OpenDirect subtract a second. The Deals API doesn't say which it means, so the #132 mapping should state its assumption. The cost is back-to-back flights: the next one starts one second afterflight_end, not at it. Either way, § 5.6.1 should say which it is, and thatflight_endMUST be later thanflight_start.