D-028 What do the § 2.1 Summary Representation and the § 2.3 manifest hold?

What the schemas do

The summary is a projection of each document onto the listed fields. The manifest is a third document. Its entries include the proposal's summary and add the keys § 2.3 names.

Options

• profiles Chosen

  The summary is a projection of each document onto the listed fields. The manifest is a third document. Its entries include the proposal's summary and add the keys § 2.3 names.

• hand-written

  The summary and the manifest are separate objects with their own members.

Why

§ 2.1 lists the fields a summary MUST contain, so the summary is the line item restricted to those fields, plus the listed proposal fields, and the model projects it from the documents (type rules § 9 has no rule for it, because the profile is a schema). It projects paths, not whole fields: the summary's formats holds only included[], and each of its pricing[] entries holds cost_method and gross_rate, read as those sub-fields of every entry, with the currency a rate requires (D-036). Each path the "MUST contain" list names, and each path "plus, from the parent proposal" continues it with, is required at every step, as type rules § 4 reads a requiring statement that introduces a list. "Property names" names no member, so it is read as the name of each option in properties.available[], and it keeps the presence the line item gives each step: a summary may leave properties out, and one that carries it carries available[], each entry a name or an unresolved catalog_ref. has_requires, which no table defines, is the boolean that § 2.1 defines in prose. A summary gives the placement keys that its line item declares, so the profile projects placement to those four keys, each optional. The summary holds channel too, so a video line item's summary gives plcmt: the line item must declare it (§ 5.2), and § 2.1 makes the summary give what the line item declares. The profile doesn't restate the § 5.2 rule, though. The rule is the line item's, one rule in one place (type rules § 5), and the summary is a projection of it, published with the full_url of the record whose rule decides it; and for the ctv line items the summaries hold, the rule is undecided (D-035). The manifest { seller_id, generated_at, spec_version, proposals[] } is published on its own, so it is a document. Its spec_version names a release of a document another party publishes, the specification, which names its releases as 3.0, so it is an ExternalId, carried as written and compared by exact equality. § 2.3 says each proposals[] entry carries proposal_id, version, the summaries of its line items, and a full_url. So an entry, named ProposalsEntry as type rules § 7 names an item of proposals[], includes the proposal's summary profile, which holds proposal_id, and adds version, as the proposal's own field, and full_url. "Carries" states no presence, so the added members are optional (type rules § 4). The key that holds the line-item summaries is unnamed. The manifest example calls it line_items, but the example isn't part of the pinned specification, so the entry is open rather than name the key (D-016).

What we ask the specification to state

• Name the key of each manifest entry that holds the line-item summaries, and say which members of an entry are required.
• Write the summary's paths as they are in the tables: pricing[].cost_method, pricing[].gross_rate, and properties.available[].name. Then the property names are required like every other listed path.
• List pricing[].currency, without which a summary's rate can't be read.
• Give has_requires a row.

The specification lines it rests on

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

main

• § 2.1, a requirement L76 at 44dfaaf

  It MUST contain, per line item:

• § 2.1, paragraph 3: the list of identifiers L79 at 44dfaaf

  line_item_id · channel · content_detail · property names · formats.included[] · pricing.cost_method · pricing.gross_rate · min_spend · addressable_scale · committed_metrics[] · transaction_mechanism

• § 5.2, the properties row L225 at 44dfaaf

  properties | Object | selectable | available[] of { id, name, domains, supported_formats }, included[], pricing, max_select

• § 2.1, paragraph 4: the list of identifiers L84 at 44dfaaf

  proposal_id · seller_name · description · valid_from · valid_until

With the open PRs

• § 2.3, paragraph 2: the inline object L117 in #76

  { seller_id, generated_at, spec_version, proposals[] }

• § 2.1, a requirement L69 on main at 981a74e

  It MUST contain, per line item:

• § 2.3, a requirement L115 in #76

  A seller MAY publish https://<seller domain>/.well-known/openproposal.json.

• § 2.1, paragraph 3: the list of identifiers L79 in #119

  line_item_id · channel · environments.available[] · content_detail · property names · formats.included[] · pricing.cost_method · pricing.gross_rate · min_spend · addressable_scale · committed_metrics[] · transaction_mechanism · has_requires

• § 2.1, a requirement L89 in #120

  A line item that carries placement (§ 5.2) MUST also give, in its summary, whichever of placement.reward · placement.instl · placement.plcmt · placement.skip it declares.

• § 2.1, paragraph 7: the list of identifiers L90 in #120

  placement.reward · placement.instl · placement.plcmt · placement.skip

• § 5.2, the properties row L225 in #17

  properties | Object | selectable | available[] of { id, name, domains, apps, supported_formats }, included[], pricing, max_select. Each property MUST carry domains, apps or both

• § 2.1, paragraph 4: the list of identifiers L77 on main at 981a74e

  proposal_id · seller_name · description · valid_from · valid_until · linked_execution

• § 2.1, a sentence L88 in #70

  has_requires is true when the line item declares requires (§ 5.6.3), so a screening agent does not recommend a line item that cannot be bought on its own.

• § 2.3, a sentence L117 in #76

  Contents: { seller_id, generated_at, spec_version, proposals[] }, where each entry in proposals[] carries proposal_id, version, the Summary Representation (§ 2.1) of each line item, and a full_url for the second phase.

Examples that disagree with the text

What it shapes

main: LineItemSummary, ProposalSummary, LineItem.properties

With the open PRs: LineItemSummary, Manifest, ProposalSummary, ProposalsEntry, LineItem.properties, Manifest.generated_at, Manifest.proposals, Manifest.seller_id, Manifest.spec_version, ProposalsEntry.full_url, ProposalsEntry.version