OpenProposal 3.0 JSON Schema Unofficial

Decision records · Changes we propose

D-039 How is a two-valued flag written where § 5.2.2 copies an AdCOM 0 | 1 integer?

Proposal Decision 41 on the supporting page of #121. Cited with the open PRs.

What we propose

A JSON boolean, as every other flag of the specification is.

As written

placement.reward, instl, and skip are the integers 0 (no) and 1 (yes), as § 5.2.2 and AdCOM 1.0 write them.

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

Options

  • boolean Chosen

    A JSON boolean, as every other flag of the specification is.

  • integer As written

    The integers 0 and 1, as § 5.2.2, AdCOM 1.0, and OpenRTB 2.6 write them.

Why

§ 5.2.2 says its keys follow AdCOM 1.0 and that each takes an integer, and it writes reward, instl, and skip as 0 (no) or 1 (yes), as AdCOM 1.0 and OpenRTB 2.6 write them. Every other yes-or-no value of the specification is a JSON boolean, such as hold_available and terms_acceptance_required. One encoding for one concept lets every receiver read a flag the same way, and a boolean can't take a third value, which an integer key can. The schema departs from the § 5.2.2 text: a seller that builds a bid request writes true as 1 and false as 0.

What we ask the specification to change

Write placement.reward, instl, and skip as JSON booleans, as every other flag of the specification is. Say they mean what the AdCOM fields of the same name mean. AdCOM 1.0 and OpenRTB 2.6 write these flags as the integers 0 and 1. A seller that builds a bid request writes true as 1 and false as 0, and reads them back the same way.

The specification lines it rests on

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

With the open PRs

  • § 5.2.2, the placement.reward key row L245 in #120
    reward | OPTIONAL | 0 (no) | 1 (yes). The user receives a reward for viewing the ad | Placement.reward, imp.rwdd
  • § 5.2.2, the placement.reward key row's meaning: the value list L245 in #120
    0 (no) | 1 (yes)
  • § 5.2.2, the placement.instl key row L246 in #120
    instl | OPTIONAL | 0 (no) | 1 (yes). The ad is interstitial or full screen | DisplayPlacement.instl, imp.instl
  • § 5.2.2, the placement.instl key row's meaning: the value list L246 in #120
    0 (no) | 1 (yes)
  • § 5.2.2, the placement.skip key row L248 in #120
    skip | OPTIONAL | Video or audio. 0 (no) | 1 (yes). The placement lets the user skip the ad | VideoPlacement.skip, AudioPlacement.skip, video.skip
  • § 5.2.2, the placement.skip key row's meaning: the value list L248 in #120
    0 (no) | 1 (yes)
  • § 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.

Examples that follow the text, not this change

ExampleWhereWhyInput
examples/line-item-rewarded-video.yaml/placement/instlThe example follows the text, which writes instl as AdCOM's 0 or 1: it writes 1. We propose a JSON boolean for every flag, true here.open PRs
examples/line-item-rewarded-video.yaml/placement/rewardThe example follows the text, which writes reward as AdCOM's 0 or 1: it writes 1. We propose a JSON boolean for every flag, true here.open PRs
examples/line-item-rewarded-video.yaml/placement/skipThe example follows the text, which writes skip as AdCOM's 0 or 1: it writes 0. We propose a JSON boolean for every flag, false here.open PRs

What it shapes

With the open PRs: LineItemSummaryPlacement.instl, LineItemSummaryPlacement.reward, LineItemSummaryPlacement.skip, Placement.instl, Placement.reward, Placement.skip

The record's YAML file