From 3c8b5491878652dcc3a62af0a6e34fc810361f38 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Fri, 13 Nov 2026 11:50:28 +0000 Subject: [PATCH 1/2] feat(schema): display labels for geo targeting codes Targeting gains display names beside its geographic codes, in the shape geo_places already uses. geo_metros and geo_metros_exclude entries take value_labels, and core/targeting.json takes geo_value_labels for the ISO codes in geo_countries, geo_countries_exclude, geo_regions and geo_regions_exclude. Labels are diagnostic: they never resolve or apply targeting, and equality and readback compare codes only. Co-Authored-By: Claude Opus 5.5 --- .changeset/geo-value-labels.md | 5 ++++ docs/media-buy/advanced-topics/targeting.mdx | 12 +++++--- static/schemas/source/core/geo-metro.json | 14 ++++++++- .../schemas/source/core/targeting-input.json | 4 +++ static/schemas/source/core/targeting.json | 29 +++++++++++++++++++ tests/schema-validation.test.cjs | 22 ++++++++++++++ 6 files changed, 81 insertions(+), 5 deletions(-) create mode 100644 .changeset/geo-value-labels.md diff --git a/.changeset/geo-value-labels.md b/.changeset/geo-value-labels.md new file mode 100644 index 00000000000..b4dd663f69b --- /dev/null +++ b/.changeset/geo-value-labels.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": minor +--- + +Targeting can carry display names beside its geographic codes. `core/targeting.json` adds `geo_value_labels`, a map from the ISO codes in `geo_countries`, `geo_countries_exclude`, `geo_regions` and `geo_regions_exclude` to their names (`{ "DE": "Germany", "US-CA": "California" }`), and `core/targeting-input.json` accepts it. `core/geo-metro.json` and the `geo_metros_exclude` entries add `value_labels`, the shape `geo_places` already uses (`{ "501": "New York" }`). Every label key must appear in the values it labels, which conformance tooling enforces through `x-adcp-validation`. Labels are not a targeting dimension: sellers never resolve or apply targeting from them, never reject a request because they are present, and may omit, keep or supply their own in readback, and targeting equality and exact readback compare codes only. A name in place of a code is still invalid. This lets a package, proposal or audit log show "New York" next to `501` without a separate lookup. Buyers should not send `geo_value_labels` to a seller on a version before 3.3. Updated: the Geographic Restrictions section of the targeting guide. diff --git a/docs/media-buy/advanced-topics/targeting.mdx b/docs/media-buy/advanced-topics/targeting.mdx index 819f60732e0..7dbd13701f1 100644 --- a/docs/media-buy/advanced-topics/targeting.mdx +++ b/docs/media-buy/advanced-topics/targeting.mdx @@ -880,6 +880,8 @@ Use geo fields **only** for: **Note**: Inclusion and exclusion can be combined. Metro and postal targeting require specifying the classification system, enabling international support. Not all geographic granularities are supported by all publishers. Country and region are most widely supported. +**Labels.** Codes are the targeting. A targeting object MAY carry display names beside them so a person reading a package, a proposal, or an audit log does not have to look codes up: `geo_value_labels` for ISO country and subdivision codes (`{ "DE": "Germany", "US-CA": "California" }`), and `value_labels` on each `geo_metros`, `geo_metros_exclude`, and `geo_places` entry. Every label key MUST appear in the values it labels. Labels are not a targeting dimension: sellers MUST NOT resolve or apply targeting from them, MUST NOT reject a request because they are present, and MAY omit, keep, or supply their own labels in readback. Targeting equality and exact readback compare codes only. A name with no code, such as `"California"` in `geo_regions`, is still invalid. Buyers SHOULD NOT send `geo_value_labels` to a seller on a version before 3.3, which may treat an unknown key as an unsupported dimension. + ### Age Restrictions (Compliance) Use for **legal compliance** requirements: - **Alcohol advertising**: Require verified 21+ in the US @@ -1113,6 +1115,7 @@ Geographic targeting supports both inclusion (restrict to) and exclusion (exclud - **Description**: Restrict delivery to specific countries - **Format**: ISO 3166-1 alpha-2 country codes - **Examples**: `["US", "CA"]`, `["GB", "FR", "DE"]` +- **Labels**: optional, in `geo_value_labels` (e.g., `{ "GB": "United Kingdom" }`) - **Use cases**: Regulatory compliance, country-specific campaigns ### geo_countries_exclude @@ -1147,6 +1150,7 @@ disclosed, compliant targeting modification. - **Description**: Restrict delivery to canonical ISO 3166-2 subdivisions, including states, provinces, regions, departments, and overseas subdivisions - **Format**: ISO 3166-2 subdivision codes - **Examples**: `["US-CA", "CA-QC"]`, `["FR-49", "FR-2A", "FR-971", "FR-ARA"]` +- **Labels**: optional, in `geo_value_labels` (e.g., `{ "US-CA": "California" }`) - **Use cases**: State-level compliance, regional testing ### geo_regions_exclude @@ -1165,16 +1169,16 @@ At create or update, unsupported dimensions, countries, or values outside Produc ### geo_metros - **Description**: Restrict delivery to specific metro areas -- **Format**: Array of objects, each with a `system` and `values` +- **Format**: Array of objects, each with a `system` and `values`; optional `value_labels` - **Systems**: `nielsen_dma` (US), `uk_itl1` / `uk_itl2` (UK), `eurostat_nuts2` (EU), `custom` -- **Example**: `[{ "system": "nielsen_dma", "values": ["501", "803"] }]` +- **Example**: `[{ "system": "nielsen_dma", "values": ["501", "803"], "value_labels": { "501": "New York", "803": "Los Angeles" } }]` - **Use cases**: Local campaigns, metro-level RCT testing - **Note**: Seller must declare supported systems in `get_adcp_capabilities` ### geo_metros_exclude - **Description**: Exclude specific metro areas from delivery -- **Format**: Array of objects, each with a `system` and `values` -- **Example**: `[{ "system": "nielsen_dma", "values": ["602"] }]` +- **Format**: Array of objects, each with a `system` and `values`; optional `value_labels` +- **Example**: `[{ "system": "nielsen_dma", "values": ["602"], "value_labels": { "602": "Chicago" } }]` - **Use cases**: RCT holdout markets, competitive exclusion zones, markets where product is unavailable - **Note**: Seller must declare supported systems in `get_adcp_capabilities` diff --git a/static/schemas/source/core/geo-metro.json b/static/schemas/source/core/geo-metro.json index 1076b659983..b1503b3c084 100644 --- a/static/schemas/source/core/geo-metro.json +++ b/static/schemas/source/core/geo-metro.json @@ -2,7 +2,11 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/core/geo-metro.json", "title": "Geo Metro", - "description": "A targeted metro area.", + "description": "A targeted metro area. value_labels are diagnostic only and MUST NOT be used to resolve targeting.", + "x-adcp-validation": { + "map_keys_subset_of_array": { "map_field": "value_labels", "array_field": "values" }, + "description": "Every value_labels key MUST also appear in values. JSON Schema draft-07 cannot express this sibling-field key membership constraint, so conformance tooling must enforce it." + }, "type": "object", "properties": { "system": { @@ -14,6 +18,14 @@ "description": "Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs)", "items": { "type": "string" }, "minItems": 1 + }, + "value_labels": { + "type": "object", + "description": "Optional human-readable diagnostic labels keyed by codes present in values (e.g., { \"501\": \"New York\" }). Extra keys are a conformance error. Labels are non-authoritative and MUST NOT be used to resolve or apply targeting.", + "additionalProperties": { + "type": "string", + "minLength": 1 + } } }, "required": ["system", "values"], diff --git a/static/schemas/source/core/targeting-input.json b/static/schemas/source/core/targeting-input.json index dc108ce6e9e..6781497056b 100644 --- a/static/schemas/source/core/targeting-input.json +++ b/static/schemas/source/core/targeting-input.json @@ -29,6 +29,10 @@ { "type": "null" } ] }, + "geo_value_labels": { + "$ref": "/schemas/core/targeting.json#/properties/geo_value_labels", + "description": "Optional diagnostic labels for ISO codes supplied in this request's geo_countries, geo_countries_exclude, geo_regions, or geo_regions_exclude. Not a targeting dimension and not stored state: it has no null form, and sellers MUST NOT reject a request because it is present or apply targeting from it." + }, "geo_metros": { "title": "Targeting Geo Metros", "type": ["array", "null"], diff --git a/static/schemas/source/core/targeting.json b/static/schemas/source/core/targeting.json index 302f7e45d99..70771f1fe92 100644 --- a/static/schemas/source/core/targeting.json +++ b/static/schemas/source/core/targeting.json @@ -53,6 +53,23 @@ }, "minItems": 1 }, + "geo_value_labels": { + "type": "object", + "description": "Optional human-readable diagnostic labels for the ISO codes in geo_countries, geo_countries_exclude, geo_regions, and geo_regions_exclude, keyed by code (e.g., { \"DE\": \"Germany\", \"US-CA\": \"California\" }). Every key MUST appear in one of those four arrays; extra keys are a conformance error. Labels are not a targeting dimension: they are non-authoritative, MUST NOT be used to resolve or apply targeting, and are ignored when comparing targeting for equality or readback. Metro and place labels live in value_labels on their own entries.", + "x-adcp-validation": { + "map_keys_subset_of_arrays": { + "array_fields": ["geo_countries", "geo_countries_exclude", "geo_regions", "geo_regions_exclude"] + }, + "description": "Every geo_value_labels key MUST appear in at least one of the listed sibling arrays. JSON Schema draft-07 cannot express this sibling-field key membership constraint, so conformance tooling must enforce it." + }, + "propertyNames": { + "pattern": "^[A-Z]{2}(-[A-Z0-9]{1,3})?$" + }, + "additionalProperties": { + "type": "string", + "minLength": 1 + } + }, "geo_metros": { "title": "Targeting Geo Metros", "type": "array", @@ -65,6 +82,10 @@ "description": "Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities.", "items": { "type": "object", + "x-adcp-validation": { + "map_keys_subset_of_array": { "map_field": "value_labels", "array_field": "values" }, + "description": "Every value_labels key MUST also appear in values. JSON Schema draft-07 cannot express this sibling-field key membership constraint, so conformance tooling must enforce it." + }, "properties": { "system": { "$ref": "/schemas/enums/metro-system.json", @@ -77,6 +98,14 @@ "type": "string" }, "minItems": 1 + }, + "value_labels": { + "type": "object", + "description": "Optional human-readable diagnostic labels keyed by codes present in values (e.g., { \"602\": \"Chicago\" }). Extra keys are a conformance error. Labels are non-authoritative and MUST NOT be used to resolve or apply targeting.", + "additionalProperties": { + "type": "string", + "minLength": 1 + } } }, "required": ["system", "values"], diff --git a/tests/schema-validation.test.cjs b/tests/schema-validation.test.cjs index e5df793cb4d..2b97d9536b7 100644 --- a/tests/schema-validation.test.cjs +++ b/tests/schema-validation.test.cjs @@ -2129,7 +2129,29 @@ async function runTests() { return 'semantic value_labels validation must reject labels for absent values'; } + const metroSchema = loadSchema(path.join(SCHEMA_BASE_DIR, 'core/geo-metro.json')); + const metroLabelRule = metroSchema['x-adcp-validation']?.map_keys_subset_of_array; + if (metroLabelRule?.map_field !== 'value_labels' || metroLabelRule?.array_field !== 'values') { + return 'geo-metro must declare value_labels key membership validation'; + } + const targetingSchema = loadSchema(path.join(SCHEMA_BASE_DIR, 'core/targeting.json')); + const excludeMetroLabelRule = targetingSchema.properties.geo_metros_exclude.items['x-adcp-validation']?.map_keys_subset_of_array; + if (excludeMetroLabelRule?.map_field !== 'value_labels' || excludeMetroLabelRule?.array_field !== 'values') { + return 'geo_metros_exclude entries must declare value_labels key membership validation'; + } + const isoLabelRule = targetingSchema.properties.geo_value_labels?.['x-adcp-validation']?.map_keys_subset_of_arrays; + if (JSON.stringify(isoLabelRule?.array_fields) !== JSON.stringify(['geo_countries', 'geo_countries_exclude', 'geo_regions', 'geo_regions_exclude'])) { + return 'geo_value_labels must declare key membership across the ISO country and region arrays'; + } + const isoLabelsAreSubset = (overlay) => Object.keys(overlay.geo_value_labels || {}).every(code => + isoLabelRule.array_fields.some(field => (overlay[field] || []).includes(code))); + if (!isoLabelsAreSubset({ geo_countries: ['DE'], geo_regions_exclude: ['US-CA'], geo_value_labels: { DE: 'Germany', 'US-CA': 'California' } })) { + return 'semantic geo_value_labels validation must accept labels for codes in any labelled array'; + } + if (isoLabelsAreSubset({ geo_countries: ['DE'], geo_value_labels: { FR: 'France' } })) { + return 'semantic geo_value_labels validation must reject labels for absent codes'; + } const disjointRule = targetingSchema['x-adcp-validation']?.disjoint_place_fields; if (disjointRule?.include !== 'geo_places' || disjointRule?.exclude !== 'geo_places_exclude') { return 'targeting schema must declare geo place include/exclude disjointness validation'; From b00e48292e41e81e7a82e89895e2491a9e642ef2 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Fri, 13 Nov 2026 13:42:03 +0000 Subject: [PATCH 2/2] fix(schema): geo_value_labels takes a null clear in targeting input Every targeting field in targeting-input.json has a null branch, which targeting-null-clear.test.cjs enforces. geo_value_labels follows the same three states: omit to keep, a map to replace, null to clear labels the seller kept. Co-Authored-By: Claude Opus 5.5 --- docs/media-buy/advanced-topics/targeting.mdx | 2 +- static/schemas/source/core/targeting-input.json | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/media-buy/advanced-topics/targeting.mdx b/docs/media-buy/advanced-topics/targeting.mdx index 7dbd13701f1..06aa5654fc4 100644 --- a/docs/media-buy/advanced-topics/targeting.mdx +++ b/docs/media-buy/advanced-topics/targeting.mdx @@ -880,7 +880,7 @@ Use geo fields **only** for: **Note**: Inclusion and exclusion can be combined. Metro and postal targeting require specifying the classification system, enabling international support. Not all geographic granularities are supported by all publishers. Country and region are most widely supported. -**Labels.** Codes are the targeting. A targeting object MAY carry display names beside them so a person reading a package, a proposal, or an audit log does not have to look codes up: `geo_value_labels` for ISO country and subdivision codes (`{ "DE": "Germany", "US-CA": "California" }`), and `value_labels` on each `geo_metros`, `geo_metros_exclude`, and `geo_places` entry. Every label key MUST appear in the values it labels. Labels are not a targeting dimension: sellers MUST NOT resolve or apply targeting from them, MUST NOT reject a request because they are present, and MAY omit, keep, or supply their own labels in readback. Targeting equality and exact readback compare codes only. A name with no code, such as `"California"` in `geo_regions`, is still invalid. Buyers SHOULD NOT send `geo_value_labels` to a seller on a version before 3.3, which may treat an unknown key as an unsupported dimension. +**Labels.** Codes are the targeting. A targeting object MAY carry display names beside them so a person reading a package, a proposal, or an audit log does not have to look codes up: `geo_value_labels` for ISO country and subdivision codes (`{ "DE": "Germany", "US-CA": "California" }`), and `value_labels` on each `geo_metros`, `geo_metros_exclude`, and `geo_places` entry. Every label key MUST appear in the values it labels. Labels are not a targeting dimension: sellers MUST NOT resolve or apply targeting from them, MUST NOT reject a request because they are present, and MAY omit, keep, or supply their own labels in readback. In create and update input, `geo_value_labels` follows the same three states as a dimension, so `null` clears labels the seller kept. Targeting equality and exact readback compare codes only. A name with no code, such as `"California"` in `geo_regions`, is still invalid. Buyers SHOULD NOT send `geo_value_labels` to a seller on a version before 3.3, which may treat an unknown key as an unsupported dimension. ### Age Restrictions (Compliance) Use for **legal compliance** requirements: diff --git a/static/schemas/source/core/targeting-input.json b/static/schemas/source/core/targeting-input.json index 6781497056b..35776bdd8d9 100644 --- a/static/schemas/source/core/targeting-input.json +++ b/static/schemas/source/core/targeting-input.json @@ -30,8 +30,10 @@ ] }, "geo_value_labels": { - "$ref": "/schemas/core/targeting.json#/properties/geo_value_labels", - "description": "Optional diagnostic labels for ISO codes supplied in this request's geo_countries, geo_countries_exclude, geo_regions, or geo_regions_exclude. Not a targeting dimension and not stored state: it has no null form, and sellers MUST NOT reject a request because it is present or apply targeting from it." + "anyOf": [ + { "$ref": "/schemas/core/targeting.json#/properties/geo_value_labels" }, + { "type": "null" } + ] }, "geo_metros": { "title": "Targeting Geo Metros",