fix!: make destination types explicit

[igrigorik]

This PR makes Fulfillment destination responses self-describing while preserving existing Platform shipping-address requests.

Destination type is required and open in Business responses. In Platform requests, the enclosing method contract defines destination authorship and any default shape:

• shipping accepts Platform-written Shipping Destinations; omitted destination type defaults to shipping_address;
• pickup destinations are Business-authored and response-only; the Platform selects one through selected_destination_id;
• other method types define their request destination shape and Platform writability in their defining contract.

The PR also introduces a bounded Location Summary that Checkout can render independently and #589 can extend with richer Location fields.

Context

Fulfillment originally used an untagged oneOf between Shipping Destination and Retail Location. The enclosing method suggested the intended shape, but every destination was validated against both branches.

The branches overlap: Shipping Destination is open and requires only id in responses, so every Retail Location also matches it and strict oneOf rejects intended pickup destinations. The old request shape also mixed authority: selected_destination_id could select one Location while Platform-written destinations[] asserted another name/address, with no precedence rule.

#507 opened the method vocabulary but left this debt unchanged. #589 exposes it again and adds a capability-boundary issue: Checkout must not inherit the full Location Search/Lookup entity and its independently evolving geo, hours, amenities, and service-area fields.

The directional contract is:

Direction/method	Destination behavior
Platform request, shipping	Platform writes Shipping Destination facts; omitted type defaults to shipping_address.
Platform request, pickup	Platform submits selected_destination_id; destinations are response-only.
Business response	Every destination includes required, open type.
Other method type	Its defining contract specifies request shape and Platform writability.

Wire changes

Shipping request — unchanged

{
  "type": "shipping",
  "line_item_ids": ["line_1"],
  "destinations": [
    {
      "street_address": "123 Main St",
      "address_country": "US"
    }
  ]
}

An ID-only saved or provider-held address remains a Shipping Destination. Provider provenance or extra fields require a negotiated extension contract.

Shipping response — typed

{
  "id": "method_shipping",
  "type": "shipping",
  "line_item_ids": ["line_1"],
  "destinations": [
    {
      "type": "shipping_address",
      "id": "address_1",
      "street_address": "123 Main St",
      "address_country": "US"
    }
  ]
}

Pickup request — scalar selection

{
  "type": "pickup",
  "line_item_ids": ["line_1"],
  "selected_destination_id": "loc_downtown"
}

Pickup response — typed Location summary

{
  "id": "method_pickup",
  "type": "pickup",
  "line_item_ids": ["line_1"],
  "selected_destination_id": "loc_downtown",
  "destinations": [
    {
      "type": "business_location",
      "id": "loc_downtown",
      "name": "Downtown Store",
      "address": {
        "street_address": "500 Market St",
        "address_country": "US"
      }
    }
  ]
}

What changes with this PR

• Moves request destination authorship to the Fulfillment Method contract.
• Keeps existing untyped Platform shipping-address requests valid.
• Requires open destination type in Business responses.
• Makes pickup destinations response-only; selection uses selected_destination_id.
• Requires method type when a request writes destinations[]; selection-only updates may target the method by id.
• Adds bounded Location Summary and Business Location Destination contracts.
• Generalizes Retail Location to Business Location Destination; retail stores remain supported alongside lockers and partner pickup points.

Catalog keeps its scalar Location ID. The same ID may be submitted as selected_destination_id for that method, including before it is enumerated in Checkout. The Business returns the typed destination when accepted and revalidates current terms; recognition is not a reservation or eligibility guarantee.

This is the Fulfillment prerequisite for #589. After it lands, #589 can compose its rich Location entity from location_summary.json, remove its direct Fulfillment rewrite, and keep discovery fields owned by Location Search/Lookup.

Resolver dependency

