D-040 How is a length of time written where the specification or its examples write it as prose, a word, or a count of seconds?

What we propose

An ISO 8601 duration in the grammar of RFC 3339 Appendix A, as hold_duration is.

As written

A production option's lead_time is prose, such as "10 business days"; a report's cadence, an availability's granularity, and a measurement source's attribution_window are bare words, such as daily and 30d; and placement.skipafter and refresh.min_interval_s are whole seconds, as § 5.2.2 and AdCOM 1.0 write them. hold_duration, which the text writes as an ISO 8601 duration, stays one.

The as-written variant takes the option as-written. Switch the type map to As written to see it.

Options

• duration Chosen

  An ISO 8601 duration in the grammar of RFC 3339 Appendix A, as hold_duration is.

• as-written As written

  Each as the specification or its examples write it, prose for lead_time, a word for cadence and granularity, 30d for attribution_window, and integer seconds for skipafter and min_interval_s.

Why

Each of these is a length of time: a production lead time, a reporting option's cadence, the granularity of an availability figure, a measurement's attribution window, how long an ad plays before it may be skipped, and the shortest interval between refreshes. The specification already writes hold_duration as an ISO 8601 duration, so one concept takes one form, and a receiver reads every length of time with one parser. For most of them the text names no form, and the examples write prose, a word, or 30d: "10 business days" and 0 for a lead time, daily for a cadence, and 30d for an attribution window. A frequency cap's period isn't one: it is a calendar period, a term (D-044). For skipafter and min_interval_s the text does name one: § 5.2.2 says its keys follow AdCOM 1.0 and that each takes an integer, and it counts both in seconds, as AdCOM 1.0 and OpenRTB 2.6 write skipafter and minint; no example writes either. The schema departs from both: each is a duration, which a seller converts to whole seconds when it builds a bid request.

What we ask the specification to change

Write every length of time as an ISO 8601 duration, as hold_duration is. That covers a production option's lead_time, a reporting option's cadence, availability's granularity, and a measurement source's attribution_window. It also covers placement.skipafter and refresh.min_interval_s. The examples write "10 business days" and 0 for a lead time. They write daily for a cadence and 30d for an attribution window, which are P1D and P30D as durations. § 5.2.2 writes skipafter and min_interval_s as integer seconds, because AdCOM 1.0 and OpenRTB 2.6 write skipafter and minint that way. A seller that builds a bid request converts each duration to whole seconds, such as PT5S to 5. The _s in min_interval_s names the unit, which a duration carries, so rename the key min_interval. Business days need a calendar the specification doesn't define, so a lead time in business days needs one too.

The specification lines it rests on

Each line is quoted as the record pins it. Expand an item to read the quote.

main

• § 5.4, the production row's description: the inline object L249 at 44dfaaf

  { custom_unit, build_owner, lead_time, cost }

• § 5.6, the availability row's description: the inline object L275 at 44dfaaf

  { unit, basis, as_of, granularity, type: forecast | reservable, quantity }

• § 5.7, the measurement_source row's description: the inline object L321 at 44dfaaf

  { vendor, attribution_window, qualifier }

• § 5.7, the reporting row's description: the inline object L323 at 44dfaaf

  { feed_type: log_level | aggregate | none, cadence, delivery_mechanism, metrics_provided[], latency }

With the open PRs

• § 5.4, the production row's description: the inline object L242 on main at 981a74e

  { custom_unit, build_owner, lead_time, cost }

• § 5.2.2, the placement.skipafter key row L249 in #120

  skipafter | OPTIONAL | When skip is 1: seconds the ad plays before the placement enables skipping | VideoPlacement.skipafter, AudioPlacement.skipafter, video.skipafter

• § 5.2.2, the placement.refresh key row's meaning: the inline object L252 in #120

  { min_interval_s }

• § 5.6, the availability row's description: the inline object L268 on main at 981a74e

  { unit, basis, as_of, granularity, type: forecast | reservable, quantity }

• § 5.7, the measurement_source row's description: the inline object L314 on main at 981a74e

  { vendor, attribution_window, qualifier }

• § 5.7, the reporting row's description: the inline object L316 on main at 981a74e

  { feed_type: log_level | aggregate | none, cadence, delivery_mechanism, metrics_provided[], latency }

• § 5.2.2, a sentence L233 in #120

  Keys follow AdCOM 1.0 Placement and its DisplayPlacement, VideoPlacement and AudioPlacement subtypes, and the matching OpenRTB 2.6 Imp attributes.

• § 5.2.2, a requirement L242 in #120

  Each key takes an integer, except playmethod[] and api[], which take arrays of integers, and refresh, an object whose min_interval_s is a REQUIRED integer.

• § 5.2.2, the placement.refresh key row L252 in #120

  refresh | OPTIONAL | { min_interval_s }: minimum seconds a creative renders before the slot refreshes | OpenRTB 2.6 only: imp.refresh.refsettings[].minint

Examples that follow the text, not this change

What it shapes

main: Availability, MeasurementSourceOption, ProductionOption, ReportingOption, Availability.as_of, Availability.basis, Availability.granularity, Availability.quantity, Availability.type, Availability.unit, MeasurementSourceOption.attribution_window, MeasurementSourceOption.qualifier, MeasurementSourceOption.vendor, ProductionOption.build_owner, ProductionOption.cost, ProductionOption.custom_unit, ProductionOption.lead_time, ReportingOption.cadence, ReportingOption.delivery_mechanism, ReportingOption.feed_type, ReportingOption.latency, ReportingOption.metrics_provided

With the open PRs: Availability, MeasurementSourceOption, ProductionOption, Refresh, ReportingOption, Availability.as_of, Availability.basis, Availability.granularity, Availability.quantity, Availability.type, Availability.unit, MeasurementSourceOption.attribution_window, MeasurementSourceOption.qualifier, MeasurementSourceOption.vendor, Placement.refresh, Placement.skipafter, ProductionOption.build_owner, ProductionOption.cost, ProductionOption.custom_unit, ProductionOption.lead_time, Refresh.min_interval_s, ReportingOption.cadence, ReportingOption.delivery_mechanism, ReportingOption.feed_type, ReportingOption.latency, ReportingOption.metrics_provided