ORTB
…
Volume navigation

Specification overview

Entry point of the supply chain volume: the four groups of standards, chapter by chapter. Each chapter renders the official specification text verbatim, alongside the field tables, variable tables, official examples and CASE walkthroughs extracted from it.

6 chapters · live 6 · draft 0 · planned 0

On this page

Group

Declaration files

2 chapters
  • Authorized Digital Sellers (ads.txt) 1.1: a publisher declares, under its own domain, the advertising systems and account IDs authorized to sell its inventory. Covers the four-field record syntax, the five variable declarations, referral and caching rules, and the nine official examples.

    • Access method: path, Content-Type, redirect and status-code handling
    • File format and the four record fields
    • Syntax definition: comments, the record, extension fields
    • Variable declaration records and the five supported variables
    • Expiration and caching
    • The nine official examples
    • Implementer's notes and version
  • Authorized Sellers for Apps (app-ads.txt): the extension of ads.txt to software distributed through app stores, where the declaration lives on the developer's website rather than in the app. Covers developer URL canonicalization and the official Appendix A/B test cases.

    • The four parties: app developers, ad networks and sell-side platforms, app stores, authorized seller verifiers
    • Providing and changing the developer website URL in store listings
    • Structured app information on the store side
    • The verifier's crawl flow and canonicalization
    • Developer URL canonicalization test cases (Appendix A)
    • Developer URL to app-ads.txt path test cases (Appendix B)
    • Limitations and constraints

Identity disclosure

1 chapters
  • An advertising system publishes, under its own root domain, the identities of the sellers it represents and their identifiers within its system, letting a buyer discover the final seller and every intermediary in a bid request. Covers the Parent / Identifier / Seller objects, the standard identifier names and the official sample file.

    • Access method and file format
    • Expiration and caching
    • Implementation: which advertising systems must publish the file
    • Fields of the Parent / Identifier / Seller objects
    • Standard identifier names
    • The official sample file (with its JSON defect noted)

In-request carriage

1 chapters
  • The OpenRTB SupplyChain object (schain): lets a buyer see every party selling or reselling a given bid request. Covers the node definition, the SupplyChain and SupplyChainNode objects, the carriage path per OpenRTB version, the construction rules on resale, and the URL-parameter serialization for non-OpenRTB requests with the six official paired examples.

    • Node definition: the semantics and uniqueness constraints of asi and sid
    • Fields of the SupplyChain and SupplyChainNode objects
    • Carriage path per OpenRTB version
    • Construction rules on resale and at origination
    • Valid and invalid domain forms
    • URL serialization for non-OpenRTB requests: format, property order, encoding rules
    • The six official object-to-string paired examples

Implementation & scenarios

