[Change] § 5.4 — Pin each format's spec to a version and keep it in the agreed record #87

What kind of change?

Change a field's type or shape

Which section?

5.4 — Creative requirements

Current text

§ 5.4:

| `formats` | Object | selectable | `available[]` of registry format ids namespaced by channel (`display/300x250`, `audio/host-read-30s`), `included[]`, `pricing`, `max_select` |
| `specs` | Object | seller-set | As defined by the referenced format registry entry. OpenProposal does not hardcode a shape per channel |

Proposed text

Shared types table (§ 2.2 in our shared types PR), add:

| `EntryRef` | String: `<domain>/<collection>/<entry_id>@<version>`, with no `/` or `@` inside a part | A named entry at one exact version, whose content does not change. `<domain>` is a `Domain`. It carries no digest |

§ 5.4, replace the `formats` and `specs` rows:

| `formats` | Selectable[FormatId] | OPTIONAL | selectable | Format ids, such as `display/300x250` and `audio/host-read-30s`. Absent: this line item states no format |
| `format_specs` | Map[FormatId, FormatSpec] | REQUIRED when the proposal has left `draft` and `formats` is present | seller-set | Map from format id to `FormatSpec` |

Add after the § 5.4 table:

**`FormatId`** is a String: `<channel>/<name>`, where `<channel>` is the line
item's `channel`, with no `/` or `@` inside a part.

**`FormatSpec`** keys:

| Key | Type | Required | Meaning |
| :--- | :--- | :--- | :--- |
| `spec_ref` | EntryRef | OPTIONAL | The format registry entry the spec comes from. Absent when the seller defines it |
| `spec` | Object | REQUIRED | The full specification. OpenProposal does not hardcode a shape per channel |

Once the proposal leaves `draft`, every id in `formats.available[]` MUST have a
`format_specs` entry. When `spec_ref` is present, `spec` MUST equal the content
of the version it names, and the format id SHOULD equal the
`<collection>/<entry_id>` part of `spec_ref`. A later registry version does not
change an agreed record's `format_specs`.

A `spec` MAY hold `asset`, a `VocabularyTerm` (§ 2.2) that says what the buyer
supplies for the format. Core terms: `audio_file` \| `video_file` \| `image_file` \|
`markup` \| `script`. A receiver that doesn't know a term treats that format as
unavailable.

Why

§ 5.4 doesn't say whether specs holds a format's spec or points at a registry entry. A format id has no version. If specs only points, the agreed record changes when the registry does. § 2.2 makes the agreed record "self-contained and immutable", but only for catalog_ref.

The CTV example pins the VAST version but not the spec of ctv/instream-15s. @unreconciled's CTV comment on #5 proposes that this entry follow the IAB Tech Lab video and CTV guidelines, which have 2008, 2015, and 2022 editions. The IAB/4A's Standard Terms and Conditions 3.0, § II(c), fix final specifications within two business days of IO acceptance.

Proposals on #5 and in #32 make an id resolve to a registry entry or an inline spec. This change says which version, and that the record keeps a copy. Our formats PR carries this text, on the EntryRef type from our shared types PR.

stateDiagram-v2
    state "published, format_specs pins version 1 and copies its spec" as pub
    state "agreed, record stores the spec" as agr
    [*] --> pub : leaves draft, each format has an entry
    pub --> pub : seller re-pins to version 2, proposal version n+1
    pub --> agr : assent
    agr --> agr : registry publishes version 2, record unchanged

Details and examples: Format specs in the agreed record: full rationale and examples

Knock-on effects

• specs becomes format_specs, and specifications (§ 4.2) becomes media_kit_detail.
• Format ids stay plain keys in included[], deltas, #22 selected[], and assets[].format_id, which [Change] § 5.4 — Validate assets[].format_ref against the resolved formats selection at submission, not at creative review #32's check looks up in format_specs. Our shared types PR renames pricing to deltas and format_ref to format_id.
• format_specs is a term, so record_digest covers it.
• asset gives [Change] § 5.4 — Validate assets[].format_ref against the resolved formats selection at submission, not at creative review #32's check the kind of file to expect. @bhillman-TelevisaUnivision and @premesh warn that it could otherwise reject a valid script or artwork.
• Under our versioning filing, a re-pin on a frozen version creates version n+1.

Open questions for the working group

1. Answered in our formats PR. Should format_specs[id] wrap the spec as { spec_ref, spec }, or hold the spec keys beside a reserved key? Validating an asset's format at submission (#32) and the spec-key proposal on open question 4 on format registry entries (#5) assume the second. It wraps, so spec_ref never clashes with a key of the spec.
2. Answered in our shared types PR. Is the copied spec enough? Or should the reference also carry an OPTIONAL content digest, such as a SHA-256 of the entry's canonical JSON? @EvgenyAndroid's catalog digest feedback (#129) asks the same for catalog_ref: "add an optional content digest alongside the version". The copy is enough: an EntryRef carries no digest, and record_digest covers the copy.
3. Answered in part in our formats PR: Should the spec name the format registry, its owner, and its location? Or should it leave that open until open question 4 on format registry entries (#5) settles the registry? A spec_ref names the registry by its domain. Still open: which registry that is and how to fetch an entry, which that PR adds to § 8 question 4.
4. Answered in our formats PR. Should every offered format need a format_specs entry once the proposal leaves draft, only at agreed, or at both points? Comments on open question 4 on format registry entries (#5) propose agreed for resolution. Once it leaves draft, so a buyer's selection never waits on the seller. The OQ-4 — The format registry has no entries for audio/*, ctv/* or dooh/* #5 rule for agreed stays on OQ-4 — The format registry has no entries for audio/*, ctv/* or dooh/* #5.
5. Answered in part in our formats PR: Should the format id be required to equal the <collection>/<entry_id> part of spec_ref (MUST)? Or may a seller source a differently named entry (SHOULD)? SHOULD, as filed. Still open: whether implementers need the MUST, which our rules issue asks.

Would this break an implementation already built to this draft?

Yes — breaking

Alternatives you considered and rejected

• A version inside the id (display/300x250@3): every re-pin renames the id wherever it is a key.
• A content digest without a copy: the record stops being self-contained.

You are commenting as

Other — IAB Tech Lab member (Postindustria).

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.

Revised 2026-11-04: Rewritten against our formats PR: specs becomes format_specs, a map of FormatSpec { spec_ref, spec }, with spec_ref an EntryRef string, and a spec can state asset. Our PRs answer open questions 1, 2, and 4, and answer 3 and 5 in part.

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