[Proposal]: Product Compatibility and Fitment Signals for Product Discovery

[vamsi678]

Summary

This proposal introduces an optional compatibility and fitment extension for UCP catalog responses so merchants can declare when a product is compatible with, incompatible with, requires, or replaces a buyer-specific context such as a vehicle, HVAC system, electronic device, appliance, room dimension, or installed component.

In agent-driven commerce, compatibility is not just another product attribute. It is a purchase constraint. Without structured fitment signals, agents must infer compatibility from titles, descriptions, or merchant-specific metadata, which increases incorrect recommendations, failed checkouts, returns, and safety risk.

Motivation

Many high-intent commerce journeys depend on whether a product works with the buyer's context:

• Automotive: brake pads that fit a specific year/make/model/trim
• HVAC: capacitors, filters, motors, and replacement parts that work with a specific unit
• Electronics: chargers, adapters, cases, cables, and accessories compatible with a model
• Appliances: replacement parts that match a model or serial range
• Furniture/home goods: items that fit dimensions, rooms, or installation constraints

Today, UCP can represent products, availability, checkout, fulfillment, and order flows, but there is no standardized way for an agent to determine whether a product is valid for a buyer's specific context.

This matters because agentic commerce shifts product selection from human browsing to machine reasoning. Agents need structured compatibility signals to avoid recommending products that are available but not usable.

This proposal is especially relevant alongside existing open discussions around taxonomy/category filtering, stock/availability signals, local fulfillment, and catalog discovery. Those issues help agents find and transact against products, but they do not answer the core fitment question: "Can this buyer use this specific product?"

Goals

• Define a lightweight, optional compatibility extension for product/catalog responses.
• Support common compatibility relationships such as compatible_with, incompatible_with, requires, and replacement_for.
• Allow compatibility targets to be represented using structured attributes rather than unstructured text.
• Enable agents to filter or rank products based on buyer context.
• Preserve backward compatibility with existing UCP implementations.
• Leave room for category-specific extensions and external ontologies without requiring them in v1.

Non-Goals

• Define a complete universal ontology for every commerce category.
• Require all merchants to provide compatibility data.
• Replace existing product attributes, taxonomy, or category filtering.
• Define a full reasoning engine for compatibility inference.
• Require merchants to expose proprietary fitment databases.
• Standardize every vertical-specific fitment model in the initial proposal.

Introduce an optional compatibility field on product objects.

Detailed Design

Schema

• compatibility: array of compatibility assertions

Each assertion includes:

• type (required): compatible_with | incompatible_with | requires | replacement_for
• target.category (required): entity type (vehicle, device, hvac_unit, etc.)
• target.attributes (required): structured key-value context
• confidence (optional): number between 0 and 1
• source (optional): manufacturer, retailer, inferred, etc.

Example

{
  "compatibility": [
    {
      "type": "compatible_with",
      "target": {
        "category": "vehicle",
        "attributes": {
          "make": "Honda",
          "model": "Accord",
          "year": "2018"
        }
      },
      "confidence": 0.98,
      "source": "manufacturer"
    }
  ]
}

Conflict Resolution

When multiple compatibility assertions exist:

• incompatible_with MUST take precedence over compatible_with

• requires does not invalidate compatibility but introduces dependency

• If multiple assertions conflict, implementations SHOULD prioritize by source:

  Suggested precedence:

  1. manufacturer
  2. certification / standards body
  3. retailer
  4. seller
  5. inferred

• If confidence is provided, it MAY be used to break ties within the same source level

• In the absence of clear resolution:

  • Agents SHOULD default to conservative behavior (exclude or flag uncertainty)

• Absence of compatibility data MUST NOT be interpreted as compatibility

Target Identification Strategy

Compatibility targets may be represented using either structured attributes or stable identifiers.

Implementations SHOULD support at least one of the following:

• Attribute-based identification (e.g., make/model/year)
• External identifiers (e.g., GTIN, MPN, OEM ID, VIN pattern, catalog ID)
• Namespaced identifiers (e.g., "oem:12345", "gtin:000123456789")

Example with identifier:

{
  "type": "compatible_with",
  "target": {
    "category": "vehicle",
    "id": "oem:HONDA_ACCORD_2018_LX"
  }
}

Requires Semantics

The requires relationship indicates that a product depends on an additional product, condition, or configuration.

