Skip to content

feat: add operations field to capability schema and document capability-to-operation mapping#438

Open
oriliz wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
oriliz:feat/capability-operation-mapping
Open

feat: add operations field to capability schema and document capability-to-operation mapping#438
oriliz wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
oriliz:feat/capability-operation-mapping

Conversation

@oriliz
Copy link
Copy Markdown

@oriliz oriliz commented May 15, 2026

Problem

The Intersection Algorithm
produces a set of active capability names, but the protocol provides no
mechanism for platforms to resolve which transport operations those
capabilities enable. This forces SDK implementors to hard-code a static
capability→operation mapping outside the protocol — a gap that makes
capability negotiation incomplete at the machine-readable level.

Two layers are affected:

  • Declaration layer: A capability entry in a profile carries no
    information about which operations it drives. The capability is
    not self-describing.
  • Runtime layer: After intersection, a platform cannot
    programmatically determine the available operation set without
    out-of-band knowledge baked into the SDK.

No existing issue or PR addresses this. This PR proposes the minimal
change to close both gaps.

Solution

1. source/schemas/capability.json — add operations field

Add an operations: string[] field to the capability base schema.
Each value is an operation identifier that MUST match:

  • an operationId in the service's OpenAPI document (REST), or
  • a method name in the service's OpenRPC document (MCP).

The transport definition (already declared in the service's schema
field) resolves each operation ID to its concrete path and HTTP verb —
no path duplication needed in the capability entry.

Extensions MUST NOT declare operations; they augment the payload
of their parent capability's operations, not introduce new ones.

2. docs/specification/overview.md — new section after Intersection Algorithm

Add a "Capability-to-Operation Mapping" section specifying:

  • How root capabilities declare their operations
  • Rules for extensions
  • How platforms use the field to derive the available operation set
  • Fallback behavior when operations is absent (older profiles)

SDK integration point

During the discovery phase, when an SDK parses the business profile and
runs the intersection algorithm, it reads operations from each active
root capability and cross-references against the pre-fetched
OpenAPI/OpenRPC index (loaded from the service schema URL at startup).
The result is the session's available operation set — resolved entirely
in memory, with no additional network calls at invocation time.

Scope

This PR intentionally excludes the Embedded Protocol transport (ec.* /
ep.cart.* methods), whose event-driven naming convention differs
fundamentally from REST/MCP operationIds. That transport can be
addressed in a follow-up.

…ty-to-operation mapping

Platforms running the intersection algorithm receive a set of active
capability names but have no protocol-level mechanism to resolve which
transport operations those capabilities enable. This forces SDK
implementors to hard-code a static capability→operation mapping.

Add `operations` (string[]) to the capability base schema so root
capabilities can declare their operationIds explicitly. Each value
matches an `operationId` in the service's OpenAPI document (REST) or
a method `name` in the OpenRPC document (MCP); the transport definition
resolves the operation to its concrete path and HTTP verb.

Also add a "Capability-to-Operation Mapping" section to overview.md
that specifies the declaration format, rules for extensions (MUST NOT
declare operations), and the SDK resolution flow.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@oriliz oriliz requested review from a team as code owners May 15, 2026 14:42
@oriliz oriliz requested review from archrao and richmolj May 15, 2026 14:42
@google-cla
Copy link
Copy Markdown

google-cla Bot commented May 15, 2026

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant