RTBlint

RTBlint

OpenRTB 检查器。 根据带版本的 IAB Tech Lab 规范快照验证 OpenRTB 2.x 竞价请求和竞价响应，版本范围从 2.0 到每月发布的 2.6 版本（目前最新为 2.6-202606）。

网站和在线体验场：rtblint.org

检查内容

• 格式错误的 JSON 和错误的顶层结构
• 必填字段，包括必填的非空数组
• 各版本目录中未知的对象和字段（ext 子树保持开放）
• 类型不匹配（字符串、整数、浮点数、布尔值、对象和数组）
• 文档中列出的枚举值，包括 AdCOM 列表和供应商范围（500+）
• 各版本中的弃用、迁移、移除和暂不可用字段
• 语义规则：site/app/dooh 互斥、imp 媒体类型是否存在、可跳过视频的依赖关系、时长互斥、响应中 seatbid/nbr 是否存在等
• 响应标记内容的一致性：bid.adm 内容与声明的 bid.mtype 是否匹配（native JSON 编码、VAST/DAAST 根节点、双重编码的载荷）
• 请求/响应交叉验证：提供发起请求后，会根据请求实际提供的内容检查每个竞价的 impid、mtype、adm 标记、dealid、seat 和币种
• JSON 方言：规范中的 JSON 类型会将 imp.secure 和 regs.coppa 等字段标记为整数，而 IAB OpenRTB protobuf 架构则将其中 28 个字段声明为 bool。两种编码在各自的传输方式中都正确，在另一种传输方式中则错误，因此调用方需声明所采用的编码方式
• 交换平台配置文件会针对所选供应商和流量方向应用已发布的请求、响应及配对约束。除非源规范明确要求，否则可选扩展仍为可选。配置文件包括 Google Authorized Buyers、Prebid Server、Microsoft Monetize、Magnite DV+ xAPI，以及买方、供应方和 SDK 的独立契约。有关来源、测试样例和限制，请参阅交换平台配置文件证据
• OpenRTB 以字符串或不透明 ext 形式携带的嵌套规范：Native Ads 1.2 标记（imp.native.request 和 native bid.adm，包括必填资源的配对）、GPP header 与 gpp_sid 和 TCF 2 结构、计费与流失 URL 上的 ${AUCTION_*} 宏、EID/SUA 结构、SKAdNetwork ext.skadn
• 隐私信号矛盾：regs.coppa / device.lmt / device.dnt / regs.gdpr 与同一载荷中的标识符、TCF Purpose 1 与设备存储 ID、US Privacy 中的拒绝出售选择与经过哈希处理的 EID、类似电子邮件地址的 user.id / site.page、DSA Transparency 字段是否存在。检查结果描述的是文档本身，不会给出法律结论。
• ARTF 信封和变更集，包括应用变更并重新验证结果

每项检查结果都包含稳定的规则 ID、严重程度、消息和 JSON 路径。

ARTF

ARTF，即 IAB Tech Lab Agentic Real Time Framework，会将 OpenRTB 负载放入 RTBRequest 信封交给 Agent，并接收 变更：由编排器逐一接受或拒绝的拟议更改。框架不会检查应用这些变更后竞价是否仍然有效，而且变更只有相对于其目标请求才有意义。

# The envelope, plus full OpenRTB validation of what it carries
rtblint validate --type artf-request rtb-request.json

# The mutation set against the auction it targets
rtblint validate --type artf-response --request rtb-request.json rtb-response.json

# Apply the mutations, revalidate, and report only what the mutations broke
rtblint validate --type artf-response --apply --request rtb-request.json rtb-response.json

三轮检查：