• A product MAY still be usable when requires is present, but is incomplete without the dependency
• Agents SHOULD surface required dependencies alongside the product
• Agents SHOULD NOT automatically exclude products with requires
• Implementations MAY choose to:
  • bundle required items
  • prompt users to confirm dependency
  • recommend compatible required components

Example:

{
  "type": "requires",
  "target": {
    "category": "accessory",
    "attributes": {
      "type": "power adapter",
      "minimum_wattage": "30W"
    }
  }
}

Temporal Validity (Optional)

Compatibility assertions MAY include temporal constraints:

• valid_from
• valid_until

This supports scenarios where compatibility changes over time (e.g., firmware updates, product revisions, regulatory changes).

Example:

{
  "type": "compatible_with",
  "valid_from": "2024-01-01",
  "valid_until": "2026-01-01"
}

Minimal Normalization Guidance

To improve interoperability:

• Common attribute keys SHOULD use consistent naming where possible (e.g., make, model, year)
• Implementations MAY map internal schemas to normalized keys
• This proposal does not enforce a global taxonomy in v1

Risks and Mitigations

• Category complexity: Keep schema generic and attribute-driven
• Data quality issues: Use optional confidence and source fields
• Inconsistent adoption: Make extension optional and incremental
• Overlap with attributes: Define compatibility as a relationship, not a static attribute

Test Plan

Unit Tests

• Validate compatibility schema structure and allowed types
• Validate required fields and optional constraints

Integration Tests

• Ensure responses without compatibility remain valid
• Ensure agents can parse compatibility data

End-to-End Tests

• Automotive: return only compatible parts
• HVAC: return correct replacement components
• Electronics: surface required accessories

Graduation Criteria

Working Draft → Candidate

• Schema defined and documented
• Tests passing
• Initial documentation available

Candidate → Stable

• Feedback incorporated
• Documentation finalized
• Reference implementation available

[Muitamax]

Recommendation for acceptance

Move forward, but require:

Must-have before Candidate
Add target identifier strategy
Define conflict resolution rules
Clarify requires semantics
Nice-to-have
Temporal validity
Minimal normalization guidelines
Bottom line
The problem framing is solid and important
The schema is a good starting point
But without identity + resolution rules, interoperability will degrade quickly

[joaomenkdev-cloud]

Hi! I came across this proposal and I'd love to contribute. I have backend experience and I'm comfortable working with JSON schemas and writing documentation.

Is this open for external contributions? If so, I'd like to start by drafting the schema changes and the initial documentation. Happy to follow the Enhancement Proposal process if required.

[vamsi678]

Recommendation for acceptance

Move forward, but require:

Must-have before Candidate Add target identifier strategy Define conflict resolution rules Clarify requires semantics Nice-to-have Temporal validity Minimal normalization guidelines Bottom line The problem framing is solid and important The schema is a good starting point But without identity + resolution rules, interoperability will degrade quickly

Thank you, great points and I added sections that clearly define identity resolution strategy etc.

[vamsi678]

Hi! I came across this proposal and I'd love to contribute. I have backend experience and I'm comfortable working with JSON schemas and writing documentation.

Is this open for external contributions? If so, I'd like to start by drafting the schema changes and the initial documentation. Happy to follow the Enhancement Proposal process if required.

Yes, once this request is finalized, we will reach out for contributions.

[joaomenkdev-cloud]

Hi vamsi678, thanks for the response and for incorporating the feedback so quickly — that's a great sign for the proposal.

I've been reviewing the updated spec, and a few thoughts I can bring to the implementation:

On identity resolution: I'd suggest the target_identifier field support a strategy enum (gtin, sku, merchant_id, url_slug) rather than a single opaque string. This makes cross-merchant resolution deterministic — agents can prefer gtin when available and fall back gracefully.

On conflict resolution: A conflict_resolution_rules array per response (field + strategy pairs like latest_updated or highest_confidence) would let platforms know exactly how the data was merged, which helps with caching and debugging.

On requires semantics: I'd model this as a list of required response fields (e.g. "requires": ["pricing", "availability"]), similar to how GraphQL handles field selection. This avoids over-fetching.

I've drafted a JSON schema for the discovery capability following UCP's existing authoring conventions ($defs, platform_schema/business_schema/response_schema variants, date-based versioning). Happy to open a draft PR with it once the proposal is accepted.

Looking forward to contributing!