What does the OpenRTB site object tell a buyer about where an ad runs?
Part of Supply path transparency
The short answer
The OpenRTB site object describes the website where an ad would appear: its domain, the page URL, the referrer, content categories and a nested publisher object naming the seller the exchange pays. Buyers match site.domain to that domain's ads.txt file and publisher.id to the exchange's sellers.json, then log both to audit what they bought.
Key takeaways
- An OpenRTB 2.6 bid request carries at most one Site, App or DOOH object, and a site ID or page URL is useful but not strictly required.
- site.domain is the field ads.txt is designed to be checked against, and the ads.txt 1.1 spec names publisher.id as the usual home of the seller's account ID.
- The publisher object describes whoever the exchange pays, which the spec says may be a publisher, an intermediary exchange or an ad network, not always the site owner.
- A blank page URL has documented seller side causes, so buyers should log it as missing rather than read it as fraud.
What does the OpenRTB site object contain?
The OpenRTB 2.6 specification (opens in a new tab) says the Site object should be included when the ad supported content is a website rather than an app or a digital out of home screen. A bid request must not contain more than one of a Site, App or DOOH object. Section 3.2.13 lists the attributes, and only one is marked recommended: id, the exchange's own identifier for the site.
Definition
- OpenRTB site object
- The part of a bid request that describes the website carrying the impression: where it is, what it is about and, through its nested publisher object, which seller account the exchange pays for it.
| Field | What the spec says it holds | What a buyer uses it for |
|---|---|---|
| id | Exchange specific site ID; recommended | Joining requests from one exchange only |
| name | Site name, which may be aliased at the publisher's request | Readable labels in logs, never proof of identity |
| domain | Domain of the site, for example mysite.foo.com | The domain whose ads.txt file is checked for the seller |
| page | URL of the page where the impression will be shown | Page level review and content checks after the fact |
| ref and search | Referrer URL and the search string that led to the page | Spotting traffic from unexpected places |
| cat, sectioncat, pagecat, cattax | IAB Tech Lab content categories for the site, the section and the page, in the taxonomy named by cattax | Seller supplied category labels to compare with the plan |
| mobile and privacypolicy | Whether the layout is optimized for mobile devices, and whether the site has a privacy policy (0 or 1) | Flags about the site, not the device or user |
| keywords or kwarray | Keywords about the site, in one of two formats; only one may be present | Seller supplied hints, read with caution |
| inventorypartnerdomain | A domain used for authorization when a site owner shares inventory with a content owner | Following authorization to the content owner's file |
| publisher and content | Nested Publisher and Content objects | Who is paid for the impression, and what content surrounds it |
How does site.domain relate to ads.txt?
The ads.txt 1.1 specification (opens in a new tab) says it is meant to be used in partnership with site.domain or app.bundle in OpenRTB bid requests. Its guidance for exchanges recommends that any system creating OpenRTB bid requests place the seller's account ID in Publisher.ID and populate Site.Domain with the domain that hosts the ads.txt file where that account ID is posted. The domain in the request and the domain in the file are designed to meet.
The match is made at the root domain, which the spec defines as the public suffix plus one string, derived with the Public Suffix List (opens in a new tab). A request for news.example.com is checked against the file on example.com, unless that root file declares the subdomain with a subdomain= line and an ads.txt exists there. Then, the spec says, only systems listed in the subdomain file are authorized to sell on it.
Check one site.domain value against ads.txt
- Reduce the domain to its root. Strip subdomains using the Public Suffix List, as the spec intends.
- Open the root ads.txt and look for subdomain lines. If the logged subdomain is declared and has its own file, use that file instead.
- Find the exchange's lines. Field one holds the advertising system's canonical domain, which each exchange documents for buyers.
- Match the account ID. The spec says field two must carry the same value used in transactions, and that in OpenRTB this is typically publisher.id.
- Note DIRECT or RESELLER, then stop. The file confirms authorization for the domain; it does not confirm that the page URL in the request is real.
What is the publisher object in a bid request?
Section 3.2.15 of OpenRTB 2.6 says the Publisher object describes the entity who directly supplies inventory to and is paid by the exchange, which may be a publisher, intermediary exchange, ad network or similar. So a sales house or reseller can sit in site.publisher while the site belongs to someone else. The object's own fields are id, name, cat with cattax, and domain.
publisher.id is the exchange specific seller ID. The spec says every ID must map to only a single entity that is paid for inventory transacted via that ID, and that it corresponds to a seller_id in the exchange's sellers.json. publisher.domain is the highest level domain of the seller. In the sellers.json specification (opens in a new tab), domain is the business domain of the company paid under the seller_id.
| What the buyer finds | What the guidance concludes |
|---|---|
| sellers.json domain equals OWNERDOMAIN in the site's ads.txt | The seller owns the site, a direct path |
| sellers.json domain equals MANAGERDOMAIN | The seller manages the site's monetization |
| sellers.json domain equals MANAGERDOMAIN with a country code | The seller manages the site for that country |
| sellers.json domain matches neither | The seller is a reseller of the inventory |
That logic comes from the Tech Lab's ads.txt and sellers.json implementation guidance (opens in a new tab). It lets buyers tell an owner, a manager and a reseller apart without trusting publisher.name, which the spec says may be aliased at the seller's request.
Why can the page URL be missing from a bid request?
OpenRTB does not force the field. The 2.6 text says that, at a minimum, it is useful to provide a site ID or page URL, but this is not strictly required. Google's Ad Manager help on ads.txt and app-ads.txt (opens in a new tab) also lists seller side reasons buyers may see blank or empty URLs in bid requests from that platform, so a missing value can come from setup rather than fraud.
| Reason | Where it is documented | What the buyer can conclude |
|---|---|---|
| The seller chose not to send it | OpenRTB 2.6: site ID or page URL useful but not strictly required | Nothing about the site; ask the exchange what it sends |
| A root domain has no ads.txt file | Google Ad Manager: bid requests may include a blank or empty URL if the file for a domain is missing | Check the domain's ads.txt before buying it again |
| A page URL override was set up wrongly | Google Ad Manager: an invalid page_url override or passback can produce a blank URL | A publisher setup fault, worth reporting to the exchange |
| The page and domain disagree | Not a documented setup case | A mismatch to investigate with the request ID, as distinct from a blank |
Keep two states apart in the log. A blank page is missing data and becomes a question to the seller. A page whose host does not belong to the logged domain is a contradiction and goes into an investigation with the request ID, alongside the domain spoofing checks.
Which site fields should buyers log?
The checklist below keeps what is needed to repeat the ads.txt and sellers.json match months later, without storing anything about the person who saw the ad. It sits alongside the request level fields in the bid request guide.
Site and publisher fields worth keeping in bid logs
- site.domain exactly as received, plus the root domain the buyer derived from it.
- site.page, with a marker for blank, so missing values can be counted per seller.
- site.publisher.id and the exchange that sent it, since the ID is exchange specific.
- site.publisher.domain, to compare with the domain in the exchange's sellers.json.
- site.cat and site.cattax together, so category codes are read in the right taxonomy.
- site.inventorypartnerdomain when present, because authorization then follows a second ads.txt.
- The date each ads.txt and sellers.json file was read.
- The request ID and impression ID, to send any mismatch back to the exchange.
What does a site object review look like on a real plan?
Fictional example
A locksmith service checks its Tennessee site list
An unnamed locksmith and home lock service with crews in Nashville, Memphis and Knoxville runs display ads on local news, home improvement and neighborhood sites in English. Its agency pulls a week of won impression logs to see what the site objects said.
One local news site, citydaily.example, appears with two subdomains in site.domain. The root ads.txt declares one of them with a subdomain= line, so the planner checks that subdomain's own file and finds the exchange's account listed as DIRECT. The undeclared subdomain falls under the root file, which lists the account too.
A home improvement site shows a publisher.id whose sellers.json domain matches neither the OWNERDOMAIN nor a MANAGERDOMAIN in its ads.txt. Under the Tech Lab guidance that seller is a reseller, which is allowed, so the line stays with a note. Some requests from one seller arrive with site.page blank; the planner records them as missing and asks the exchange why.
How does PlacementGraph show who sells a site before any bid request arrives?
Frequently asked questions
When does a bid request use the App object instead of the Site object?
OpenRTB 2.6 says the App object should be included when the ad supported content is a non browser application, typically on mobile, as opposed to a website. A request must not carry more than one of Site, App or DOOH. Apps identify themselves with bundle and storeurl, and their sellers are declared in app-ads.txt rather than ads.txt.
Is site.id the same for one website on two exchanges?
No. The specification calls site.id an exchange specific site ID, so two exchanges can give the same website different values. To group one website across exchanges, buyers use the root of site.domain, and keep site.id only for joining records that came from the same exchange.
Does site.mobile tell a buyer the visitor is on a phone?
No. In OpenRTB 2.6, site.mobile indicates whether the site has been programmed to optimize layout when viewed on mobile devices. It describes the website, not the visit. Device details travel in the separate Device object, which carries fields such as the device type, operating system and user agent.
What does inventorypartnerdomain mean on a website request?
It names a content owner that has the right to monetize part of the ad inventory within the site. The spec says the content owner's domain should be listed in the site owner's ads.txt as an inventorypartnerdomain, and authorization for that supply is published in the ads.txt on the root of the partner's own domain.
Sources
- OpenRTB 2.6 specification, sections 3.2.13 Site and 3.2.15 Publisher (opens in a new tab)IAB Tech Lab
- ads.txt 1.1 specification (opens in a new tab)IAB Tech Lab
- sellers.json specification (opens in a new tab)IAB Tech Lab
- ads.txt and sellers.json implementation guidance (OWNERDOMAIN and MANAGERDOMAIN) (opens in a new tab)IAB Tech Lab
- AdCOM 1.0, List: Category Taxonomies (opens in a new tab)IAB Tech Lab
- Ads.txt and app-ads.txt FAQ: blank or empty URLs in bid requests (opens in a new tab)Google Ad Manager Help
- Public Suffix List (opens in a new tab)Mozilla Foundation
Researched and written by PlacementGraph Research. Read how we research, source and update these pages. Corrections: diana@placementgraph.com.