DEV Community

Aleksander Sekowski
Aleksander Sekowski

Posted on

OpenRTB 3.0 Placement With Only tagid Has No AdCOM Subtype

#openrtb #adtech #json #advertising

A supply-side adapter ships its first OpenRTB 3.0 bid request. The envelope validates. domainspec is adcom. Each item has an id and a spec.placement with the same tagid the 2.x integration used on imp.banner.tagid. The exchange accepts the HTTP 200 and returns no bids.

Nothing in that JSON is syntactically wrong. The failure is semantic: AdCOM never learned what format the placement is.

{
  "openrtb": {
    "ver": "3.0",
    "domainspec": "adcom",
    "domainver": "1.0",
    "request": {
      "id": "req-3-0-no-subtype",
      "item": [
        {
          "id": "item-1",
          "spec": {
            "placement": {
              "tagid": "banner-atf"
            }
          }
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The Placement object names the ad slot. It does not declare banner, video, or audio inventory. Under AdCOM that is an incomplete object, not a minimal valid one.

What "subtype" means in AdCOM

OpenRTB 2.x kept format fields as siblings on imp: imp.banner, imp.video, imp.audio, imp.native. OpenRTB 3.0 folds the inventory description into AdCOM objects under item.spec on the request side and under bid.media on the response side.

AdCOM models several core objects as a discriminated union. A Placement must include at least one of:

  • display (banner or similar display placement)
  • video (video placement constraints)
  • audio (audio placement constraints)

An Ad on the bid response side has the same rule: at least one of display, video, or audio under media.ad. A Native Asset needs at least one of title, image, video, data, or link. An AssetFormat in a native request template needs at least one of title, img, video, or data.

These are not optional decoration fields you add when you have time. They are how AdCOM knows which branch of the object you mean. tagid, id, w, and h are metadata on top of a branch that must exist first.

The migration trap is copying 2.x shape into 3.0 paths without moving the format block. On 2.x, imp[0].video.mindur beside imp[0].tagid was enough. On 3.x that same video block belongs under item[0].spec.placement.video. Leaving only placement.tagid is the 3.0 equivalent of an imp with no banner, no video, and no native.

OpenRTB 2.6 also moved many enumerated lists into AdCOM (plcmt, pos, content taxonomies). That work is about value lists. The subtype rules are about object shape: which child object carries the format contract. Both matter, and they fail in different ways.

How you catch it

Schema validation that only checks required keys on Placement will miss this. The object has an id path. JSON parsers are happy.

I maintain RTBlint, an open source OpenRTB linter. On the fixture above it reports:

$ rtblint validate --version 3.0 bid-request.json
FAILED (OpenRTB 3.0 bid request): 1 error(s), 0 warning(s).
- [error] openrtb.request.item[0].spec.placement: A Placement needs at
  least one of display, video, or audio.
  (adcom.placement.subtype_required)
Enter fullscreen mode Exit fullscreen mode

The same pattern fires on responses. A bid that prices against item-1 but returns an Ad shell with only id fails adcom.ad.subtype_required:

"media": {
  "ad": {
    "id": "creative-no-subtype"
  }
}
Enter fullscreen mode Exit fullscreen mode

Native paths have parallel rules. An Asset with only id and no title, image, video, data, or link triggers adcom.asset.subtype_required. A native request template whose AssetFormat lists sizes but no asset type triggers adcom.assetformat.subtype_required.

Paste the payload into the browser tester if you do not have the CLI handy. The rule id names the AdCOM object and the missing branch, which is faster than diffing against the PDF when you are debugging a 3.0 adapter for the first time.

Where to go next

Start with the placement subtype rule reference for the exact request-side requirement and example invalid payloads.

If you are mapping 2.6 video fields forward, read how AdCOM 1.0-202607 renamed content objects and extended enum lists on the AdCOM 1.0-202607 enums blog post. That snapshot is separate from subtype shape, but the same migration project usually touches both.

For response-side QA, keep the Ad subtype rule beside your seatbid fixtures. A valid price and item reference does not rescue an Ad object with no creative branch.

RTBlint is independent of IAB Tech Lab. The rule ids above cite the published AdCOM object definitions because that is where the requirements live, not because this is an official tool.

Top comments (0)