[KonstantinMirin]

What this changes

Draft 1 names no key the buyer writes to, and no formula for agreed_rate. This PR states both.

• § 3.1: selected[] is the complete set of options in effect. Object options have an id, and options combine freely. A Delta table holds delta_cpm, delta_fraction, and delta_flat.
• § 3.2: a settable field is a Settable or a SettableRange. The buyer writes value beside an explicit default, with no bare-value fallback.
• § 3.3 adds an availability read that changes no state. § 3.4 names BuyerWrites and LineItemWrites.
• § 5.6: agreed_rate has one formula, on the committed entry, rounded once. list_rate and commitment_bounds are requestable, and a granted rate is the next version's list_rate. min_rate is a hint that grants nothing.
• § 5.5: geo holds GeoCode entries, and markets is the form priced by market. device holds AdCOM 1.0 device types, and daypart holds ClockWindow entries.
• § 5.9: transaction_mechanism declares max_select: 1.

Related issue

Refs #22 and #30 by @VJAlkimi, and #58 by @dtbarne.

Refs #14, #16, #111, #133.

Builds on

This PR builds on our lifecycle PR, which builds on our parties PR, our errors and extensions PR, and our shared types PR. It carries #72 and #18 by @Sirajmx, at their heads. The #18 merge resolves to the min_rate row. Our daypart clock PR (#123) folds into this one. Review the last commit and the #18 merge; the earlier ones belong to the PRs it carries.

Type

• Editorial — no normative effect
• Normative — changes what the spec requires
• Breaking — would break an implementation already built to this draft
• Examples / schema / docs only

Checklist

• The body section is updated — § 1.1, § 2.1, § 2.2, § 2.6, § 3, § 3.1 to § 3.4, § 4.1, § 4.1.1, § 4.1.3, § 4.3.1, § 4.3.2, § 5.1.1, § 5.2, § 5.2.1, § 5.4, § 5.5, § 5.6, § 5.6.1, § 5.6.3, § 5.7, § 5.9, § 6
• Appendix A (field index) matches the body — markets and time_zone added, list_rate and min_rate renamed, and geo, device, and daypart retyped. list_rate, commitment_bounds, and commitment are re-marked, and agreed_rate is REQUIRED on the committed entry. scripts/check_appendix.py passes
• Appendix B (fields by marker, and the counts) matches the body — selectable 12 → 13, settable 5 → 4, and requestable 2 → 4. mixed 5 → 6 and seller-set 39 → 38, for 87 fields, up from 85
• Any affected example in examples/ is updated and still parses — proposal-issued.yaml shows selected[] beside included[], a value on geo and frequency_cap, and agreed_rate 27.54. Its record_digest is recomputed. line-item-display.yaml adds device and daypart, and the audio example moves to markets. manifest.json is regenerated. scripts/check_examples.py recomputes each agreed_rate and passes
• RFC 2119 keywords used deliberately — MUST / SHOULD / MAY are not synonyms
• The no-inheritance rule (§ 2) still holds — every BuyerWrites path sits on the line item
• Anything selectable declares available[] and included[]; anything settable declares bounds (§ 3.1, § 3.2) — markets declares both, and every settable field also declares default
• No confidential or commercially sensitive content

Knock-on effects

• Breaking. gross_rate, floor, and delta_pct become list_rate, min_rate, and delta_fraction. A delta_fraction of 0.02 is 2 percent. Country codes are ISO 3166-1 alpha-2. device and daypart change shape, and supported_formats is removed.
• Filings this answers.
  • selected[] and value are the keys @VJAlkimi asked for in [Change] § 3 — Name the key the buyer writes its selection to: selected[] on selectable fields, value on settable fields #22. default names [Change] § 3 — Name the key the buyer writes its selection to: selected[] on selectable fields, value on settable fields #22's declared default.
  • The formula follows @VJAlkimi's derivation in [Change] § 5.6 — Give the buyer's counter a field (requested_rate), state how agreed_rate is derived, and say who can read floor and seller_rate #30. It answers @aleksUIX's question on #30: a request moves list_rate, before options.
  • GeoCode, device types, and ClockWindow carry @dtbarne's [Change] § 5.5 — Typed geo codes aligned with the OpenRTB 2.6 Geo object #58 and @dineshbhat's [Change] § 5.5 — Type the device and daypart envelopes: AdCOM device types, and dayparts with a time-zone basis #111.
  • markets keeps @fgranata's per-market deltas from [Change] § 5.6 — Per-geo pricing: selectable geo with price deltas, and pricing[].guidance percentiles alongside floor #14, and § 5.5 — Selectable geo with per-market price deltas (#14) #72's "MUST NOT declare both".
  • min_rate keeps § 5.6 — pricing[].floor is the offer floor, not the auction floor (#16) #18's point, from @fgranata's [Comment] § 5.6 — pricing[].floor is the offer floor, not the downstream auction floor #16: it isn't the downstream auction floor.
• Changes from the filed text.
  • [Change] § 5.6 — Give the buyer's counter a field (requested_rate), state how agreed_rate is derived, and say who can read floor and seller_rate #30: requested_rate isn't added; a request on list_rate replaces it. Our reply read a granted rate as final. Here it becomes the next version's list_rate, and deltas still add. The reply's composed floor isn't added.
  • [Change] § 5.5 — Typed geo codes aligned with the OpenRTB 2.6 Geo object #58: our reply wrote { type, code } entries, max, and basis. They become GeoCode strings, count, and per, and end becomes before. person isn't a core per term.
  • § 5.6 — pricing[].floor is the offer floor, not the auction floor (#16) #18 and [Change] § 5.6, § 1.1, § 2.1 — Say which price a deal carries: agreed_rate as the Deals API dealfloor, with its pricetype; rename floor to min_rate #133: min_rate no longer resolves a counter without a round trip. floor doesn't stay as a deprecated alias.
• What later PRs of ours complete. Our signing PR takes min_rate out of the offered terms. Later PRs type the held terms, each mechanism's delivery_type, commitment_bounds, more option ids, and combine.

---

By opening this pull request I agree my contribution may be published under this
repository's licence, as set out in CONTRIBUTING.md.

Analyzed and generated with the help of Claude, fully reviewed by me.