Guides

OpenRTB validation in CI

Install the CLI with the GitHub Action or cargo install rtblint, run rtblint validate over your bid request fixtures, and fail the build on a nonzero exit code. That is the whole idea. The rest of this guide covers exit codes, JSON output, a GitHub Actions example, and why you should pin a spec snapshot.

Why validate fixtures in CI at all

Most bidder and SSP codebases carry a directory of bid request fixtures: golden files for integration tests, sample payloads for partners, request builders exercised in unit tests. Those files rot. Someone hand-edits one and typos a field name. A partner upgrades from 2.5 to a 2.6 snapshot and suddenly regs.ext.gdpr should be regs.gdpr and imp.video.placement should be plcmt. The 2.6 line itself moves: the tracked snapshots run from 2.6-202210 to 2.6-202606, and fields like regs.gpp (added in 2.6-202211) appear along the way.

The failure mode is silent. A request that drifted from the spec usually does not throw anywhere; the strictest partner just stops bidding on it, and you find out weeks later as a revenue dip. See OpenRTB no-bid reasons for how little signal comes back. A validation step in CI turns that silent drift into a red build at the pull request that introduced it.

Exit codes and JSON output

rtblint validate exits 0 when the request is valid (warnings are allowed), 1 when it has spec errors, and 2 on usage or I/O problems. That is enough for a plain shell gate. When you want to inspect or filter findings, --format json emits a machine-readable report:

{
  "version": "2.6-202606",
  "valid": false,
  "issues": [
    {
      "id": "openrtb.field.moved",
      "severity": "error",
      "message": "regs.ext.gdpr moved in OpenRTB 2.6-202606; use regs.gdpr.",
      "path": "regs.ext.gdpr"
    }
  ]
}

Each issue carries a stable rule id, a severity, a message, and the JSON path. The diagnostic reference documents the IDs.

GitHub Actions example

name: Validate OpenRTB fixtures
on: [push, pull_request]
permissions:
  contents: read
jobs:
  validate-fixtures:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate bid request fixtures
        uses: aleksUIX/rtblint@v0.13.4
        with:
          path: fixtures/bid-request.json
          version: v0.13.4
          spec-version: 2.6-202606

This example pins the action and CLI release to v0.13.4. Save the workflow as .github/workflows/validate-openrtb.yml. spec-version is the OpenRTB snapshot; leave it off to use the latest tracked 2.6. For multiple fixtures, use a workflow matrix with one path per entry. The same CLI contract works in GitLab CI, Buildkite, or a Makefile: exit 0 valid, 1 spec errors, 2 usage or I/O. cargo install rtblint is still available when you are not on GitHub Actions.

Validating piped payloads

--stdin reads the request from the pipe instead of a file, which is handy when fixtures are generated, templated, or extracted from logs on the fly:

# validate a generated request without touching disk
./gen-request --seat 42 | rtblint validate --stdin --format json

# spot-check a request pulled from a log line
jq -c '.request' sampled.log | head -1 | rtblint validate --stdin

Pin a spec snapshot

Without --version, RTBlint validates against the latest tracked 2.6 snapshot, which changes when a new spec release lands. In CI that means an RTBlint upgrade can move the goalposts mid-week. Pin the snapshot instead:

rtblint validate request.json --version 2.6-202606

Now a spec upgrade is a deliberate one-line diff that reviewers can see, run, and discuss, exactly like bumping a dependency. When you do bump it, the new findings (a freshly deprecated field, a moved path) arrive in one reviewable batch.

Gating on rule IDs

Exit-code gating treats every error the same. With JSON output you can be more selective. This policy temporarily allows only openrtb.field.movedamong errors. Save the following as scripts/check-openrtb.sh. It requires the RTBlint CLI and jq on PATH:

#!/usr/bin/env bash
set -euo pipefail

fixture="${1:?Usage: bash scripts/check-openrtb.sh path/to/request.json}"
report="$(mktemp)"
trap 'rm -f "$report"' EXIT

# Exit 1 is a validation verdict. Let the rule policy below decide.
status=0
rtblint validate "$fixture" --version 2.6-202606 --format json >"$report" || status=$?
case "$status" in
  0|1) ;;
  *) echo "RTBlint failed before policy evaluation (exit $status)." >&2; exit "$status" ;;
esac

# Temporarily allow moved fields. Reject other errors and malformed reports.
jq -e '
  type == "object"
  and (.valid | type == "boolean")
  and (.issues | type == "array")
  and all(.issues[];
    (.id | type == "string")
    and (.severity == "error" or .severity == "warning" or .severity == "info"))
  and (.valid or any(.issues[]; .severity == "error"))
  and ([.issues[] | select(.severity == "error"
    and .id != "openrtb.field.moved")] | length == 0)
' "$report"

Run it with a fixture path:

bash scripts/check-openrtb.sh fixtures/bid-request.json

The CLI can exit 1 for an allowed moved-field error, so the script captures that status before applying the policy. Exit 2 and unexpected failures stop the gate immediately. Missing or malformed reports also fail. Warnings pass this policy.

Rule IDs such as openrtb.payload.invalid_json, openrtb.field.undefined, openrtb.field.deprecated, and openrtb.field.moved are stable, so allowlists survive upgrades. Keep the allowlist short and dated; it is a migration tool, not a mute button.

FAQ

Does RTBlint need network access in CI?

Validation itself is offline. The GitHub Action downloads a CLI tarball once from GitHub Releases. cargo install also needs network, and you can cache either.

How fast is it? Will it slow the pipeline down?

The validator is Rust operating on parsed JSON, and a single bid request validates in well under a millisecond of CPU time. Even a fixtures directory with thousands of requests finishes in seconds. The Action download is a small tarball; cargo install dominates until you cache it.

Validate it

Try a fixture in the bid request tester first to see what the findings look like, then wire the same checks into CI with the CLI. If you are new to the request format itself, start with the bid request reference and the guide on validating a bid request.