• 信封。 必需成员、lifecycle 是否与实际携带的负载相符、tmax 对于竞价期间调用是否合理、originator 和 applicable_intents 的枚举值，以及携带的竞价请求和竞价响应是否通过 protobuf JSON 验证。
• 变更。 响应 ID 回显扩展点请求 ID（而非竞价请求 ID），每个声明的意图都在 applicable_intents 中，操作和负载 oneof 成员与意图匹配，并且每个语义路径（/imp/{id}、/imp/{id}/pmp/deals/{id}、/user/data/segment、/seatbid/{seat}/bid/{id}）都能解析到竞价中携带的内容。报告指出 ADJUST_DEAL_MARGIN 没有可写入的 OpenRTB 字段，因为它确实没有。
• 应用后。 写入变更并重新验证结果，报告这些变更新引入的 OpenRTB 问题，同时过滤掉原本就存在的问题。报告 Agent 弄坏的内容，而不是收到时就已损坏的内容。

ARTF v1.0 文档和其 .proto 对同一变更使用了不同的词汇（文档使用 activateSegments 和 value: {IDsPayload: ...} 包装结构，而 .proto 使用 ACTIVATE_SEGMENTS 和顶层 oneof 成员）。根据文档编写的负载会被映射并报告为 artf.mutation.legacy_spec_encoding，而不会被当作未知内容忽略。

接入方式

接入方式	软件包	状态
Rust CLI	rtblint	可用
Rust 库	rtblint-core	可用
MCP 服务	rtblint-mcp	可用
Node（WASM）	npm 上的 rtblint-core	可用
GitHub Action	aleksUIX/rtblint	可用
Python	PyPI 上的 rtblint	尚未实现
Go	github.com/aleksUIX/rtblint/go	尚未实现

OpenRTB 3.0 通过其分层信封进行验证：传输对象（Openrtb、Request、Item、Deal、Source、Response、Seatbid、Bid）以及 item.spec（Placement）、bid.media（Ad）和 request.context 中的 AdCOM 1.0 领域对象。将 2.x 负载发送给 3.0 验证器时，会收到迁移诊断，而不是单纯的解析错误。2.6-202204 快照没有提取出的目录，因此会报告自身不受支持，而不会默默放行负载。请参阅 ROADMAP.md 了解后续计划，并参阅 CHANGELOG.md 查看发布历史。

CLI

cargo install rtblint

rtblint validate request.json
rtblint validate --type response response.json
rtblint validate --type response --request request.json response.json
rtblint validate --version 2.5 --format json request.json
rtblint validate --dialect proto-json grpc-bid-request.json
rtblint validate --profile google-ab google-bid-request.json
rtblint validate --profile prebid-server pbs-auction.json
rtblint validate --profile xandr xandr-bid-request.json
rtblint validate --profile magnite magnite-bid-request.json
rtblint validate --resolve --cache ./supply-cache request.json
rtblint validate --summary bids.ndjson
rtblint validate --batch --summary bids.ndjson
cat request.json | rtblint validate --stdin

--request 提供用于配对检查的原始竞价请求，包括批量验证。--dialect proto-json 选择 protobuf JSON 编码。--profile 选择供应商契约和流量方向。Xandr 检查面向竞价方的 Microsoft Monetize 流量；Magnite 检查 DV+ xAPI 扩展模型。提供可选的卖方、上下文和库存标识字段时，也会检查这些字段。特定账户和运行时的验收不在检查范围内。--resolve --cache <dir> 使用本地目录中的 sellers.json 和 ads.txt / app-ads.txt 检查 SupplyChain 跳转：

<dir>/sellers/<asi>/sellers.json
<dir>/ads/<site.domain>/ads.txt
<dir>/app-ads/<app.bundle>/app-ads.txt

Protobuf JSON 也支持 IAB 架构的原生对象选项： imp.native.request_native（requestNative）和 bid.adm_native （admNative）。其中的原生标志使用布尔值。字符串选项 request 和 adm 保留以 JSON 编码的 Native Ads 标记。每个 oneof 只提供一个 选项。原生资源仍会经过验证，并与请求中的必需资源配对。请参阅 IAB protobuf 架构。

不会获取任何内容；请自行填充缓存。--batch 从文件或 stdin 读取每行一个 JSON 对象并进行 lint 检查。对于捕获的流，--summary 会添加规则频次总计（仅查看直方图时使用 --summary bids.ndjson）。关于 --type artf-request 和 --type artf-response，请参阅 ARTF。

退出代码：0 表示有效，1 表示验证错误，2 表示用法或 I/O 错误。

GitHub Action

Action 位于此仓库中。请固定使用一个发布标签，以便 CI 下载对应的 CLI tarball：

- uses: aleksUIX/[email protected]
  with:
    path: fixtures/bid-request.json
    spec-version: 2.6-202505

version 选择 CLI 发布版本（auto 会跟随 Action 自身的 v* 标签）。spec-version 是 OpenRTB 快照版本。支持 Linux 和 macOS 运行器，以及 x86_64 和 aarch64。

Node

import { validate, validateResponse, validateResponseAgainstRequest } from "rtblint-core";

const report = validate(JSON.stringify(bidRequest), "2.6-202505");
if (!report.valid) {
  for (const issue of report.issues) {
    console.log(`[${issue.severity}] ${issue.path}: ${issue.message} (${issue.id})`);
  }
}

// Cross-validate a response against the request it answers.
const paired = validateResponseAgainstRequest(
  JSON.stringify(bidResponse),
  JSON.stringify(bidRequest)
);

对于 gRPC 竞价流负载和 ARTF：

import {
  validateDialect,
  validateProfile,
  validateArtfRequest,
  validateArtfResponseApplied,
  protoBoolDivergences,
} from "rtblint-core";

validateDialect(JSON.stringify(bidRequest), "proto-json");
validateProfile(JSON.stringify(bidRequest), "google-ab");
validateProfile(JSON.stringify(bidRequest), "prebid-server");
validateArtfRequest(JSON.stringify(rtbRequest));

// { result, application }: what the mutations broke, and the payloads they produced
const { result, application } = validateArtfResponseApplied(
  JSON.stringify(rtbResponse),
  JSON.stringify(rtbRequest)
);

protoBoolDivergences(); // the 28 fields the two schemas type differently

MCP 服务

托管的 Streamable HTTP（无需安装）：https://rtblint.org/mcp。Smithery 列表：aleksander/rtblint（与 vastlint 使用同一账户）。发送到托管端点的负载可能会被存储（已移除标识符），以改进规则；请参阅 rtblint.org/privacy。通过 stdio 运行的本地 rtblint-mcp 不会发送负载。

rtblint-mcp 也通过 stdio 使用 MCP。工具：validate_bid_request、validate_bid_response（可选的 bid_request 用于交叉验证）、validate_artf_request、validate_artf_response（apply 会写入变更并重新验证）、list_openrtb_versions、get_adcp_capabilities。验证工具接受可选的 dialect 和 profile 参数。

ARTF 工具是 Agent 在执行自身工作时调用的防护措施：先检查交给它的信封，再检查它即将提出的变更集，然后才交由编排器处理。

{
  "mcpServers": {
    "rtblint": { "url": "https://rtblint.org/mcp" }
  }
}

使用本地 stdio，而非托管端点：

{
  "mcpServers": {
    "rtblint": { "command": "rtblint-mcp" }
  }
}

Rust 库

use rtblint_core::{validate_bid_request_for_version, OpenRtbVersion};

let result = validate_bid_request_for_version(OpenRtbVersion::V2_6_202505, payload);
for issue in &result.issues {
    println!("{} {} {:?}", issue.severity, issue.id, issue.path);
}

validate_bid_request_with_profile 会在规范基础上应用交易平台配置（Profile::GoogleAuthorizedBuyers、Profile::PrebidServer）。validate_bid_request_with_dialect 用于选择规范 JSON 或 protobuf JSON。

已发布的配置 ID：spec、google-ab、prebid-server、xandr、magnite、dv360、index-exchange、index-exchange-seller、unity、vungle、bidswitch、bidswitch-supplier、inmobi、inmobi-supplier、mobilefuse、mobilefuse-sdk、applovin-alx、commerce-grid、digital-turbine、sovrn、equativ、equativ-supplier、triplelift-supplier、adform-handler、yandex-sdk-bidding、pubmatic-openwrap、pubmatic-openwrap-ctv。请选择匹配的方向，例如，买方 5.7 使用 bidswitch，供应商 1.1 使用 bidswitch-supplier。

关于检查的字段、支持的方向和明确列出的缺口，请参阅配置范围和来源依据。配对响应验证会将请求用作参考上下文；如需获取完整报告，请单独运行请求验证。

JSON 架构

schemas/ 为每个受跟踪版本保存一份 JSON Schema（draft 2020-12），涵盖两种载荷类型，生成所用的目录与验证器使用的目录相同。IAB Tech Lab 未为 2.6 或 3.0 发布 JSON Schema，因此这些架构构成了每个月度快照的机器可读契约：

https://rtblint.org/schemas/openrtb-2.6-202606-bid-request.schema.json
https://rtblint.org/schemas/openrtb-2.6-202606-bid-response.schema.json

它们涵盖结构、类型、必填字段、文档记录的取值集合以及 AdCOM 枚举列表。它们无法表达的是检查器额外提供的内容：已弃用和已迁移的路径、特定版本中移除的内容，以及语义规则。通过架构验证并不等同于运行检查器。

目录有任何更改后都要重新生成（如果两者不一致，CI 会失败）：

cargo run -p rtblint-core --example export_json_schemas

文档

除了本 README 外，rtblint.org 还提供参考资料：

• 诊断代码参考：包含每个稳定的问题 ID，每个 ID 都有对应页面，介绍其含义、重要性以及修复方法
• 带版本信息的规则目录：介绍每个 OpenRTB 版本新增、弃用、迁移或移除了哪些内容
• OpenRTB 版本：为每个受跟踪版本提供单独页面，涵盖 2.0 到 3.0
• 常见的 OpenRTB 错误和 在 CI 中进行验证
• 竞价请求剖析、竞价响应剖析以及 OpenRTB 常见问题

规范数据与来源

验证器基于从 IAB Tech Lab OpenRTB 规范中提取的结构化目录运行，其中包含对象名称、字段名称、类型表示法、枚举值集合和章节引用。目录不包含规范正文。方言表也以同样方式得出，即将这些目录与 IAB OpenRTB protobuf 架构声明的字段类型进行比较。RTBlint 与 IAB Tech Lab 无关联，也未获得其认可。归属信息请参阅 NOTICE。

供应链

OpenSSF Scorecard 每周运行并发布公开评分。Dependabot 覆盖 Cargo、npm 和 GitHub Actions。CodeQL 会在每次推送和 PR 时扫描 Rust 与 JavaScript。

三个 cargo-fuzz 目标（validate、validate_response、validate_artf）会在每次 CI 推送时各运行 30 秒。验证器不得因任意输入而 panic。

cargo +nightly fuzz run validate -- -max_total_time=60

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。

研究

Sekowski, A.（2026）。OpenRTB 的可机器检查程度如何？对实时广告交易协议规范性内容的分类研究。预印本。 DOI：10.13140/RG.2.2.27937.57448

Sekowski, A.（2026）。衡量客户端标头竞价中的 OpenRTB 方言。预印本。 DOI：10.13140/RG.2.2.26572.78720

Sekowski, A.（2026）。CTV 广告欺诈为何屡禁不止：对联网电视供应链可验证性的分析。预印本。 ResearchGate。字段清单摘自此目录。相关资料：github.com/aleksUIX/ctv-verification-gap。