§ 5.6.2 — Holds: offered hold terms and the live hold (#66) by KonstantinMirin · Pull Request #143 · IABTechLab/OpenProposal

KonstantinMirin · 2026-11-04T14:39:58Z

What this changes

Draft 1 keeps a hold's offer and its live state in one object, hold_status, so § 4.1.1 needs a removal path with an exception. This PR splits the object in two.

hold_terms, { available, duration }, offers the hold. It is seller-set and inside the record. An absent hold_terms offers no hold, and asking for one returns not_offered (§ 2.4).
hold is the buyer's hold. It is lifecycle, outside the record, and absent until the buyer first asks. It carries status, version, position, and valid_until.
Two OPTIONAL hold keys state terms: requested_terms, a LineItemWrites, and held_availability, what the seller reserves.
HoldStatus adds declined and drops none. The transitions are exhaustive. A declined, expired, or released hold can be asked again, and a re-offer is the listed held → held transition.
The held terms are the offered terms of hold.version.
hold.reference is the seller's id for the reservation, and renewal_right is an offered term for the next cycle.
hold_scope is removed. Under linked_execution: all, the holds on a proposal move as a unit. Our packages PR moves this rule to packages.
§ 2.3: the manifest's hold_limits caps concurrent holds per buyer and per advertiser, from @pkanna000 and @premesh.

Related issue

Closes #66, a change request from Postindustria (IAB Tech Lab member).

Refs #67 and #156.

Builds on

This PR builds on our buyer writes PR. That PR builds on our lifecycle PR, our parties PR, our errors and extensions PR, and our shared types PR. Through them, it carries #18, #70, #71, and #72 by @Sirajmx, #73, #74, #75, and #76 by @Kishore-2572, and #118 by @aleksUIX. Review the commits "Split holds into offered terms and live state", "Answer the open hold questions and offer a renewal right", "Let a seller declare hold limits in the manifest", and "Put the holds entry's Breaking marker at its end"; the others belong to those PRs.

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 — § 2.3, § 2.4, § 3.4, § 4.1.1, § 4.1.3, § 4.3, § 4.3.1, § 4.3.2, § 4.3.4, § 5.6, § 5.6.1, § 5.6.2
Appendix A (field index) matches the body — the hold_status row becomes hold_terms (seller-set) and hold (lifecycle). scripts/check_appendix.py passes, with Availability listed as a pending type
Appendix B (fields by marker, and the counts) matches the body — seller-set 38 → 40, lifecycle 1 → 2, mixed 6 → 5; 87 → 89 fields
Any affected example in examples/ is updated and still parses — line-item-ctv.yaml offers no hold on its private_auction line item. line-item-display.yaml and proposal-issued.yaml carry hold_terms. proposal-issued.yaml shows a hold granted on version 1 and re-offered at version 2, and its record_digest is recomputed. scripts/check_examples.py passes, and checks requested_terms against the BuyerWrites paths
RFC 2119 keywords used deliberately — MUST / SHOULD / MAY are not synonyms
The no-inheritance rule (§ 2) still holds — hold_terms and hold sit on the line item
Anything selectable declares available[] and included[]; anything settable declares bounds (§ 3.1, § 3.2) — no new selectable or settable fields
No confidential or commercially sensitive content

Knock-on effects

Breaking. hold_status is removed. hold_available and hold_duration become hold_terms.available and duration. state and hold_expires_at become hold.status and valid_until. A line item that carried hold_status gets a new record_digest.
Pending type. The held_availability row in § 5.6.2 has the Type Availability, which has no key table yet. It stays a pending type until our pricing PR adds that table. Until then, the example uses the availability row's keys.
Filings this answers.
- [Change] § 5.6.2 — hold_status needs refused and re-entry to requested #66: declined is the value [Change] § 5.6.2 — hold_status needs refused and re-entry to requested #66 asked for as refused. Our comment on #66 asked that a hold freeze the held terms. A seller change is a new version, so the seller re-offers or releases the hold.
- position is the queue order @premesh describes on #66: seller-set, in the order granted. It answers [Change] § 5.6.2 — hold_status needs refused and re-entry to requested #66 question 5.
- held_availability carries the held quantity @EvgenyAndroid asks for, answering [Change] § 5.6.2 — hold_status needs refused and re-entry to requested #66 question 7. Their point that the queue position is status, which @premesh agrees with, puts all of hold outside the record.
- The CTV example uses available: false where no inventory is reserved, as @EvgenyAndroid and @premesh agree.
- [Change] § 3, § 5.6.1, Appendix B — A resolved commitment is an offer until the seller accepts #67: § 5.6.1 names hold.position in the exception to its bar on declining.
Merging with our signing PR. This PR and our signing PR conflict in § 3.4, § 4.1.1, § 4.1.3, § 4.3 to § 4.3.4, Appendix B, the issued example, and the examples checker. Our pricing PR builds on both and carries the merged text.

Open questions

Answered in review:

Yes, by @EvgenyAndroid. A hold stays live under a commit made while it runs. held → expired waits until that commit is answered. Otherwise a seller could leave it unanswered until the hold lapses, then decline for lack of availability.
Yes. held means reserved inventory, as @EvgenyAndroid and @premesh agree. A seller that only honors terms uses hold_terms.available: false with price_valid_until.
Yes. hold.reference holds the seller's id, as @EvgenyAndroid asks ([Change] § 5.6.2 — hold_status needs refused and re-entry to requested #66 question 6). hold is live state, so it adds no version.
renewal_right is @premesh's first refusal, negotiated, so an offered term inside the record, as @EvgenyAndroid agrees.

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.

§ 5.6 defines floor as the seller's offer floor at proposal time, not the downstream auction floor and not a guarantee that bids will clear. Editorial: the meaning of the field is unchanged. Refs IABTechLab#16

A proposal can say its line items must be bought together (linked_execution, § 4.1), and a line item can name the line items or spend that must be in the same commitment (requires, § 5.6.3). A bonus line is a line item with requires and its own price. The § 2 "binding terms" hook now points at a field, and the Summary Representation carries has_requires and linked_execution. Adds a CTV bonus line example (§ 6.5) and linked_execution: none to the proposal example. Refs IABTechLab#23

The seller declares which exclusion types it accepts and how it enforces each (exclusions_accepted); the buyer supplies its lists (exclusions). Blocked apps carry their store, { platform, bundle }, so one store id is never applied across stores. Exclusions are recompute inputs (§ 3.3) and are never disclosed to other parties (§ 5.8). The display example declares and supplies lists. Refs IABTechLab#25

A line item whose rate differs by market can declare geo with the selectable structure of § 3.1: available[], included[], pricing deltas and max_select. A geo that declares only allowed[] stays settable, so existing payloads are unchanged. When several priced markets are selected, the highest delta applies. The audio example is priced by market. Refs IABTechLab#14

A commitment names the proposal and version it was priced against (§ 5.6.1). The seller rejects a new attempt on a stale version, or past valid_until or price_valid_until, and returns the current version. An authenticated replay with the same idempotency_key and terms returns the stored result without re-running those checks; the same key with different terms is a conflict. Keys are opaque and scoped to one buyer and seller pair. § 4.1 states that each revision while published increments version. The display, CTV and audio examples carry proposal_id and version. Refs IABTechLab#24

§ 4.1 adds an optional, immutable proposal_template_id linking an issued proposal to the seller's template. Each issued proposal has its own status, version and negotiation_history[], and buyers never need the template id to transact. § 7 adds a non-normative note separating seller-side templates from the issued proposals buyers commit against. Appendix A gains one row; Appendix B counts immutable 6 → 7 and 72 fields. The proposal example carries a proposal_template_id. Refs IABTechLab#26

§ 5.8 adds terms_ref ({ url, sha256, version }), REQUIRED when terms_acceptance_required is true, hash-pinned and frozen at agreed, so assent binds to an exact document. § 5.10 adds agreement_ref, an informative pointer to the master or annual agreement a line item is priced under, and documents the io and agreement roles on external_references[]. IO generation is stated to be a connector concern, and § 7 adds a non-normative note on relationships. agreement_ref is seller-set; a buyer-held agreement id travels as an external_references[] entry with role: agreement, so the field keeps one marker (§ 3). Appendix A gains two rows; Appendix B counts seller-set 29 → 31 and 73 fields. The display example carries terms_ref. Refs IABTechLab#27

A new § 2.3 lets a seller publish its public standard line items at /.well-known/openproposal.json: seller_id, generated_at, spec_version and, per proposal, proposal_id, version, the Summary Representation of each line item and a full_url. ETag / Last-Modified are required, only line items with visibility public appear, and entries must match the current version. Buyers discover from the manifest, then fetch the Full Representation of shortlisted line items. Adds examples/manifest.json (§ 6.5) and visibility: public to the CTV and audio examples; the registry_gated display line item is not listed. Refs IABTechLab#29

The specification does not define authentication yet (WS1; see IABTechLab#62), so the replay rule now applies to a replay from the same buyer rather than an authenticated replay. Refs IABTechLab#24

agreement_ref.parties used buyer_id, which the specification does not define. parties[] now names the seller by its seller_id and the buyer by the id it holds in eligible_bidders[] (section 5.8). Refs IABTechLab#27

The rule that a hold on a linked_execution: all proposal uses hold_scope: proposal came from a comment on IABTechLab#23, not the change request as filed. It moves to the PR description as a point for the working group, so this PR carries only the filed change. Refs IABTechLab#23

IABTechLab#25 names the content-category list iab_content_category[], a list of IAB Content Taxonomy ids. The earlier commit renamed it content_category with a version-pinned taxonomy_ref, which nobody proposed. This restores the filed name and shape; which taxonomy version to reference is left to the working group. Refs IABTechLab#25

IABTechLab#14 doesn't say how deltas combine when a buyer selects more than one priced market, and neither did any comment on it. The earlier commit said the highest delta applies; that is a design choice nobody proposed, so it moves to the PR description as a question. Refs IABTechLab#14

Read the media condition from the ad served when an impression accepts several media, name the seller as the party that serves, place linear TV outside the table, and state environments as (distribution channel, device type) pairs. Insert environments.available[] into the summary list without rewrapping it, shorten the changelog entry and drop audio_streaming from OQ-7 in docs/open-questions.md. Refs IABTechLab#90

time_zone is the line item's clock for daypart windows and frequency_cap.period: an IANA time zone name or viewer_local. A window is { days[], start, end } in civil time with an exclusive end later than start, up to 24:00; a window that crosses midnight is two windows.

List the `days[]` values once in the `daypart` row, as `monday` | ... | `sunday`. Write HH:MM, America/New_York, and UTC as plain text, since they're a format and examples, not field names. The meaning is unchanged.

"At least one of" an empty list is never satisfied, so the bonus line would fail a literal check. An absent key sets no condition. Only the examples change; the any_of[] row and the rules stay as filed in IABTechLab#23. Refs IABTechLab#23

The floor row now says it "neither constrains nor describes the downstream auction floor", as IABTechLab#16 asked, and names that floor: the per-impression floor the exchange applies at auction time (OpenRTB 2.6 Imp.bidfloor). Refs IABTechLab#16

From the Postindustria review on IABTechLab#73: - a replay matches on the same body, every value the buyer sent except idempotency_key, and returns the stored result whether an acceptance or a rejection; a retry against a new version uses a new key; - version increments on each revision of the proposal, not only while published, so a counter under review also moves it; - "deterministic" now says what the checks depend on: the stored proposal and the time the seller receives the attempt; - the price check names the pricing[] entry the commitment is priced against. Refs IABTechLab#24

Give each repeated concept one type in section 2.2, and state the table, presence, type, key, and value rules in section 2.6. Add Type and Required columns to every field and key table. Add the lifecycle, recorded, asserted, and mixed markers, and a line_items[] field. Define the Summary as a strict path subset, with manifest key tables. Delete catalog_ref. Rename the time, reference, delta, cap, and path fields to use the shared types. Number every heading, and keep issue citations and edit history out of normative text. Update the examples, the manifest, the appendices, and the docs. Teach check_appendix.py the new columns and a closed layout list, and add check_examples.py, which checks the examples against the spec's tables.

State that held means reserved inventory. Keep a hold live while a commit made during it is open, so a seller can't leave the commit unanswered until the hold lapses and then decline it for lack of availability. Add the seller's hold reference and renewal_right, an offered term for the right to the next cycle. Refs IABTechLab#66

KonstantinMirin · 2026-11-05T12:14:17Z

Thanks, @premesh and @EvgenyAndroid. All four are in this PR, so you can review them here:

renewal_right: a seller-set term inside the record, versioned like any other. Core term first_refusal; absent means no such right. It sits apart from hold.position.
A hold under a commit: held → expired waits until a commit made during the hold is answered. Otherwise a seller could leave it unanswered until the hold lapses, then decline for lack of availability.
held means reserved inventory. A seller that only honors terms uses hold_terms.available: false with price_valid_until.
hold.reference: the seller's id for the reservation. hold is live state, so it adds no version.

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

The manifest's hold_limits states the most holds a seller grants at once, per buyer domain and per advertiser. A seller declines a request over a declared limit, and under a per-advertiser limit may decline one that names no advertiser.

jaanijuk · 2026-11-09T06:26:58Z

Hold terms by transaction mechanism

Evidence from a desk test against this stack at 56cbd4da, with the same results at 598f5c8a (details on #134). JCDecaux Australia's indicative, experimental description of its own practice, shared with their permission for this exercise: on a direct insertion order it sometimes holds inventory for 24 hours, by hand; on programmatic guaranteed through its SSP it doesn't hold. Separation works the same way: checked by hand at scheduling on direct, not offered on programmatic.

In this PR, hold_terms is line-item wide. A transaction_mechanisms[] key on it is rejected (key 'transaction_mechanisms' is not in the HoldTerms table), and the same for the exclusivity option in #146. Price (pricing[].transaction_mechanisms[]) and delivery_type (§ 5.9) can vary by route inside one line item, so a seller that holds and separates only on direct must publish two line items over the same screens (§ 3.1).

Two questions:

Is that the intended shape? If so, a sentence in § 5.9 or § 5.6.2 would help: when two line items cover the same screens, does a hold granted on one reserve inventory the other also sells, and how is availability shared between them?
If not, would hold_terms.transaction_mechanisms[] (the mechanisms the hold is offered on; absent means all) be acceptable, with the same key on ExclusivityOption?

KonstantinMirin · 2026-11-09T09:01:27Z

Thanks, @jaanijuk. Yes, two line items is the intended form (§ 3.1). A price varies by route because each route has its own price. A hold or an exclusivity term is a promise about the inventory itself.

Your first question has an answer in § 5.6.2: holds on the same inventory reserve it in grant order (Hold.position). A hold on the direct line item reserves the screens the programmatic one also sells, and the availability the seller reports for each (§ 3.3) reflects it.

So I'd rather not add transaction_mechanisms[] to HoldTerms and ExclusivityOption. It would be a second way to say what two line items already say.

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

@aleksUIX

Add the rule @aleksUIX proposed on IABTechLab#42: a stitched preview uses a session with no production notifications, or the creative is inspected outside the stitched stream.

Sirajmx and others added 30 commits October 6, 2026 16:28

Clarify that pricing[].floor is the offer floor

ff53dc5

§ 5.6 defines floor as the seller's offer floor at proposal time, not the downstream auction floor and not a guarantee that bids will clear. Editorial: the meaning of the field is unchanged. Refs IABTechLab#16

Scope the replay rule to the same buyer

74a2544

The specification does not define authentication yet (WS1; see IABTechLab#62), so the replay rule now applies to a replay from the same buyer rather than an authenticated replay. Refs IABTechLab#24

Name agreement_ref parties with defined identifiers

b88e9a0

agreement_ref.parties used buyer_id, which the specification does not define. parties[] now names the seller by its seller_id and the buyer by the id it holds in eligible_bidders[] (section 5.8). Refs IABTechLab#27

Separate creative inspection from production notifications

7ab6d2b

Close inspection URL and notification-observation gaps

8fde92c

Define channel and environments in AdCOM terms

49ad2e2

Narrow creative inspection wording and separate fixture tooling

395ca83

Write the daypart day names as one value list

9783ec8

List the `days[]` values once in the `daypart` row, as `monday` | ... | `sunday`. Write HH:MM, America/New_York, and UTC as plain text, since they're a format and examples, not field names. The meaning is unchanged.

Merge IABTechLab#119, channel and environment definitions

c102a50

Merge IABTechLab#118, creative inspection

ecc0ae5

Merge IABTechLab#70, linked line items

48219db

Merge IABTechLab#76, well-known manifest

c04acd0

Merge the shared types change

c7a0eb7

Merge IABTechLab#71, buyer block lists

1705a49

This was referenced Nov 6, 2026

[Change] § 5.6.2 — Let a seller cap concurrent holds per buyer, and admit hold requests like commitments #156

Open

[Impl] commitment.idempotency_key has no scope, conflict rule or retention #128

Open

KonstantinMirin added 3 commits November 7, 2026 12:47

Let a seller declare hold limits in the manifest

ed74d0c

The manifest's hold_limits states the most holds a seller grants at once, per buyer domain and per advertiser. A seller declines a request over a declared limit, and under a per-advertiser limit may decline one that names no advertiser.

State that a min_rate is as readable as its line item

c95934c

Merge the buyer writes change

e9c837a

jaanijuk mentioned this pull request Nov 9, 2026

[Impl] DOOH line items have no standardized fields for venue, screens, spot and loop length, share of voice or impressions per play #134

Open

2 tasks done

KonstantinMirin added 20 commits November 10, 2026 11:56

Cover previews through server-side ad insertion

c85b053

Add the rule @aleksUIX proposed on IABTechLab#42: a stitched preview uses a session with no production notifications, or the creative is inspected outside the stitched stream.

Merge the shared types change

7a3958f

Merge the errors and extensions change

5317f7f

Merge the lifecycle change

d2a16c4

Merge the parties change

13cced5

Merge the buyer writes change

e5ec5a2

Record the shared types changes the changelog left out

bac1fef

Merge the shared types change

d3e2552

Merge the errors and extensions change

adb19b6

Merge the lifecycle change

010844e

Merge the parties change

160f145

Record the buyer writes changes the changelog left out

c86ef5f

Merge the buyer writes change

3d4dcf0

Put the holds entry's Breaking marker at its end

6b4d6c6

Read an integral number as an Integer, as JSON does

c7192f7

Merge the shared types change

a73d71e

Merge the errors and extensions change

d1da1e0

Merge the parties change

44535cf

Merge the lifecycle change

e15329e

Merge the buyer writes change

9b9ca68

Navigation Menu

Repository navigation

§ 5.6.2 — Holds: offered hold terms and the live hold (#66) - #143

§ 5.6.2 — Holds: offered hold terms and the live hold (#66)#143
KonstantinMirin wants to merge 69 commits into
IABTechLab:mainfrom
KonstantinMirin:op30-holds

KonstantinMirin commented Nov 4, 2026 •

edited

Loading

Uh oh!

KonstantinMirin commented Nov 5, 2026

Uh oh!

jaanijuk commented Nov 9, 2026

Uh oh!

KonstantinMirin commented Nov 9, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

KonstantinMirin commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this changes

Related issue

Builds on

Type

Checklist

Knock-on effects

Open questions

Uh oh!

KonstantinMirin commented Nov 5, 2026

Uh oh!

jaanijuk commented Nov 9, 2026

Uh oh!

KonstantinMirin commented Nov 9, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

KonstantinMirin commented Nov 4, 2026 •

edited

Loading