diff --git a/.changeset/geo-value-labels.md b/.changeset/geo-value-labels.md new file mode 100644 index 0000000000..b4dd663f69 --- /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 819f60732e..06aa5654fc 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. 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: - **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 1076b65998..b1503b3c08 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 dc108ce6e9..35776bdd8d 100644 --- a/static/schemas/source/core/targeting-input.json +++ b/static/schemas/source/core/targeting-input.json @@ -29,6 +29,12 @@ { "type": "null" } ] }, + "geo_value_labels": { + "anyOf": [ + { "$ref": "/schemas/core/targeting.json#/properties/geo_value_labels" }, + { "type": "null" } + ] + }, "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 302f7e45d9..70771f1fe9 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 e5df793cb4..2b97d9536b 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';