chore: Refactor schema references to common types

[amithanda]

refactor: move generic types from shopping/ to common/types/

Rationale

All types currently live under shopping/types/, but many of them carry no shopping-specific semantics. As UCP is envisioned to expand to other verticals beyond shopping, those verticals will need the same primitives — money amounts, addresses, pagination, messaging, rich text — without taking a dependency on the shopping namespace. This refactor establishes common/types/ as the canonical home for types that belong to the protocol, not to a vertical.

This also fixes a pre-existing namespace violation: common/identity_linking.json was referencing ../shopping/types/description.json, which is the exact problem this refactor corrects structurally.

---

Phases to do the refactor

Phase 1 — Pure primitives

No vertical semantics. Any future capability will need these.

amount, signed_amount, price, description, media, postal_address, pagination, reverse_domain_name, link, buyer

Phase 2 — Protocol messaging infrastructure

UCP's error/warning/info messaging pattern. Every vertical reuses this plumbing verbatim.

message, message_error, message_warning, message_info, error_response, error_code, warning_code, info_code

Phase 3 — Cross-vertical candidates (future PR)

Strong candidates with clear cross-vertical semantics, deferred to validate design stability first.

attribution, signals, context, rating

Phase 4 — Transactional primitives (future PR)

Financial breakdown types whose schema may need to evolve per vertical before being promoted.

total, totals, price_range, price_filter

Phase 5 - Payment types (future PR)

payment_instrument, payment_credential, payment_identity, card_credential, card_payment_instrument, token_credential, available_payment_instrument — these are cross-vertical but domain-specific. Should they be in their own payment/types/ namespace?

---

This PR (Phase 1 + Phase 2)