1 chapters
  • The two official guides: the inventory-sharing guide covers CTV / vMVPD cases where several entities hold rights to sell ad space within one app (CASE A, B.1, B.2, C), and the implementation guidance ties ads.txt DIRECT / RESELLER values directly to sellers.json, with seven CASEs laid out in five columns (bid request, ads.txt, sellers.json, validation, answer).

    • Background and scope: inventory sharing in scope, revenue sharing out of scope
    • Updates to the ads.txt and app-ads.txt standards
    • Facts and file contents of inventory-sharing CASE A, B.1, B.2, C
    • The five-column walkthrough of implementation CASE A–G
    • The interlock rules in the Validation column (the source of this site's relation list)
    • Implementation guidelines for publishers, exchanges and DSPs

Specification and guide registry

The official source file, baseline commit, checksum and ingestion statistics for each volume. The checksums detect upstream changes: once a source file differs, npm run supplychain:gen and the data integrity tests fail.

StandardKindVersionReleasedOfficial source fileIngested
ads.txt (Authorized Digital Sellers)Specification1.12022-07vendor/iab-supplychain/ads.txt v1.1.mdsha256: de5544b9b9bfsections 44 · fields 4 · variables 5 · examples 9 · exampleFiles 14
app-ads.txt (Authorized Sellers for Apps)app-ads.txt.md states no version number and no release date anywhere in its text. The repository's first commit for the file (2026-03-25) is when it entered the Supply-Chain-Validation repository, which has nothing to do with the specification's release, so it is not used as a release date.Specification——vendor/iab-supplychain/app-ads.txt.mdsha256: f8ad57c8b4a6sections 34 · canonicalizationCases 18 · urlMappingCases 6
sellers.jsonSpecification1.0July 2019vendor/iab-supplychain/sellers-json.mdsha256: da90706a38d7sections 13 · objects 3 · fields 16
OpenRTB SupplyChain objectsupplychainobject.md carries no version stamp and no release date. Its two mentions of “version 1.0 of the spec / of SupplyChain” are example values for the ver field, not a version declaration for the document. The file was first committed to the repository on 2019-04-11 and last on 2022-03-24; those dates evidence file changes only and are not used as a specification release date.Specification——vendor/iab-openrtb3/supplychainobject.mdsha256: 95f94bcf5bf5sections 22 · fields 11
ads.txt & app-ads.txt: Guidance for Inventory SharingOfficial guide——vendor/iab-supplychain/Explainer Guide.mdsha256: 6a036746d233cases 5
Ads.txt Implementation GuidanceOfficial guide——vendor/iab-supplychain/Implementation Guidance.mdsha256: fe92b8850fa8cases 7 · validationRules 28
  • InteractiveAdvertisingBureau/Supply-Chain-Validation ↗ · main @ 7682963ae241 · Fetched 2026-10-29

    vendor/iab-supplychain · The repository has no root LICENSE file. ads.txt self-declares CC-BY 3.0 as "Ads.txt by Programmatic Supply Chain Working Group", and app-ads.txt and sellers.json each declare CC-BY 3.0 in their own headers; the two guides have no licence section, and the CC-BY 3.0 line in the repository README names Ads.txt only.

    The repository was created on 2026-03-25 and then renamed from ads.txt-app-ads.txt to Supply-Chain-Validation; the table-of-contents anchors and image links in the body still carry the old repository path and rely on GitHub's 301 redirect to keep working.

  • InteractiveAdvertisingBureau/openrtb ↗ · main @ f3fb64bb9e5f · Fetched 2026-10-29

    vendor/iab-openrtb3 · The repository has no root LICENSE file; its README states CC-BY 3.0 for the OpenRTB Specification, but supplychainobject.md itself has no licence section.

    The OpenRTB 3.0 repository, distinct from the openrtb2.x repository this site already vendors; this module takes only supplychainobject.md from it.

Defects found in the official sources

Defects in the official documents found during ingestion, each with file-level and line-level evidence. Nothing is repaired: samples stay exactly as the official source has them, and a parsable copy is labelled separately so the two are never mixed.

16 entries

  • supplychainobject.md · Examples (multiple hops, all properties supplied)

    inconsistent value

    The rid in the serialized example disagrees with the SupplyChain object printed above it: the object says bid-request-2 while the serialized string says bid-request2 (a missing hyphen). This site records both as-is, and the round-trip test must treat this as a known official defect rather than a parsing error of its own.

    Evidence: vendor/iab-openrtb3/supplychainobject.md:395 · vendor/iab-openrtb3/supplychainobject.md:402

  • supplychainobject.md · Examples (the four BidRequest samples)

    not valid JSON

    None of the four BidRequest samples is valid JSON: a comma is missing after the closing brace of the app object, and the second sample is also missing one after the sid line; the fences carry no language tag either. All four also place schain under source.ext.schain (the 2.5 carriage path) while the same document's prose states that 2.6 and later should use source.schain — the examples contradict the text.

    Evidence: vendor/iab-openrtb3/supplychainobject.md:143-253 · vendor/iab-openrtb3/supplychainobject.md:28

  • Implementation Guidance.md · the CASE A five-column table

    not valid JSON

    The sellers.json column of CASE A writes seller_type as "Publisher", which does not match the sellers.json enumeration PUBLISHER/INTERMEDIARY/BOTH literally (the spec says the field is case insensitive, so it still works); the same Bid Request column contains the official typo placecment. The fence is tagged ```json but the content includes prose, so it is not valid JSON.

    Evidence: vendor/iab-supplychain/Implementation Guidance.md:71 · vendor/iab-supplychain/Implementation Guidance.md:112

  • Both the Supply-Chain-Validation and openrtb repositories

    licence declaration mismatch

    Neither repository has a root LICENSE file, and the licence declarations do not cover all documents: ads.txt self-declares as "Ads.txt by Programmatic Supply Chain Working Group", app-ads.txt as "OpenRTB Specification the IAB Tech Lab", and sellers.json as "Sellers.json by OpenRTB Working Group" — three different attributing bodies — while the Explainer Guide, the Implementation Guidance and supplychainobject.md have no licence section at all and can only be inferred from their repository READMEs, and the Supply-Chain-Validation README line names Ads.txt only. This site records what each document states, does not extend a README's attribution to documents that state nothing, and does not supply a repository-level licence on the official body's behalf.

    Evidence: vendor/iab-supplychain/ads.txt v1.1.md:15-17 · vendor/iab-supplychain/app-ads.txt.md:33-35 · vendor/iab-supplychain/sellers-json.md:13-15 · vendor/iab-supplychain/README.md:15-17 · vendor/iab-openrtb3/README.md:45-46

  • The Supply-Chain-Validation repository

    stale internal links

    The repository was created on 2026-03-25 and renamed from ads.txt-app-ads.txt, but the table-of-contents anchors in both guides still hard-code the old repository path (github.com/InteractiveAdvertisingBureau/ads.txt-app-ads.txt/blob/main/…). GitHub 301-redirects renamed repositories, so the links do not break, yet the path names are stale. This site never ingests a table of contents — only the body text.

    Evidence: vendor/iab-supplychain/Explainer Guide.md:5-21 · vendor/iab-supplychain/Implementation Guidance.md:5-9

  • ads.txt v1.1.md · §4.1 / §4.2

    inconsistent example format

    Of the nine examples in §4, 4.1 and 4.2 write the ads.txt contents as inline code rather than a fenced block (the other seven use fences). The ingester has to recognize both, or the file contents of these two examples would be lost.

    Evidence: vendor/iab-supplychain/ads.txt v1.1.md:230 · vendor/iab-supplychain/ads.txt v1.1.md:238

  • supplychainobject.md · the domain-form examples

    unlabelled examples

    The Valid / Invalid examples are bare domain lines with no fence and no list marker, formally indistinguishable from the surrounding prose. Ingestion classifies them by a state machine keyed on the preceding "Valid/Invalid examples:" label; if the official layout of this passage changes the classification breaks, which the count assertions in __tests__ guard against.

    Evidence: vendor/iab-openrtb3/supplychainobject.md:116-122

  • ads.txt v1.1.md · the BEFORE passage of §4.6

    malformed code fence

    One code fence opens with content on the same line (```# ads.txt file for Programmer A:) instead of the standard fence-alone opening. Starting collection from the next line would drop that comment line, so the ingester handles this form explicitly.

    Evidence: vendor/iab-supplychain/ads.txt v1.1.md:331

  • ads.txt v1.1.md · §3.5.1 MANAGERDOMAIN

    missing sentence terminator

    In the MANAGERDOMAIN description there is no full stop after “Syntax of the domain is [PSL+1 domain, required], [ISO 3166-1 alpha-2 country code, optional, blank=global]”, which runs straight into “This variable should only be used…”. The value syntax is therefore extracted by closing on the bracket groups rather than on a sentence terminator, otherwise the following sentence would be swallowed with it.

    Evidence: vendor/iab-supplychain/ads.txt v1.1.md:210

  • Explainer Guide.md · the CASE A footnote

    unbalanced markup

    The Note paragraph at the end of CASE A has an unclosed bold marker (**Note: … as it is optional.* closes with a single *), so paired replacement leaves stray ** behind. stripMd gained a fallback that flattens leftover **, otherwise that paragraph would render with its markup symbols visible.

    Evidence: vendor/iab-supplychain/Explainer Guide.md:113

  • app-ads.txt.md · Appendix A

    merged lines

    The official text puts 2 test cases on a single line (a missing line break); ingestion splits them at URL boundaries: https://another.subdomain.example.co.uk/test / https://subdomain.www.example.co.uk/test

    Evidence: vendor/iab-supplychain/app-ads.txt.md

  • app-ads.txt.md · Appendix B

    glued bullet

    The official text joins the fallback item to the end of the previous line with a ● instead of a line break; ingestion splits it into its own entry: Test developer URL with multiple subdomains

    Evidence: vendor/iab-supplychain/app-ads.txt.md

  • sellers-json.md · Sample File Contents

    not valid JSON

    The official sample is not valid JSON: the closing quote of seller_type is a curly quote U+201D ("PUBLISHER”). This site records the text as-is and keeps a separate parsable copy in which only that curly quote is replaced. Original error: Bad control character in string literal in JSON at position 339 (line 16 column 27)

    Evidence: vendor/iab-supplychain/sellers-json.md:172

  • Implementation Guidance.md · the CASE A–G diagrams

    stale image path

    All 7 CASE diagrams link to the pre-rename ads.txt-app-ads.txt repository, each pinned to a different historical commit (7 distinct commits). GitHub 301-redirects renamed repositories so the links do not break, but both the path names and the commits are stale. The Explainer Guide contains no diagrams at all. This site records the official URLs as-is and does not mirror them into public/ — the same handling as the SIMID module.

    Evidence: vendor/iab-supplychain/Implementation Guidance.md:60 · vendor/iab-supplychain/Implementation Guidance.md:149 · vendor/iab-supplychain/Implementation Guidance.md:255 · vendor/iab-supplychain/Implementation Guidance.md:376 · vendor/iab-supplychain/Implementation Guidance.md:470 · vendor/iab-supplychain/Implementation Guidance.md:588 · vendor/iab-supplychain/Implementation Guidance.md:679

  • Implementation Guidance.md · the Validation column of CASE A–G

    inconsistent wording

    The Validation column of all seven CASEs states the same four rules (the equality and inequality branches of sellers.domain against OWNERDOMAIN / MANAGERDOMAIN / MANAGERDOMAIN+GEO), but the official wording is not uniform: the domain placeholder is A=publisher.com B=publisher.com C=publisher.com D=site.com E=site.com F=publisher.com G=publisher.com, and the fourth conclusion in CASE E stops at "THEN seller is reseller", omitting the "of inventory" the other six have. This site normalizes the rules by shape into a single source, records the wording differences as they are, and does not harmonize the official wording on its behalf.

    Evidence: vendor/iab-supplychain/Implementation Guidance.md:120-135 · vendor/iab-supplychain/Implementation Guidance.md:441-456 · vendor/iab-supplychain/Implementation Guidance.md:558-573

  • Implementation Guidance.md · the Bid Request and Answer columns of CASE G

    inconsistent value

    CASE G narrates inventory on site.com sold by xyzmedia.com (sid xyz) through exchange.com (sid 1240), and its ads.txt column reads xyzmedia.com, 123xyz, DIRECT; yet the first node (sid 123xyz) in the Bid Request column has asi miswritten as "ecxhange.co m", which per the ads.txt line and the narrative should be xyzmedia.com — the first node points at the wrong advertising system. The second node (sid 1240) has asi "ecxhange.com", a misspelling of exchange.com (the same ecxhange misspelling also appears in the Bid Request columns of CASE B/C/F). The Answer column misspells XYZ Media as "ZYZ Media". This site records the text as-is and does not correct it on the official body's behalf; these defects mean CASE G's literal schain does not satisfy the 'downstream sellers.domain = upstream asi' entity continuity, so the ads.txt column and the narrative must be taken as authoritative when citing this example.

    Evidence: vendor/iab-supplychain/Implementation Guidance.md:691-709 · vendor/iab-supplychain/Implementation Guidance.md:725-726 · vendor/iab-supplychain/Implementation Guidance.md:778

Ingestion notes

ads.txt 1.1, app-ads.txt, sellers.json 1.0 and the two implementation guides are vendored from the official IAB Tech Lab repository Supply-Chain-Validation (previously named ads.txt-app-ads.txt); the OpenRTB SupplyChain object specification is vendored from supplychainobject.md in the official openrtb (3.0) repository, which is a different repository from the openrtb2.x one this site already vendors. ads.cert is deliberately not ingested: only a 714-byte redirect stub remains in the openrtb repository, the 1.0 beta was never released as a standard, and v2.0 has been published on a separate site independent of OpenRTB. The SupplyChainPlus repository is likewise not ingested — it holds only a README and one CRC32C script, with no specification text.

The content is faithful to the official specification texts in the IAB Tech Lab repositories Supply-Chain-Validation and openrtb (CC-BY 3.0, attributed per document header), ingested by scripts/gen-supplychain-spec.mjs: recorded verbatim, not rewritten, not translated, and with defects in the official sources not repaired. Each defect is logged in the findings of PROVENANCE.json and shown on the relevant chapter. The baseline commit and fetch date are in the sources section of each chapter.