Catalog: Standardized taxonomy / terms discovery for category filtering

[invocation97]

Summary

The current Catalog Search capability allows platforms to filter by category using human-readable strings (e.g. "Footwear"), but does not define a standardized way for platforms to discover or reference a business’s canonical taxonomy terms. Many real-world commerce backends require internal identifiers (IDs or slugs) for taxonomy filtering, which creates ambiguity and inconsistent behavior across implementations.

This proposal introduces a standardized Terms Discovery capability (e.g. categories, collections, taxonomies) that allows platforms to retrieve business-defined terms in a canonical, reusable format. This enables accurate filtering, reduces guesswork by AI platforms, and improves interoperability across diverse commerce systems.

Motivation

As demonstrated in ongoing implementation and testing of the Catalog REST binding (see PR #55), platforms may submit filters.category as a string label, but businesses often require internal identifiers to apply the filter correctly. Without a discovery mechanism, platforms must guess category names or rely on fuzzy matching, leading to empty results, inconsistent filtering, or degraded user experience.

This limitation becomes especially apparent for AI-driven platforms, where category labels may be inferred from user intent rather than grounded in the merchant’s actual taxonomy. A standardized way to retrieve and reuse canonical terms would allow platforms to stop guessing and instead rely on business-provided structures.

The primary beneficiaries are:

• Platform implementers (human or AI) seeking predictable filtering behavior
• Business implementers who want to expose taxonomies without leaking internal data models
• The UCP ecosystem, through improved cross-backend interoperability

Goals

• Provide a standardized, optional mechanism for platforms to discover business-defined taxonomy terms.
• Enable platforms to reference canonical term identifiers in subsequent catalog searches.
• Reduce ambiguity around filters.category and similar taxonomy-based filters.
• Improve consistency across UCP implementations backed by different commerce systems.

Non-Goals

• Mandating internal identifier formats or exposing raw backend IDs.
• Replacing free-text search or requiring platforms to always prefetch terms.
• Defining business-specific taxonomy semantics beyond discovery and reference.

Detailed Design

API Changes

Introduce a new optional capability and endpoint, for example:

GET /catalog/terms

or a scoped variant:

GET /catalog/terms/{type}

Where {type} may include values such as category, collection, or other business-defined taxonomies.

Request Parameters (illustrative)

• type (path or query): taxonomy type (e.g. category)
• search (optional): free-text filter for narrowing results
• limit, cursor: pagination controls

Response Structure (illustrative)

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.catalog.terms",
        "version": "2026-01-11"
      }
    ]
  },
  "terms": [
    {
      "type": "category",
      "labels": [
        { "scheme": "merchant", "label": "Footwear" }
      ],
      "identifiers": [
        { "scheme": "merchant", "id": "cat_123" }
      ],
      "path": "Footwear"
    },
    {
      "type": "category",
      "labels": [
        { "scheme": "merchant", "label": "Running" }
      ],
      "identifiers": [
        { "scheme": "merchant", "id": "cat_124" }
      ],
      "path": "Footwear > Running"
    }
  ],
  "pagination": {
    "cursor": "eyJwYWdlIjoxfQ==",
    "has_next_page": false
  }
}

Note: labels / identifiers are arrays to support multiple taxonomy schemes (e.g. a merchant-defined value alongside one or more standardized taxonomy references), per discussion in PR #55. A platform can use the merchant identifier for precise filtering, while optionally retaining standardized taxonomy values for cross-merchant reasoning.

Behavioral Changes

• Platforms may optionally call the terms endpoint to ground category filters before invoking /catalog/search.
• Businesses may continue to accept string-based category filters for backward compatibility.
• When a canonical id is provided in filters.category, businesses may apply exact matching without additional resolution.
• When terms include multiple schemes, platforms SHOULD prefer the merchant scheme for subsequent calls to /catalog/search for that specific business.

Risks and Mitigations

Security

• Risk: exposing internal taxonomy structure
• Mitigation: terms are opaque identifiers defined by the business; no requirement to expose backend IDs.

Performance

• Risk: additional round-trip for discovery
• Mitigation: endpoint is optional; platforms may cache results and reuse identifiers.

Backward Compatibility

• Risk: none — existing string-based filtering remains valid
• Mitigation: discovery capability is additive and optional.

Complexity

• Risk: increased spec surface area
• Mitigation: scope limited to read-only discovery with simple pagination.

Test Plan

Unit Tests

• Validate schema compliance for terms responses.
• Ensure pagination behavior is correct.

Integration Tests

• Verify that discovered term IDs can be reused in subsequent catalog searches.
• Confirm backward compatibility with string-only filters.

End-to-End Tests

• Platform retrieves categories, selects a term, and performs a filtered product search using the returned identifier.

Graduation Criteria

Working Draft → Candidate:

• Terms discovery schema merged and documented.
• Example REST binding added.
• Reference implementation or fixture provided.
• TC majority vote to advance.

Candidate → Stable:

• Feedback from at least one platform and one business implementation.
• Documentation updated with best practices for AI platforms.
• TC majority vote to advance.