diff --git a/.changeset/rename-inventory-lists-to-property-lists.md b/.changeset/rename-inventory-lists-to-property-lists.md new file mode 100644 index 0000000000..b6dc5b76fe --- /dev/null +++ b/.changeset/rename-inventory-lists-to-property-lists.md @@ -0,0 +1,19 @@ +--- +"adcontextprotocol": major +--- + +Rename the `inventory-lists` specialism to `property-lists` to match the tool family it actually tests (`create_property_list`, `validate_property_delivery`, etc.). The original name was flagged as onboarding friction in the fresh-builder specialism test (#2287): the specialism claimed to cover "property and collection lists" but the storyboard only exercised property-list tools, and every builder fumbled the `inventory-lists` ↔ `property_list` mapping. A dedicated `collection-lists` specialism can be added later when that storyboard is written. + +**Changes.** + +- `specialism` enum: `inventory-lists` → `property-lists` (wire ID), with updated `enumDescription` scoped to property lists only. +- Compliance source: `static/compliance/source/specialisms/inventory-lists/` → `property-lists/`. In `index.yaml`: `id: inventory_lists` → `property_lists`, `category: inventory_lists` → `property_lists`, `title: "Inventory lists"` → `"Property lists"`, capability tag and all step `correlation_id`s updated. Summary narrowed to property-list scope (removed "and collection"). +- `storyboard-schema.yaml` governance-categories comment updated. +- `compliance-catalog.mdx`: governance table, naming conventions example, mapping table, and tool-family prose bullet now use `property-lists` / `property_lists`. +- `glossary.mdx`: added **Specialism**, **Storyboard**, and **Storyboard Category** entries documenting the kebab↔snake split between wire IDs, storyboard categories, and prose titles. + +**Not renamed.** The media-buy scenarios `media_buy_seller/inventory_list_targeting` and `media_buy_seller/inventory_list_no_match` keep their IDs — they genuinely exercise both `PropertyListReference` and `CollectionListReference` targeting and are correctly "inventory list" umbrella scenarios. + +**Wire enum change (RC-window), no alias.** The `specialism` enum is only shipping in 3.0-rc.3 and has no published SDK or registered agent declaring `inventory-lists` today (verified across server, skills, docs, dist schemas, AAO runner). An alias would be dead weight. Contrast with the `audience-sync-domain-and-naming-docs` rename, which did emit transitional aliases because `@adcp/client@5.x` reads the old key — no comparable consumer exists here. + +Closes #2287 (the last open sub-issue of the fresh-builder epic #2288). diff --git a/docs/building/compliance-catalog.mdx b/docs/building/compliance-catalog.mdx index 619c2c4280..d4273df522 100644 --- a/docs/building/compliance-catalog.mdx +++ b/docs/building/compliance-catalog.mdx @@ -101,7 +101,7 @@ Specialisms are grouped below by parent protocol. | Specialism | Status | Purpose | |-----------|--------|---------| | `content-standards` | stable | Content standards enforcement (brand safety, policy compliance) | -| `inventory-lists` | stable | Property and collection list governance — curated inventory groupings for targeting and authorization | +| `property-lists` | stable | Property list governance — curated inclusion and exclusion lists for targeting and delivery compliance | | `governance-delivery-monitor` | stable | Campaign delivery monitoring with drift detection | | `governance-spend-authority` | stable | Conditional spend approval and human-in-the-loop governance | | `measurement-verification` | **preview** | Third-party measurement and verification. Parked under `governance` for 3.1; a dedicated `measurement` protocol is planned once the viewability, attribution, brand-safety, and SI-outcome surfaces split out. | @@ -139,7 +139,7 @@ Four casings coexist in the taxonomy. Which one applies depends on where the ide | Casing | Layer | Example | Where it appears | |--------|-------|---------|------------------| | `snake_case` | Wire enums (`supported_protocols`, `delivery_type`, channel IDs, `signal_type`) | `media_buy`, `non_guaranteed`, `ctv`, `custom` | `get_adcp_capabilities` response, JSON payloads, generated schemas | -| `kebab-case` | Specialism IDs and compliance URLs | `sales-streaming-tv`, `inventory-lists`, `audience-sync` | `get_adcp_capabilities.specialisms`, `/compliance/.../specialisms/{id}/` paths | +| `kebab-case` | Specialism IDs and compliance URLs | `sales-streaming-tv`, `property-lists`, `audience-sync` | `get_adcp_capabilities.specialisms`, `/compliance/.../specialisms/{id}/` paths | | `snake_case` | Storyboard `id:` and `category:` fields | `sales_broadcast_tv`, `audience_sync` | Compliance YAML frontmatter, runner output, test reports | | Prose / hyphenated | Titles and narrative | "Streaming TV", "non-guaranteed" | Catalog pages, narrative copy | @@ -150,7 +150,7 @@ The kebab↔snake swap between wire specialism IDs and storyboard categories is | `sales-streaming-tv` | `channels: ['ctv']` | `sales_streaming_tv` | — | | `sales-broadcast-tv` | `channels: ['linear_tv']` | `sales_broadcast_tv` | — | | `audience-sync` | `sync_audiences` tool | `audience_sync` | — | -| `inventory-lists` | `property_list` tools | `inventory_lists` | — | +| `property-lists` | `property_list` tools | `property_lists` | — | | `governance-spend-authority` | `check_governance`, `sync_plans` | `governance_spend_authority` | `governance_spend_authority/denied` | | `creative-generative` | `build_creative` | `creative_generative` | `creative_generative/seller` | | `brand-rights` | `get_brand_identity`, `acquire_rights` | `brand_rights` | `brand_rights/governance_denied` | @@ -162,7 +162,7 @@ The case split is deliberate: `supported_protocols` is a pre-existing 3.0 field The protocol an agent claims does not always match the tool family name a specialism uses: - `audience-sync` lives under the `media-buy` protocol because `sync_audiences` is a media-buy tool. -- `inventory-lists` is the specialism name; the actual tools are named `create_property_list`, `validate_property_delivery`, etc. "Inventory list" is the prose concept; `property_list` is the tool family. +- `property-lists` (specialism ID, kebab-case) maps to the `property_list` tool family (`create_property_list`, `validate_property_delivery`) and storyboard category `property_lists`. - `sales-streaming-tv` declares `channels: ['ctv']` — "Streaming TV" is the prose name; `ctv` is the wire value. `/compliance/{version}/index.json` surfaces each specialism's `required_tools` so agents can discover the tool families without reading the full storyboard YAML. diff --git a/docs/reference/glossary.mdx b/docs/reference/glossary.mdx index 8517071c2d..f97b38e53b 100644 --- a/docs/reference/glossary.mdx +++ b/docs/reference/glossary.mdx @@ -315,12 +315,21 @@ The data type of a signal's values: `binary` (user matches or doesn't), `categor **Size Unit** (Signals Protocol) The measurement type for signal size: individuals, devices, or households. +**Specialism** +A specific capability claim an agent declares in `get_adcp_capabilities.specialisms`. Each specialism has a wire ID in `kebab-case` (e.g. `sales-guaranteed`, `property-lists`) and a matching storyboard bundle published at `/compliance/{version}/specialisms/{id}/`. The AAO compliance runner executes the matching storyboards to verify the claim. See [Compliance Catalog](/docs/building/compliance-catalog) for the list of specialism IDs; claim one by adding it to your `get_adcp_capabilities.specialisms` array, then run [Validate Your Agent](/docs/building/validate-your-agent) to see how the runner maps it to storyboards. + **Sponsored Intelligence (SI)** An open standard for conversational brand experiences in AI assistants. Like VAST defines video ad serving, SI defines how to serve and interact with brand agent endpoints. SI handles the engagement; the Agentic Commerce Protocol (ACP) handles transactions. See [SI Chat Protocol](/docs/sponsored-intelligence/si-chat-protocol) for details. **SSP (Supply-Side Platform)** A type of decisioning platform that helps publishers sell advertising inventory programmatically. SSPs connect to multiple demand sources and make ad selection decisions. Examples: Index Exchange, OpenX, PubMatic, Magnite. +**Storyboard** +A compliance test bundle that verifies a protocol baseline or [specialism](#specialism) claim. Each storyboard is a YAML file under `/compliance/{version}/` that declares an `id`, phases of test steps, sample requests, and validations the agent must pass. Storyboards live in three buckets: `universal/` (applies to every agent), `protocols/{protocol}/` (one baseline per supported protocol), and `specialisms/{id}/` (one per specialism claim). + +**Storyboard Category** +The `snake_case` identifier in a storyboard's `category:` frontmatter field. For specialisms, the category is the specialism's kebab-case wire ID with hyphens swapped to underscores — e.g. specialism ID `sales-streaming-tv` has category `sales_streaming_tv`. Variant scenarios within a specialism use `{category}/{variant}` form (e.g. `governance_spend_authority/denied`). The kebab↔snake split is deliberate: specialism IDs are URL path segments, storyboard categories are wire enums. + ## T **Takeover** diff --git a/static/compliance/source/specialisms/inventory-lists/index.yaml b/static/compliance/source/specialisms/property-lists/index.yaml similarity index 93% rename from static/compliance/source/specialisms/inventory-lists/index.yaml rename to static/compliance/source/specialisms/property-lists/index.yaml index 9d91852098..6207cc29da 100644 --- a/static/compliance/source/specialisms/inventory-lists/index.yaml +++ b/static/compliance/source/specialisms/property-lists/index.yaml @@ -1,9 +1,9 @@ -id: inventory_lists +id: property_lists version: "1.0.0" -title: "Inventory lists" +title: "Property lists" protocol: governance -category: inventory_lists -summary: "Curated property and collection lists for inventory grouping, targeting governance, and delivery compliance — create, query, update, delete, and validate." +category: property_lists +summary: "Curated property lists for inventory grouping, targeting governance, and delivery compliance — create, query, update, delete, and validate." track: governance required_tools: - create_property_list @@ -24,7 +24,7 @@ narrative: | agent: interaction_model: governance_agent capabilities: - - inventory_lists + - property_lists - brand_safety examples: - "IAS" @@ -64,7 +64,7 @@ phases: Return capabilities declaring governance in supported_protocols, confirming the agent provides governance services. sample_request: context: - correlation_id: "inventory_lists--get_capabilities" + correlation_id: "property_lists--get_capabilities" validations: - check: response_schema description: "Response matches get-adcp-capabilities-response.json schema" @@ -77,7 +77,7 @@ phases: description: "Response echoes back the context object" - check: field_value path: "context.correlation_id" - value: "inventory_lists--get_capabilities" + value: "property_lists--get_capabilities" description: "Context correlation_id returned unchanged" - id: create_list title: "Create property lists" @@ -119,7 +119,7 @@ phases: value: "campinggear.example" context: - correlation_id: "inventory_lists--create_inclusion_list" + correlation_id: "property_lists--create_inclusion_list" context_outputs: - path: "list.list_id" key: "property_list_id" @@ -133,7 +133,7 @@ phases: description: "Response echoes back the context object" - check: field_value path: "context.correlation_id" - value: "inventory_lists--create_inclusion_list" + value: "property_lists--create_inclusion_list" description: "Context correlation_id returned unchanged" - check: field_present path: "list.list_id" @@ -166,7 +166,7 @@ phases: name_contains: "Acme Outdoor" context: - correlation_id: "inventory_lists--list_property_lists" + correlation_id: "property_lists--list_property_lists" validations: - check: response_schema description: "Response matches list-property-lists-response.json schema" @@ -176,7 +176,7 @@ phases: description: "Response echoes back the context object" - check: field_value path: "context.correlation_id" - value: "inventory_lists--list_property_lists" + value: "property_lists--list_property_lists" description: "Context correlation_id returned unchanged" - id: get_property_list title: "Get a specific property list" @@ -200,7 +200,7 @@ phases: domain: "acmeoutdoor.example" context: - correlation_id: "inventory_lists--get_property_list" + correlation_id: "property_lists--get_property_list" validations: - check: response_schema description: "Response matches get-property-list-response.json schema" @@ -210,7 +210,7 @@ phases: description: "Response echoes back the context object" - check: field_value path: "context.correlation_id" - value: "inventory_lists--get_property_list" + value: "property_lists--get_property_list" description: "Context correlation_id returned unchanged" - id: update_list title: "Update property lists" @@ -249,7 +249,7 @@ phases: value: "mountaineering.example" context: - correlation_id: "inventory_lists--update_property_list" + correlation_id: "property_lists--update_property_list" validations: - check: response_schema description: "Response matches update-property-list-response.json schema" @@ -259,7 +259,7 @@ phases: description: "Response echoes back the context object" - check: field_value path: "context.correlation_id" - value: "inventory_lists--update_property_list" + value: "property_lists--update_property_list" description: "Context correlation_id returned unchanged" - id: delivery_validation title: "Validate delivery compliance" @@ -304,7 +304,7 @@ phases: impressions: 200 context: - correlation_id: "inventory_lists--validate_property_delivery" + correlation_id: "property_lists--validate_property_delivery" validations: - check: response_schema description: "Response matches validate-property-delivery-response.json schema" @@ -319,7 +319,7 @@ phases: description: "Response echoes back the context object" - check: field_value path: "context.correlation_id" - value: "inventory_lists--validate_property_delivery" + value: "property_lists--validate_property_delivery" description: "Context correlation_id returned unchanged" - id: enforcement @@ -436,7 +436,7 @@ phases: domain: "acmeoutdoor.example" context: - correlation_id: "inventory_lists--delete_property_list" + correlation_id: "property_lists--delete_property_list" validations: - check: response_schema description: "Response matches delete-property-list-response.json schema" @@ -446,5 +446,5 @@ phases: description: "Response echoes back the context object" - check: field_value path: "context.correlation_id" - value: "inventory_lists--delete_property_list" + value: "property_lists--delete_property_list" description: "Context correlation_id returned unchanged" diff --git a/static/compliance/source/universal/storyboard-schema.yaml b/static/compliance/source/universal/storyboard-schema.yaml index 3380bb6f06..19462b4094 100644 --- a/static/compliance/source/universal/storyboard-schema.yaml +++ b/static/compliance/source/universal/storyboard-schema.yaml @@ -17,7 +17,7 @@ # Sales: sales_guaranteed | sales_non_guaranteed | sales_proposal_mode | sales_catalog_driven | sales_broadcast_tv | sales_streaming_tv | sales_social | sales_exchange | sales_retail_media # Creative: creative_ad_server | creative_generative | creative_template # Signals: signal_marketplace | signal_owned -# Governance: content_standards | inventory_lists | governance_delivery_monitor | governance_spend_authority | measurement_verification +# Governance: content_standards | property_lists | governance_delivery_monitor | governance_spend_authority | measurement_verification # Brand: brand_rights # Audiences: audience_sync # Universal / domain-level: capability_discovery | schema_validation | behavioral_analysis | error_compliance | security | media_buy_seller | media_buy_governance_escalation | si_session diff --git a/static/schemas/source/enums/specialism.json b/static/schemas/source/enums/specialism.json index 21ffa69968..b46832e1e0 100644 --- a/static/schemas/source/enums/specialism.json +++ b/static/schemas/source/enums/specialism.json @@ -13,8 +13,8 @@ "creative-template", "governance-delivery-monitor", "governance-spend-authority", - "inventory-lists", "measurement-verification", + "property-lists", "sales-broadcast-tv", "sales-catalog-driven", "sales-exchange", @@ -36,8 +36,8 @@ "creative-template": "Creative template and transformation agent", "governance-delivery-monitor": "Campaign delivery monitoring with drift detection", "governance-spend-authority": "Conditional spend approval and human-in-the-loop governance", - "inventory-lists": "Property and collection list governance — curated inventory groupings for targeting and authorization", "measurement-verification": "Third-party measurement and verification across domains (viewability, brand safety, attribution, SI outcomes)", + "property-lists": "Property list governance — curated inclusion and exclusion lists for targeting and delivery compliance", "sales-broadcast-tv": "Broadcast linear TV seller with guaranteed inventory and FCC cancellation rules", "sales-catalog-driven": "Catalog-driven commerce with conversion tracking", "sales-exchange": "Programmatic exchange or SSP exposing auction-based inventory",