feat: ask capability for natural-language Q&A

[igrigorik]

Adds dev.ucp.shopping.ask, a new top-level shopping capability. A platform, on behalf of the buyer, asks a free-form question and receives a text answer with optional related links. ask is the standardized ingress for the open questions buyers actually ask — returns, shipping, warranty, store hours, fit, suitability, etc — and for business-specific facts and knowledge that no structured capability exposes.

Examples

A broad question, no grounding. Request:

{
  "query": "What is your return policy for items bought on sale?"
}

Response:

{
  "ucp": { "version": "draft", "capabilities": { "dev.ucp.shopping.ask": [{ "version": "draft" }] } },
  "answer": {
    "markdown": "Sale items can be returned within **14 days** of delivery for store credit. Items returned to a different region may be subject to local return rules — see the refund policy for details."
  },
  "links": [
    { "type": "refund_policy", "url": "https://business.example.com/policies/refunds", "title": "Refund Policy" }
  ]
}

Grounded, multi-turn conversation

Turn 1 grounds the question on a specific product via ids; the business issues an opaque conversation value. Turn 2 replays it to continue, and the business builds on the prior turn. Request:

{
  "query": "Is this jacket warm enough for winter?",
  "ids": ["https://business.example.com/products/winter-jacket"]
}

Response:

{
  "ucp": { "version": "draft", "capabilities": { "dev.ucp.shopping.ask": [{ "version": "draft" }] } },
  "answer": {
    "plain": "Yes — it's insulated for sub-zero conditions and rated for harsh winter use."
  },
  "conversation": "conv_9a3f2e7b"
}

Turn 2, Request:

{
  "query": "And is it waterproof?",
  "conversation": "conv_9a3f2e7b"
}

Turn 2, response:

{
  "ucp": { "version": "draft", "capabilities": { "dev.ucp.shopping.ask": [{ "version": "draft" }] } },
  "answer": {
    "plain": "It's water-resistant with a durable water-repellent finish — good for snow and light rain, though not fully waterproof."
  },
  "conversation": "conv_9a3f2e7b"
}

"Can't answer" (best-effort)

A question the business can't address still returns a successful response with a populated answer that states the limitation — never an error.

{
  "ucp": { "version": "draft", "capabilities": { "dev.ucp.shopping.ask": [{ "version": "draft" }] } },
  "answer": {
    "plain": "I don't have information about competitor pricing. For questions about this store's products, I can help with policies, materials, fit, and availability."
  }
}

Design highlights

• Best-effort contract — every well-formed, authorized request returns success with a populated answer. A "can't answer" outcome is a populated answer that says so plainly, never an error code or non-2xx status.
• Multi-turn — a business MAY issue an opaque conversation value; the platform replays it to continue, and the business builds on prior turns. Omitting it starts fresh; an unresolved value starts a new conversation and notes it in messages. Platforms MUST treat it as opaque.
• Grounding via ids — a business SHOULD accept grounding identifiers (product and variant IDs are the recommended minimum) and MAY also accept secondary identifiers (SKU, handle, URL) and other held GIDs such as a cart or checkout. For a cart or checkout, a held GID MAY act as a bearer reference — possession is enough, with no separate authentication — and a business MAY otherwise require authentication. ask stays independent of catalog.
• Messages — non-blocking notes from the shared vocabulary: info/not_found when a referenced item can't be resolved, warnings with presentation: "disclosure" for notices the platform MUST surface.
• No new primitives — reuses existing leaf types (context, signals, attribution, description, link, message); introduces no new shared types, enums, or monetary fields.

---

Checklist

• Capability: New schemas (Discovery, Cart, etc.) or extensions.
• Documentation: Updates to README, or documentations regarding schema or capabilities.
• I have followed the Contributing Guide
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• I have added tests that prove my fix is effective or that my feature works.

[jamesandersen]

I'm curious at the choice to model this as an array of possibly varied types of identifiers. I'd guess platforms will typically know what type of ID they'd be including and that it would be advantageous to send that context along to businesses (and their AI agents) as well e.g.

"ids": {
   "dev.ucp.product.id": [...],
   "dev.ucp.variant.url": [...]
}

If users are asking a business about products (one of the likely use cases noted) as similar structure could be used in the response to identify product / variant ids that could be immediately leveraged for catalog, cart or checkout capabilities.

[igrigorik]

UCP contract is that ids are self-describing GIDs (e.g. gid://Shopify/Product/...). The platform treats them as opaque IDs, but the business can differentiate between a product, variant, cart, etc. This allows us to keep single array and provide an array of grounding references -- which is a nice property.

For URLs it's a good flag, I'm borrowing from the contract we adopted in catalog lookup operation where we allow GIDs and other identifiers that business can recognize (e.g. GTIN, URL, etc). It is overloading ids but I'd like to see how far we can push it; URLs are also self-describing, which keeps the overall contract more or less consistent for the business.

[jamesandersen]

This could very well fall outside the scope of a "v1" of this capability ... but just to explore, what about an attachments property as another way to scope / ground / contextualize the conversation? e.g.:

• Do you have a sweater with patterns like this available?
• Can I get a refund when the lace on my shoe broke after 3 weeks of normal wear?

attachments: [<jpg data url>]

This could be useful where people are very comfortable snapping pictures from their phones as well as possible wearables use cases.

[igrigorik]

Great callout. Multi-modal input is definitely something we should model and consider, but agree that this may be a good v2 iteration: it'll likely require exposing a config on business schema, so we can communicate what type of attachments (image, audio, video, ...) are supported, etc. Added a note for this in the draft.

As an aside, "find me something like this image" is better handled in catalog as a visual-similarity input. As a live example, Shopify global catalog extension provides similarity search that accepts ID or image input.

[jamesandersen]

Nice! 💯

[igrigorik]

@jamesandersen great feedback, ty! Updated the draft, ptal.