IAB Content Taxonomy 3.0 vs 3.1: what changed and what to do about it
Version 3.1 is a small release. For most buyers of category data, it changes very little. This page shows the differences we found in the published files, how IAB versioning works, and a migration checklist for teams coming from 3.0 or from the older 2.x line.
Version 3.0
- Released June 2022
- 703 category rows
- 36 top-level entries
- Shipped with a Descriptive Vectors file
- Not backward compatible with 2.x
Version 3.1
- Released December 2024
- 704 category rows
- Thriller added under Genres
- Communication row listed at top level
- 3.0 IDs kept
The differences between 3.0 and 3.1
IAB Tech Lab describes 3.1 as a minor update to the genres list, released alongside guidance on CTV genres. When we compared the two published category files, these were the differences that matter to data buyers.
Thriller genre
A new tier 2 row, Thriller, with ID 700, sits under the Genres branch. Genres describe programme style rather than topic, so this addition mainly affects video, CTV and audio inventory.
Before 3.1, thriller content had to be tagged with a nearby genre such as Mystery or Action/Adventure.
Communication
In 3.0, Communication (ID 80DV8O) is a tier 4 row under Technology & Computing > Computing > Computer Software and Applications.
In the published 3.1 file the same ID appears with no parent and its own name as tier 1. Reports that roll this row up to Technology & Computing will see it move.
IDs and names
The 3.0 IDs we checked carry the same names and paths in 3.1. A list of 3.0 IDs therefore stays valid, which is the key point for anyone storing category codes.
File layout
Both files use the same columns: Unique ID, Parent, Name, four tier columns and an extension column that carries flags such as SCD for sensitive category data.
Always run your own diff on Unique ID before relying on any summary, including this one. A simple join of the two files on ID, comparing Parent and the tier columns, takes minutes and shows every row that moved.
How IAB taxonomy versioning works
The numbering tells you how much work an upgrade will be. IAB Tech Lab publishes a versioning policy for its taxonomies; in plain terms it works like this.
Breaking changes. Rows can be removed or restructured, and the new tree should not be mixed with the old one in the same list.
Improvements that should not break existing integrations, such as new rows. Existing IDs keep working.
Mistakes found in a release are corrected in the next release rather than by silently editing the published file.
Where 3.1 sits in the full timeline
| Version | Released | Status for buyers | What it means today |
|---|---|---|---|
| 1.0 | Original list | Deprecated since 2020 | Still seen in old bid streams; convert before analysis |
| 2.0 | November 2017 | Being phased out | Common in legacy systems and older contracts |
| 2.1 | October 2020 | Being phased out | Widely deployed; many platforms still accept it |
| 2.2 | December 2020 | Being phased out | Last of the 2.x line |
| 3.0 | June 2022 | Current major version | Restructured tree plus Descriptive Vectors |
| 3.1 | December 2024 | Current release | 3.0 plus a genre addition; safe default for new work |
A full walk through the structure and every top-level category is on our IAB Content Taxonomy 3.1 category list and structure page.
Who is affected by the 3.1 update
Because the update touches genres and one software row, the impact depends on what you buy and how you report.
CTV and video buyers
Most affected. Thriller is now a target or exclusion option in its own right, and CTV genre guidance was published at the same time.
Audio and podcast teams
Moderately affected. Genre rows are shared across media, so audio inventory can carry the new genre too.
Web and domain buyers
Barely affected. Websites are labelled mostly by topic, and the topic branches did not change in a way that alters domain lists.
Analysts and reporting
Check roll-ups. If your reports group Communication under Technology & Computing, decide which view you want and apply it consistently.
Migration checklist: moving from 3.0 to 3.1
For most teams this is an afternoon of work. The steps below keep it tidy and auditable.
- Load both files side by side. Join them on Unique ID and list every row whose Parent or tier columns differ. Expect a very short list.
- Update your parent map. If you keep a child to tier 1 lookup for reporting, regenerate it from the 3.1 file so the Communication row lands where the new file puts it.
- Decide on Thriller. Video and audio campaigns that previously approximated thrillers with Mystery or Action/Adventure can now target or exclude the exact genre.
- Change the declared version. Wherever you exchange category lists, record 3.1 as the taxonomy version so partners read the codes correctly.
- Leave stored 3.0 codes alone. They remain valid. Rewriting historic data adds risk without benefit.
- Re-run a sample report. Compare a month of results under the old and new roll-ups to confirm totals match apart from the expected moves.
- Tell your partners. A short note to your SSPs, DSPs or data clients avoids confusion when a new genre code starts appearing.
The bigger move: from 2.x to 3.x
Most of the real migration work we see is not 3.0 to 3.1 but 2.x to 3.x. Version 3.0 reorganised several top-level branches. The table compares the two trees using the category files in our own data.
| In 2.x | Where it lives in 3.x | Migration effort |
|---|---|---|
| Events and Attractions | Split into Attractions (places to visit) and Events (shows, expos, conventions). Holidays and Personal Celebrations & Life Events became their own top-level entries. | High |
| Movies | Entertainment → Movies, with film styles moved to the shared Genres branch | Medium |
| Television | Entertainment → Television, with show styles such as Reality TV and Soap Opera in Genres | Medium |
| Music and Audio | Entertainment → Music for the subject; radio formats such as Talk Radio and Sports Radio in Genres | High |
| News and Politics | Politics, Crime, Disasters and Law became top-level entries; Weather moved under Science. Local, national and international news have no direct topic row. | High |
| Technology & Computing | Same top-level name, with new branches such as Artificial Intelligence, Robotics and Augmented Reality | Low |
| Video Gaming | Same name and main branches; more rows in 3.x | Low |
| Most other branches | Names carried over, for example Automotive, Travel, Pets, Real Estate, Personal Finance | Low |
| Not in 2.x as a branch | New in 3.x: Sensitive Topics, Genres, War and Conflicts, Holidays | Medium |
Practical rules for a 2.x to 3.x migration
Map by meaning, not by name
Some names exist in both trees but sit in different places. Map each 2.x ID you use to the 3.x ID that describes the same subject, and record cases where one row became two.
Separate topic from format
2.x mixed subject and style in rows like "Comedy Movies". In 3.x you express that as Entertainment > Movies plus the Comedy genre, so a single 2.x code can become a pair.
Rebuild news targeting
Because local and national news are no longer topic rows, news campaigns in 3.x usually combine subject rows with a curated domain list. Our news domains list exists for exactly this job.
Run both columns during the switch
Data that carries both a v2 and a v3 label per domain lets you compare old and new segments before you cut over, which is why our database keeps both. See dual taxonomy categorization.
A worked example: one campaign, three taxonomy versions
Here is how the same brief, "reach people reading or watching comedy about food and travel", is expressed in each version. It shows why the 2.x to 3.x step is real work and the 3.0 to 3.1 step is not.
| Version | How the targeting is written | What the team had to do |
|---|---|---|
| 2.x | Food & Drink rows, Travel rows, plus media rows such as Comedy Movies and Comedy TV | Pick each media-specific comedy row separately, because subject and style were mixed in one code |
| 3.0 | Food & Drink and Travel subject rows, combined with the shared Comedy row under Genres | Rebuild the segment as subject plus genre; one genre code now covers film, TV and audio |
| 3.1 | Exactly the same codes as in 3.0 | Nothing, unless the brief also wanted thrillers, which can now be added with one code |
For web inventory the picture is simpler still. Domains are labelled by subject, so a domain list for food and travel sites is identical under 3.0 and 3.1.
Common mistakes during a taxonomy upgrade
These are the problems that most often turn a small upgrade into a support ticket. All of them are easy to avoid once you know to look.
Matching on names instead of IDs
Several names appear in more than one branch, for example genre rows that share a word with a subject row. A join on name can attach the wrong parent. Always join on Unique ID.
Forgetting the declared version
Sending 3.x codes while the receiving system still expects 2.x makes codes resolve to the wrong subject or to nothing at all. Declare the version wherever the exchange format allows it.
Treating genres as topics
A site about horror films is about Entertainment > Movies; Horror is the style of the content. Teams that put genres into web targeting often end up with very small or very odd lists.
Blocking whole branches
Excluding all of Sensitive Topics or all of a news-related branch can remove large amounts of safe, valuable inventory. Choose specific rows and review the result.
Rewriting history
Converting years of stored reports to new codes rarely pays off. Keep historic data on the version it was collected under and convert only at the reporting layer.
Skipping the sample check
A quick look at a few dozen domains or pages after the switch catches most surprises. Our domain checker makes that a five minute job.
Quality checks after you switch
Run these checks once, right after the change, and keep the results with your project notes. They give you evidence that nothing broke.
| Check | How to run it | What a good result looks like |
|---|---|---|
| Unknown codes | Count category codes in your data that do not exist in the new file | Zero for 3.0 to 3.1; a known, mapped set for 2.x to 3.x |
| Roll-up totals | Compare tier 1 totals for one month under the old and new parent maps | Equal, except for the rows you know moved |
| Segment size | Count domains or impressions in each live segment before and after | Within a few percent unless you changed the definition on purpose |
| Exclusion coverage | Test a list of sites you must never appear on against the new exclusion rules | Every test site still blocked |
| Partner readback | Ask one partner to confirm they read your new codes and version correctly | Same labels on both sides |
Questions to ask any category data supplier
- Which IAB versions are delivered, and are they in separate columns or mixed in one field?
- How deep do the labels go? Tier 2 only, or down to tier 3 and tier 4 where the content supports it?
- Does a domain carry one label or several, and are several labels ranked by how much of the site they describe?
- How often is the data refreshed, and how are newly registered domains handled?
- Can the data run inside your own systems, or does every lookup leave your network?
What this means for our data
| Question | Answer |
|---|---|
| Which IAB version is in the file? | An IAB version 3 column with 703 categories down to tier 4, plus a separate IAB v2 column. |
| Can 3.1 systems read it? | Yes. 3.1 keeps the 3.0 IDs, so our v3 codes resolve in a 3.1 lookup without remapping. |
| Does the Thriller genre matter for domains? | Rarely. Genres describe programme style, and domain labels describe what a site is mainly about. |
| How do I check a domain? | Use the domain category lookup to see its IAB and filtering categories. |
| Where are the category lists? | The taxonomy downloads page has JSON and CSV exports of both IAB lists, and IAB category documentation explains the columns. |
| How fresh are the labels? | Newly registered domains are categorized daily and rechecked after a week and a month; other domains are refreshed monthly. |
Key terms in one place
The permanent key of a category row. It is what systems store and exchange, while names are for people reading reports.
The ID of the row one level up. Following parents from any leaf leads back to its tier 1 subject, which is how roll-up reports are built.
A shared branch describing programme style, used across film, TV, audio and CTV. It sits next to the subject branches rather than inside them.
Non-topic attributes released with 3.0 in a separate file, so that subject rows stay about subject matter only.
A marker in the extension column for rows touching sensitive category data. It signals extra care in targeting and privacy review.
The taxonomy version stated alongside a list of codes, so the receiving system resolves each code against the right tree.
Questions buyers ask about 3.0 and 3.1
Do I need to remap my data from 3.0 to 3.1?
Usually not. The 3.0 IDs remain valid. Update parent roll-ups and the declared version, then decide whether you want to use Thriller.
Why did IAB release 3.1 if so little changed?
The release supported work on CTV genres, where buyers wanted a consistent way to describe programming. Small, regular releases also keep the standard current without forcing large migrations.
Can I mix 2.x and 3.x codes in one list?
No. A major version change means the trees should not be combined. Keep one version per list and say which one it is.
Does 3.1 change the Descriptive Vectors?
The 3.1 release was described as a genres update. Vectors were introduced with 3.0 in a separate file; check the current IAB Tech Lab files if your workflow depends on them.
Which version should new projects use?
Start on version 3. If your platforms only accept 2.x today, take data that carries both columns so you can switch later without rebuilding segments.
How do contextual teams use these categories?
They turn chosen IDs into domain or page lists for targeting and exclusion. Our programmatic advertising and RTB page shows how category data fits the bid flow.
Category data that works on 3.0, 3.1 and 2.x
120 million domains with ranked IAB v3 and v2 categories, web filtering labels, personas and popularity in files that run in your own systems.
IAB and IAB Tech Lab are trademarks of the Interactive Advertising Bureau. They are used here only to identify the standard discussed. URL Categorization Database is not affiliated with, sponsored or endorsed by IAB or IAB Tech Lab. Category names are listed as facts; all explanations are our own.