分册导航
sellers.json 1.0
1.0本页目录
本册定位
广告系统在自己根域下公开其代表的卖家身份与这些卖家在其系统内的标识,使买方能够发现一次竞价请求的最终卖家与全部中介。含 Parent / Identifier / Seller 三个对象、标准 identifier 名单与官方样例文件。
- 访问方法与文件格式
- 过期与缓存
- 实施:哪些广告系统必须发布该文件
- Parent / Identifier / Seller 三个对象的字段
- 标准 identifier 名单
- 官方样例文件(含其 JSON 瑕疵说明)
关键事实
- 版本
- 1.0
- 发布日期
- July 2019
- 官方源文件
- sellers-json.md
- sha256
- da90706a38d7
- 采集基线 commit
- 7682963ae241
- 抓取日期
- 2026-10-29
- 已入库
- sections 13 · objects 3 · fields 16
官方源瑕疵
以下是采集本册时在官方文档里发现的瑕疵,附行号级证据。站内一律照录不修复,页面渲染的样本保持官方原样。
sellers-json.md · Sample File Contents
非合法 JSON官方样例不是合法 JSON:seller_type 的收尾引号写成弯引号 U+201D("PUBLISHER”)。站内照录原文,另存一份仅替换该弯引号的可解析副本。原始错误:Bad control character in string literal in JSON at position 339 (line 16 column 27)
vendor/iab-supplychain/sellers-json.md:172
结构化要点
对象 · Parent
| 名称 | 类型 | 必填性 | 默认值 | 官方说明 |
|---|---|---|---|---|
| sellers | object array | 必填性 | — | The list of all Seller objects that are represented by the advertising system. All sellers must be included even if they are confidential. |
| identifiers | object array | optional | — | Array of Identifier objects associated with this advertising system. Examples could be TAG-Ids, Dun & Bradstreet business identifiers, or any custom identifier that a consuming advertising system might need. |
| contact_email | string | optional | — | An email address to use to contact the Advertising System for questions or inquiries about this file. |
| contact_address | string | optional | — | The business address of the advertising system. |
| version | string | 必填性 | — | The version of this spec, currently the only valid value is 1.0. |
| ext | object | optional | — | Placeholder for advertising-system specific extensions to this object. |
对象 · Identifier
| 名称 | 类型 | 必填性 | 默认值 | 官方说明 |
|---|---|---|---|---|
| name | string | 必填性 | — | The description of the identifier |
| value | string | 必填性 | — | The value of the identifier |
对象 · Seller
| 名称 | 类型 | 必填性 | 默认值 | 官方说明 |
|---|---|---|---|---|
| seller_id | string | 必填性 | — | This is the same ID that appears in an ads.txt file and in the SupplyChain.nodes array sid property. In most cases will also appear in the Publisher.Id property of an OpenRTB request. |
| is_confidential | integer | optional | 0 | Indicates whether the identity of the seller is confidential, where 0 = is not confidential and 1 = is confidential. |
| seller_type | string | 必填性 | — | An enumeration of the type of account, either PUBLISHER, INTERMEDIARY, or BOTH. A value of "PUBLISHER" indicates that the inventory sold through this account is on a site, app, or other medium owned by the named entity and the advertising system pays them directly. A value of “INTERMEDIARY" indicates that the inventory sold through this account is not owned by the named entity or the advertising system does not pay them directly. 'BOTH' indicates that both types of inventory are transacted by this seller. Note that this field should be treated as case insensitive when interpreting the data. |
| is_passthrough | integer | optional | 0 | A passthrough seller is a facilitator of inventory from the upstream supplier to the consumer of the inventory. The upstream supplier and consumer must establish a business relationship with each other such that the upstream supplier has control of their account within the consumer’s platform. A value of 1 indicates the following: - This seller has an account control relationship with the downstream/consuming advertising system. - If this seller is the last link in a SupplyChain, the buying system has to have established an account control relationship with this seller to transact the seller’s inventory. - If this is not the last link in a SupplyChain than this seller should exist between two entities that have an account control relationship. A value of 0 indicates: - The downstream/consuming advertising system has no account control relationship with this seller. |
| name | string | required when is_confidential=0 | — | The name of the company (the legal entity) that is paid for inventory that is transacted under the given seller_id. Can be omitted only when is_confidential is set to 1. |
| domain | string | required if seller has a web presence and is_confidential=0 | — | The business domain name of the company (the legal entity) that is paid for inventory that is transacted under the given seller_id. When the seller_type property is set to INTERMEDIARY or BOTH, this should be the root domain name of the seller’s Sellers.json file. Can be omitted when is_confidential is set to 1 or when the seller doesn’t have a web presence. |
| comment | string | optional | — | Any helpful description for this inventory. It is useful for sellers that have multiple seller ids to describe what this seller_id represents. |
| ext | object | optional | — | Placeholder for advertising-system specific extensions to this object. |
标准 identifier 名单
| identifier 名 | 官方说明 |
|---|---|
| TAG-ID | Trustworthy Accountability Group ID |
| DUNS | Dun & Bradstreet DUNS Number |
seller_type 枚举取值
- PUBLISHER
- INTERMEDIARY
- BOTH
官方样例文件
官方样例的 seller_type 收尾引号写成弯引号,整份不是合法 JSON。左侧照录原文,右侧是仅替换该弯引号后的副本,两者不混用。
官方原文(照录,非合法 JSON)
{
"contact_email": "adops@advertisingsystem.com",
"contact_address": "Advertising System Inc., 101 Main Street, New York, NY 10101",
"version": "1.0",
"identifiers": [
{
"name": "TAG-ID",
"value": "28cb65e5bbc0bd5f"
}
],
"sellers": [
{
"seller_id": "1942009976",
"name": "Publisher1",
"domain": "publisher1.com",
"seller_type": "PUBLISHER”
},
{
"seller_id": "1397382429",
"name": "Exchange1",
"domain": "exchange1.com",
"seller_type": "INTERMEDIARY"
},
{
"seller_id": "20000000",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "PUBLISHER",
"comment": "NorthAmerica O&O inventory"
},
{
"seller_id": "20000001",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "PUBLISHER",
"comment": "APAC O&O inventory"
},
{
"seller_id": "20000002",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "INTERMEDIARY",
"comment": "Non O&O inventory"
},
{
"seller_id": "101010101",
"name": "Hybrid Seller",
"domain": "hybridseller.com",
"seller_type": "BOTH",
"comment": "Sells both O&O and other sellers' inventory"
},
{
"seller_id": "00000001",
"seller_type": "INTERMEDIARY",
"is_confidential": 1
},
{
"seller_id": "EB_0001",
"name": "Passthrough Publisher",
"domain": "passthroughpublisher.com",
"seller_type": "PUBLISHER",
"is_passthrough": 1, "comment": "direct buyer/seller of this inventory must establish an account relationship with Passthrough Publisher" }
]
}仅替换弯引号后的可解析副本
{
"contact_email": "adops@advertisingsystem.com",
"contact_address": "Advertising System Inc., 101 Main Street, New York, NY 10101",
"version": "1.0",
"identifiers": [
{
"name": "TAG-ID",
"value": "28cb65e5bbc0bd5f"
}
],
"sellers": [
{
"seller_id": "1942009976",
"name": "Publisher1",
"domain": "publisher1.com",
"seller_type": "PUBLISHER"
},
{
"seller_id": "1397382429",
"name": "Exchange1",
"domain": "exchange1.com",
"seller_type": "INTERMEDIARY"
},
{
"seller_id": "20000000",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "PUBLISHER",
"comment": "NorthAmerica O&O inventory"
},
{
"seller_id": "20000001",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "PUBLISHER",
"comment": "APAC O&O inventory"
},
{
"seller_id": "20000002",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "INTERMEDIARY",
"comment": "Non O&O inventory"
},
{
"seller_id": "101010101",
"name": "Hybrid Seller",
"domain": "hybridseller.com",
"seller_type": "BOTH",
"comment": "Sells both O&O and other sellers' inventory"
},
{
"seller_id": "00000001",
"seller_type": "INTERMEDIARY",
"is_confidential": 1
},
{
"seller_id": "EB_0001",
"name": "Passthrough Publisher",
"domain": "passthroughpublisher.com",
"seller_type": "PUBLISHER",
"is_passthrough": 1,
"comment": "direct buyer/seller of this inventory must establish an account relationship with Passthrough Publisher"
}
]
}官方正文
以下正文按官方原文顺序照录,未改写、未补写、未翻译;小节编号与标题取自官方文档,锚点与官方 slug 规则一致。
Introduction
Ads.txt has been extremely successful in allowing publisher content distributors and app publishers to define who is authorized to sell a given set of impressions (publisher’s advertising inventory) via a bid request. Ads.txt does not, however, make any attempt at revealing the identities of the publisher account IDs within their advertising platform(s) (Publisher's SSPSupply-Side Platform).
A published and accessible Sellers.json file allows the identity of the final seller of a bid request to be discovered (assuming that they are ads.txt authorized). It also allows the identities of all nodes (entities that participated in the bid request) in the SupplyChain object to be discovered. Currently, it is possible for the final seller to be identified via the Publisher.name and Publisher.domain attributes, but in practice, these properties are inconsistently populated by various selling systems.
Sellers.json enables smaller bid request object sizes by allowing this information to be looked up and cached “offline” rather than supplied with every bid request. Sellers.json also allows the identification of any and all intermediaries that participated in the selling of a bid request.
Audience
Advertising systems, whether they are sellers or buyers of programmatic advertising both benefit from a transparent marketplace where all parties to the transaction are well understood. This document serves to define the information that sellers will provide to both downstream sellers and buyers of programmatic inventory.
Change Log
| Version | Date | Changes |
|---|---|---|
| 1.0 | July 2019 | First Version |
SPECIFICATION
This document specifies a mechanism for advertising systems to publicly declare the sellers that they represent and those sellers’ identifiers within their systems. It also describes the format for encoding the instructions to be consumed by advertising systems and their customers.
ACCESS METHOD
Advertising systems should post the sellers.json file on their root domain and any subdomains as needed. For the purposes of this document the “root domain” is defined as the “public suffix” plus one string in the name. Crawlers should incorporate Public Suffix list [16] to derive the root domain.
The declarations must be accessible via HTTP and/or HTTPS from the website where the instructions are to be applied under a standard relative path on the server host: "/sellers.json" and HTTP request header containing "Content-Type: application/json". Additionally, you could use "Content-Type: application/json; charset=utf-8" to explicitly signal UTF8 support.
Also, HTTPS connections over HTTP are preferred when crawling sellers.json files. In any case, where data is available at both an HTTPS and an HTTP connection for the same URL, the data from HTTPS should be preferred.
For convenience we will refer to this resource as the "/sellers.json" file. Despite the use of the word "file," the resource need not originate from a file system.
If the server response indicates Success (HTTP 2xx Status Code,) the advertising system must read the content, parse it, and utilize the declarations.
If the server response indicates an HTTP/HTTPS redirect (301, 302, 307 status codes), the advertising system should follow the redirect and consume the data as authoritative for the source of the redirect, if and only if the redirect is within the scope of the original root domain defined as the public suffix plus one string in the name as defined above. Multiple redirects are valid as long as each redirect location remains within the original root domain. For example an HTTP to HTTPS redirect within the same root domain is valid.
Only a single HTTP redirect to a destination outside the original root domain is allowed to facilitate one-hop delegation of authority to a third party's web server domain. If the third party location returns a redirect, then the advertising system should treat the response as an error. A future version may address other delegation of authority to a third-party web server, but for now redirects to a third-party web server and any other redirect should be interpreted as an error and ignored.
If the server response indicates the resource does not exist (HTTP Status Code 404) or for any other HTTP error, the last successfully retrieved data set should be utilized.
FILE FORMAT
All data in the file is serialized using JSON (JavaScript Object Notation). The parent JSON object and all child objects are written to the sellers.json file.
EXPIRATION
Consuming systems of /sellers.json should cache the files, but if they do they must periodically verify the cached copy is fresh before using its contents.
Standard HTTP cache-control mechanisms can be used by both origin server and robots to influence the caching of the /sellers.json file. Specifically consumers and replicators should take note of HTTP Expires header set by the origin server.
If no cache-control directives are present, consuming systems should default to an expiry of 7 days.
Implementation
Every advertising system listed in an ads.txt file and any advertising system that is referenced from a SupplyChain object node should publish a Sellers.json file at the following location:
http://{advertising_system_domain}/sellers.json
Object: Parent
The Parent object is the top-level object of a Sellers.json file. It is a container for all properties in a sellers.json file.
| Attribute | Type | Description |
|---|---|---|
| sellers | object array; required | The list of all Seller objects that are represented by the advertising system. All sellers must be included even if they are confidential. |
| identifiers | object array; optional | Array of Identifier objects associated with this advertising system. Examples could be TAG-Ids, Dun & Bradstreet business identifiers, or any custom identifier that a consuming advertising system might need. |
| contact_email | string; optional | An email address to use to contact the Advertising System for questions or inquiries about this file. |
| contact_address | string; optional | The business address of the advertising system. |
| version | string; required | The version of this spec, currently the only valid value is 1.0. |
| ext | object; optional | Placeholder for advertising-system specific extensions to this object. |
Sellers.json object: Identifier
An identifier is an arbitrary name/value pair that is used to communicate common values such as business identifiers, certification identifiers, or any other identifier that a consuming system might need to better interoperate with the seller.
Standard Identifiers are listed in the section Identifier Names below.
| Attribute | Type | Description |
|---|---|---|
| name | string; required | The description of the identifier |
| value | string; required | The value of the identifier |
Sellers.json object: Seller
The identification of the selling legal entity that is paid for inventory sold on behalf of seller_id.
It is invalid for a seller_id to represent multiple entities. Every seller_id must map to only a single entity that is paid for inventory transacted with that seller_id. It is valid for a selling entity to have multiple seller_ids within an advertising system.
| Attribute | Type | Description |
|---|---|---|
| seller_id | string; required | This is the same ID that appears in an ads.txt file and in the SupplyChain.nodes array sid property. In most cases will also appear in the Publisher.Id property of an OpenRTB request. |
| is_confidential | integer; optional, default 0 | Indicates whether the identity of the seller is confidential, where 0 = is not confidential and 1 = is confidential. |
| seller_type | string; required | An enumeration of the type of account, either PUBLISHER, INTERMEDIARY, or BOTH. A value of "PUBLISHER" indicates that the inventory sold through this account is on a site, app, or other medium owned by the named entity and the advertising system pays them directly. A value of “INTERMEDIARY" indicates that the inventory sold through this account is not owned by the named entity or the advertising system does not pay them directly. 'BOTH' indicates that both types of inventory are transacted by this seller. Note that this field should be treated as case insensitive when interpreting the data. |
| is_passthrough | integer; optional, default 0 | A passthrough seller is a facilitator of inventory from the upstream supplier to the consumer of the inventory. The upstream supplier and consumer must establish a business relationship with each other such that the upstream supplier has control of their account within the consumer’s platform. A value of 1 indicates the following: - This seller has an account control relationship with the downstream/consuming advertising system. - If this seller is the last link in a SupplyChain, the buying system has to have established an account control relationship with this seller to transact the seller’s inventory. - If this is not the last link in a SupplyChain than this seller should exist between two entities that have an account control relationship. A value of 0 indicates: - The downstream/consuming advertising system has no account control relationship with this seller. |
| name | string; required when is_confidential=0 | The name of the company (the legal entity) that is paid for inventory that is transacted under the given seller_id. Can be omitted only when is_confidential is set to 1. |
| domain | string; required if seller has a web presence and is_confidential=0 | The business domain name of the company (the legal entity) that is paid for inventory that is transacted under the given seller_id. When the seller_type property is set to INTERMEDIARY or BOTH, this should be the root domain name of the seller’s Sellers.json file. Can be omitted when is_confidential is set to 1 or when the seller doesn’t have a web presence. |
| comment | string; optional | Any helpful description for this inventory. It is useful for sellers that have multiple seller ids to describe what this seller_id represents. |
| ext | object; optional | Placeholder for advertising-system specific extensions to this object. |
Note that domain in sellers.json and SupplyChain are to be populated with only the root domain and not a full URL, much like ‘domain’ in OpenRTB’s Site object and the domain definition used for ads.txt. For the purposes of this document the “root domain” is defined as the “public suffix” plus one string in the name. Implementers should incorporate Public Suffix list [16] to derive the root domain.
Identifier Names
The following list defines standard identifiers that should be used in the identifier list.
| Name | Description |
|---|---|
| TAG-ID | Trustworthy Accountability Group ID |
| DUNS | Dun & Bradstreet DUNS Number |
Sample File Contents
{
"contact_email": "adops@advertisingsystem.com",
"contact_address": "Advertising System Inc., 101 Main Street, New York, NY 10101",
"version": "1.0",
"identifiers": [
{
"name": "TAG-ID",
"value": "28cb65e5bbc0bd5f"
}
],
"sellers": [
{
"seller_id": "1942009976",
"name": "Publisher1",
"domain": "publisher1.com",
"seller_type": "PUBLISHER”
},
{
"seller_id": "1397382429",
"name": "Exchange1",
"domain": "exchange1.com",
"seller_type": "INTERMEDIARY"
},
{
"seller_id": "20000000",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "PUBLISHER",
"comment": "NorthAmerica O&O inventory"
},
{
"seller_id": "20000001",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "PUBLISHER",
"comment": "APAC O&O inventory"
},
{
"seller_id": "20000002",
"name": "Seller And Intermediary, Inc",
"domain": "sellerandintermediary.com",
"seller_type": "INTERMEDIARY",
"comment": "Non O&O inventory"
},
{
"seller_id": "101010101",
"name": "Hybrid Seller",
"domain": "hybridseller.com",
"seller_type": "BOTH",
"comment": "Sells both O&O and other sellers' inventory"
},
{
"seller_id": "00000001",
"seller_type": "INTERMEDIARY",
"is_confidential": 1
},
{
"seller_id": "EB_0001",
"name": "Passthrough Publisher",
"domain": "passthroughpublisher.com",
"seller_type": "PUBLISHER",
"is_passthrough": 1, "comment": "direct buyer/seller of this inventory must establish an account relationship with Passthrough Publisher" }
]
}出处
InteractiveAdvertisingBureau/Supply-Chain-Validation ↗ · sellers-json.md
commit 7682963ae241 · 抓取 2026-10-29 · 已入库
CC-BY 3.0 · 文档自述:Sellers.json by OpenRTB Working Group
changelog 只有一行:1.0,2019 年 7 月首版