• Creates source/schemas/common/types/ with 18 new files, each with updated $id (https://ucp.dev/schemas/common/types/...)
• Deletes the 18 originals from source/schemas/shopping/types/
• Updates all $ref paths in:
  • shopping/types/*.json (remaining shopping types that reference moved types)
  • shopping/*.json (capability schemas: cart, checkout, order, fulfillment, etc.)
  • source/schemas/ucp.json
  • source/schemas/common/identity_linking.json (fixes pre-existing violation)
  • source/services/shopping/ (OpenRPC and OpenAPI service definitions)
• Adds source/schemas/common to SCHEMAS_DIRS in main.py so the docs macro system resolves moved types correctly

No schema semantics were changed — this is a pure relocation with path updates.

[jamesandersen]

thanks @amithanda for setting these types up for more broad use

[igrigorik]

TY for restoring error codes, that was my main flag on firt pass.

Pedantic nice: technically this change may be breaking because we're changing $id pointers and URLs from published schemas. If any code or validators cached that state, they'll get 404's. My intuition is that we should be OK, but this is something to watch out for... let's see if and what breaks.

Question: how do we want to distinguish, or not, common vs domain-specific schemas? Right now they're indistinguishable in how we render then in our tables. Should we separate and note that some are common vs not? This also connects to my flag on main.py behavior where we can end up in shadow / duplicate schemas unless we put some strict guards around it.

[amithanda]

Question: how do we want to distinguish, or not, common vs domain-specific schemas? Right now they're indistinguishable in how we render then in our tables. Should we separate and note that some are common vs not? This also connects to my flag on main.py behavior where we can end up in shadow / duplicate schemas unless we put some strict guards around it.

You're right that the reference page currently renders all types indistinguishably:
Type Schemas
Amount ← common/types/ (no label)
Buyer ← shopping/types/ (no label)
Message ← common/types/ (no label)
Product ← shopping/types/ (no label)
This matters for implementors building non-shopping verticals who need to know at a glance which types
are safe to reuse. Fixing it requires changes to reference.md and auto_generate_schema_reference
(section split, or a "Common" badge, or both). Intentionally leaving this for a follow-up so the
presentation choice gets proper discussion rather than being decided quietly inside a refactor PR.

Shadow/duplicate schema guard

Implemented — but we scoped the guard more narrowly than your suggestion after thinking through the
multi-vertical future. PTAL at my other comment.

[amithanda]

Following up on @yanheChen and @jingyli's comments — agreed that buyer carries shopping-domain
semantics and shouldn't be declared a cross-vertical primitive prematurely.

Reverted buyer back to shopping/types/ in this PR. The reasoning:

• The name encodes a purchase transaction — it may not generalize cleanly to other verticals
• Promoting it to common/ would lock in shopping-centric field names (first_name, last_name,
  email, phone_number) as the universal person model before UCP has any non-shopping verticals
  to validate that shape against
• The right pattern is to introduce a neutral type (e.g. party or contact) when the first
  non-shopping vertical is designed and its person-identity requirements are actually known — not
  to rename a shopping type preemptively and carry the debt forward

common/types/ now contains 18 types, all of which have zero vertical-specific semantics. buyer
remains in shopping/types/ unchanged.

The neutral cross-vertical person type is tracked as a follow-up for when the first non-shopping
vertical is scoped.

[igrigorik]

@amithanda pushed a small improvement to the validation logic, please sanity check.

LGTM.

[amithanda]

@amithanda pushed a small improvement to the validation logic, please sanity check.

LGTM.

@igrigorik - Thanks for the cleanup and auto-discovery in 72eca50!

However, zooming out to the multi-vertical design, there is a fundamental gap in enforcing global filename uniqueness across all vertical namespaces:

1. Top-Level Capabilities Remain Unprotected: The current check only validates filenames under the types/ subdirectories. It does not protect capability schemas (e.g., checkout.json, order.json, fulfillment.json). If a second vertical introduces new-vertical/checkout.json alongside shopping/checkout.json, main.py will still suffer from the exact same silent resolution bug (loading whichever vertical appears first in SCHEMAS_DIRS for all pages) without triggering this guard.
2. Restrictions on Vertical Autonomy: Enforcing global name uniqueness forces different verticals to use different names for parallel concepts (e.g., we'd have to use new-vertical_status.json vs. shopping_status.json instead of clean, vertical-scoped types/status.json files).

Proposal: A Path-Aware Resolver

Instead of using strict filename constraints to workaround the resolver's flat-search design, we should make the resolver path-aware. We can inspect the MkDocs compilation context (env.page.file.src_path) to identify which vertical's documentation page is being compiled, and prioritize that vertical's folders in the lookup path.

Here is a quick sketch of how we can achieve this in main.py:

def get_active_vertical() -> str:
  try:
    # src_path is like "specification/new-vertical/checkout.md" 
    # or "specification/checkout.md" (defaults to shopping)
    src_path = Path(env.page.file.src_path)
    parts = src_path.parts
    if len(parts) > 2 and parts[0] == "specification":
      vertical = parts[1]
      # Verify against discovered verticals
      if vertical in [d.name for d in VERTICAL_DIRS]:
        return vertical
  except AttributeError:
    pass
  return "shopping"  # Default vertical fallback

Then, in _load_json_file(entity_name):

def _load_json_file(entity_name):
  """Try loading a JSON file prioritizing the active vertical."""
  active_vertical = get_active_vertical()
  
  # Construct prioritized search paths for the active vertical
  active_schemas_dir = SCHEMAS_DIR / active_vertical
  active_types_dir = active_schemas_dir / "types"
  
  search_dirs = []
  if active_types_dir.exists():
    search_dirs.append(active_types_dir)
  if active_schemas_dir.exists():
    search_dirs.append(active_schemas_dir)
    
  # Append remaining directories in standard order
  for d in schemas_dirs:
    if d not in search_dirs:
      search_dirs.append(d)
      
  # Resolve file
  for schemas_dir in search_dirs:
    full_path = Path(schemas_dir) / (entity_name + ".json")
    try:
      with full_path.open(encoding="utf-8") as f:
        return json.load(f)
    except FileNotFoundError:
      continue
  return None

Next Steps

If this looks good, we can:

1. Revert 72eca50 to remove the vertical-to-vertical type name constraints.
2. Keep the common vs. vertical uniqueness check (since a common type should never be shadowed by a vertical).
3. Implement this path-aware lookup, which guarantees that pages for any vertical will always resolve their own schemas correctly, without restricting filenames.

OR

We can come back and look at build time enforcement once we have some idea on the patterns that are emerging.

[igrigorik]

Restrictions on Vertical Autonomy: Enforcing global name uniqueness forces different verticals to use different names for parallel concepts (e.g., we'd have to use new-vertical_status.json vs. shopping_status.json instead of clean, vertical-scoped types/status.json files).

Right, I see this as a feature, not a bug. If we promote something to common, then let's not create a shadow override in sub-verticals -- that violates the contract of common.

[amithanda]

I think there are 3 issues we should discuss:

1. How should we generate documentation clearly for each vertical? (Path-Aware Resolver)

• The Problem:
  The MkDocs macro system (main.py) resolves JSON schemas by searching for their basenames (e.g., 'checkout' or 'types/status') across a flat list of directories configured in SCHEMAS_DIRS. The first folder match wins. When multiple verticals exist, this flat lookup causes silent cross-vertical rendering failures.

• Example (Silent Doc Corruption):
  Suppose we have a new vertical new-vertical alongside shopping, and both define a capability schema checkout.json:

1. source/schemas/shopping/checkout.json (defines shopping-specific lines, totals, cart links)
2. source/schemas/new-vertical/checkout.json (defines new-vertical-specific reservation details, identifiers)

Since new-vertical comes first alphabetically (or is ordered before shopping), source/schemas/new-vertical appears before source/schemas/shopping in SCHEMAS_DIRS.
When compiling the shopping checkout page, calling {{ schema_fields('checkout', 'checkout') }} will scan SCHEMAS_DIRS, find new-vertical/checkout.json first, and silently render the new-vertical schema on the shopping documentation page without any build warnings or errors.

• Recommended Solution:
  Implement a Path-Aware Resolver. We inspect the MkDocs compiler context (env.page.file.src_path) to identify which vertical's page is being built and prioritize that vertical's schema and types directories at the top of the search path.
• For page specification/new-vertical/checkout.md, search path starts with: [new-vertical/types, new-vertical]
• For page specification/checkout.md (shopping default), search path starts with: [shopping/types, shopping]

---

2. Should we enforce that vertical and common namespaces cannot have overlapping names?

• The Question:
  Should we allow a vertical to define a type name that already exists in the core protocol namespace (e.g., common/types/)?

• Example:
  If common/types/amount.json exists as the protocol's canonical definition of money, should a vertical be allowed to define source/schemas/shopping/types/amount.json?

• Recommendation:
  Enforce strict uniqueness (no overlaps).
  The common namespace defines universal protocol primitives. Shadowing a core common type with a vertical-specific version of the same name introduces severe developer confusion and breaks specification predictability. If a vertical needs a different shape, it should define a distinctly named type (e.g., types/billing_amount.json) or propose an update to the common type. We should maintain a build-time guard that fails fast on any common-to-vertical name collision.

---

3. Should we enforce that filenames be unique between different verticals?

• The Question:
  Should we force sibling verticals to have globally unique filenames across the entire codebase?

• Example:
  If the shopping vertical defines a type shopping/types/guest.json, should the new-vertical vertical be forbidden from defining a type new-vertical/types/guest.json?

• Recommendation:
  Allow overlapping names between verticals (do NOT enforce uniqueness).
  Each vertical represents a separate, modular application domain. Forcing different verticals to coordinate filenames globally goes against vertical autonomy and adds unnecessary prefix boilerplate (e.g., renaming files to shopping_guest.json and new-vertical_guest.json).

Once the Path-Aware Resolver (Point 1) is implemented, the documentation build will resolve vertical-specific files correctly based on the compilation context. Sibling verticals should have the freedom to design their namespaces independently using clean, intuitive terms.

[igrigorik]

@amithanda updated per our TC discussion, PTAL -- right shape?