Capabilities & Extensions

Reactions and playlists are not special cases; they're instances of the one extension mechanism — thecapability. This is why the core spec stays small: any interactive feature — comments, ratings, watch-later, recommendations — arrives as a capability following six rules, and existing deployments are untouched.

"capabilities": ["search", "changes", "progress", "reactions", "playlists"]

The six rules

1. A capability is a named bundle of endpoints, object shapes, and (if it writes) a <capability>.write scope, advertised as a keyword in the manifest's capabilities array. Every keyword is matched against acapability convention that fixes exactly what it applies to and which routes it mounts — the keyword carries no meaning beyond its convention, and providers cannot reinterpret it.
2. Every capability obeys the shared layers — transport and service token, the credential model, request conventions (pagination, caching, the error envelope), and, for writes, the write model. A new feature defines only its routes and objects; it never redefines auth, errors, or sync semantics.
3. Unknown capabilities are invisible. Consumers ignore capability names (and JSON fields) they don't recognize, and never fail on them. You can ship a new feature without breaking a single old client; a client gains the feature by learning the name.
4. Standard vs vendor. Standard names (search,changes, progress, reactions,playlists) are defined by the specification and only added there. Anything else uses an x_ prefix with a vendor tag —x_acme_comments — and should mount its routes under{api_base}/x/acme/… so vendor routes can never collide with future standard ones.
5. Additive within a major version. A capability may gain optional fields and routes freely; anything breaking means a new capability name (playlists2) or a protocol major bump. vcp_version alone never implies capability support — the capabilities array is the only source of truth.
6. Graduation path. A widely adopted vendor capability can be standardized: the spec adopts it under an unprefixed name, and providers advertise both names during the transition.

Manifest configuration for a vendor capability lives in an x_-prefixed manifest field:

{
  "capabilities": ["search", "x_acme_comments"],
  "x_acme_comments": {
    "moderation_url": "https://example.com/moderation"
  }
}

Capability conventions

A capability keyword is a switch over a fixed convention. Every convention — standard or vendor — fixes five facets:

The five standard conventions

¹ Including user-owned objects of every advertised write capability; change entries for those objects are scoped to the requesting identity.

Binding rules

1. Subjects are closed. A keyword applies its feature to the convention's subject and nothing else: reactions never implies reactions on playlists or collections. A feature on a different subject is a different keyword (e.g. a future playlist_reactions) with its own convention.
2. Advertised means fully implemented. Listing a keyword commits you to every route in the convention. There is no partial support; if you can't serve a route, omit the whole keyword.
3. Absent means off. Consumers never call a capability's routes, expect its response additions, or render its UI when the keyword is missing. Requests to unadvertised routes get 404 not_found.
4. Vendor capabilities follow the same template. An x_keyword's convention (published by its vendor) must fix the same five facets, with routes under /x/{vendor}/…. The gateway treats it identically — the keyword is the switch, the convention is the contract.