This schema depends on a companion ucp-schema --strict fix (see #689) that recursively closes item schemas inside conditional branches. Normal JSON Schema remains open; the fix makes strict mode apply its existing closure policy consistently.

Breaking changes

• Business response producers must add destination type.
• Retail Location responses migrate to type: "business_location".
• Platforms that wrote pickup destination objects must select through selected_destination_id.
• retail_location.json is retired; retail stores remain supported through Business Location Destination.

Existing untyped Platform Shipping Destination requests remain valid.

---

Checklist

• Capability: breaking Fulfillment schema update
• Documentation: directional request/response contract and examples
• I have followed the Contributing Guide
• Documentation, schema lint, examples, and validator tests pass locally.

[gsmith85]

Nit: Let "ucp_request": "optional" speak for itself and drop the redundant comment.

[gsmith85]

I have some concerns regarding using nested if/then conditional blocks inside allOf in fulfillment_method.json (and fulfillment_destination.json) from both schema maintainability and DevRel/SDK tooling perspective:

1. Schema Readability & Maintainability: Nested conditional logic inside allOf makes the JSON Schema significantly harder for humans to read, trace, and reason about when reviewing or extending protocol contracts.
2. SDK Code Generation & DX: Most standard SDK generators (datamodel-code-generator for Python/Pydantic, quicktype for TypeScript/Go/C#, openapi-generator, etc.) do not natively parse or resolve dynamic JSON Schema if/then conditionals. As a result, code generation tools either drop these branches, emit untyped Any / unknown arrays, or fail to produce clean discriminated unions.

[gsmith85]

I believe the intent here is to (i) avoid limiting the value of type (ii) while still adding the correctly typed destinations array either shipping_destination[] or location_destination[]) in recognized cases?

In the spirit of avoiding conditionals in our JSON Schema and keeping it simple(r) for code generation, I think that we can achieve the same result using an object-oriented approach.

fulfillment_method.json (Open Base Object)

Defines common fields shared across all fulfillment methods without imposing destination rules:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/fulfillment_method.json",
  "title": "Fulfillment Method",
  "type": "object",
  "ucp_shared_request": true,
  "required": ["id", "type", "line_item_ids"],
  "properties": {
    "id": { "type": "string", "ucp_request": {"create": "omit", "update": "optional"} },
    "type": {
      "type": "string",
      "description": "Fulfillment method type (e.g. shipping, pickup). Open vocabulary."
    },
    "line_item_ids": {
      "type": "array",
      "items": { "type": "string" },
      "ucp_request": {"create": "optional", "update": "required"}
    },
    "selected_destination_id": { "type": ["string", "null"] }
  }
}

shipping_fulfillment_method.json (Specialized Subtype)

Extends fulfillment_method.json via allOf, constrains "type": "shipping", and adds Platform-writable shipping destinations:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/shipping_fulfillment_method.json",
  "title": "Shipping Fulfillment Method",
  "type": "object",
  "ucp_shared_request": true,
  "allOf": [
    { "$ref": "fulfillment_method.json" },
    {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": { "type": "string", "const": "shipping" },
        "destinations": {
          "type": "array",
          "description": "Platform-authored shipping addresses.",
          "ucp_request": "optional",
          "items": { "$ref": "shipping_destination.json" }
        }
      }
    }
  ]
}

pickup_fulfillment_method.json (Specialized Subtype)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/pickup_fulfillment_method.json",
  "title": "Pickup Fulfillment Method",
  "type": "object",
  "ucp_shared_request": true,
  "allOf": [
    { "$ref": "fulfillment_method.json" },
    {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": { "type": "string", "const": "pickup" },
        "destinations": {
          "type": "array",
          "description": "Business-authored business locations. Response-only.",
          "ucp_request": "omit",
          "items": { "$ref": "location_destination.json" }
        }
      }
    }
  ]
}

A bit of an aside about polymorphism and this pattern: most of our SDK generators are going to be fine serializing from subtype -> JSON but will need custom code (cued off of type) to handle deserialization to JSON -> subtype. We are already doing this for fulfillment_method's current approach, so we'll need to make minor modifications to support this change.