Subprotocols Explained

Analogy categoryAnalogies

What a Subprotocol Actually Is

The base WebSocket protocol only defines how bytes are framed and how a connection opens and closes — it says nothing about what the payloads inside those frames mean. A subprotocol is an agreed-upon convention layered on top, such as the message format, field names, and interaction rules two parties will use, and it is negotiated during the handshake itself via the Sec-WebSocket-Protocol header, which the client sends as a comma-separated list of protocol names it supports and the server echoes back with the single one it has chosen to use, or omits entirely if it doesn't support any of them.

🏏

Cricket analogy: It's like two boards agreeing before a bilateral series whether they'll play under ICC playing conditions or a domestic variant with different powerplay rules — the pitch and stumps (the transport) are the same, but the rulebook governing play differs.

Negotiating a Subprotocol During the Handshake

The negotiation is intentionally simple: the client lists every subprotocol it's willing to speak, ordered by preference, and the server picks at most one from that list — it cannot invent a new name the client never offered, and it cannot select more than one. If the server includes a Sec-WebSocket-Protocol header in its 101 response, the client must treat the connection as using exactly that subprotocol; if the header is absent from the response, no subprotocol was agreed and the application must fall back to some default understanding or fail. This is commonly used to version an API (offering chat.v1 and chat.v2 simultaneously) or to let one WebSocket endpoint serve multiple distinct client types, like graphql-ws for GraphQL subscriptions versus a custom JSON protocol for a different feature.

🏏

Cricket analogy: It's like a toss-winning captain choosing to bat or bowl from the exact two options the coin toss presents — there's no third option to invent, and once chosen, both teams play the rest of the match under that single decision.

javascript

// Client offers two subprotocols, in preference order
const socket = new WebSocket('wss://api.example.com/ws', ['chat.v2', 'chat.v1']);

socket.addEventListener('open', () => {
  // The server picked exactly one; inspect it to know how to speak
  console.log('Negotiated subprotocol:', socket.protocol); // e.g. "chat.v1"
  if (socket.protocol === 'chat.v2') {
    socket.send(JSON.stringify({ v: 2, type: 'hello' }));
  } else if (socket.protocol === 'chat.v1') {
    socket.send(JSON.stringify({ type: 'hello' }));
  } else {
    // Empty string means the server didn't agree to any subprotocol
    socket.close(1002, 'No compatible subprotocol');
  }
});

Subprotocols vs. Extensions

It's easy to conflate subprotocols with extensions, but they solve different problems: extensions (negotiated via Sec-WebSocket-Extensions, like permessage-deflate) modify how frames themselves are transported — compression, multiplexing — and are meant to be transparent to the application layer, whereas a subprotocol defines what the application-level messages mean and is meaningful only to the application code, not the WebSocket implementation itself. A server can support several extensions and several subprotocols independently, and a client library like the browser's WebSocket constructor lets you specify subprotocols directly but has no way to request specific extensions, since those are typically handled transparently by the underlying implementation.

🏏

Cricket analogy: It's like the difference between the type of ball used (a transport-level detail affecting how the game physically plays, similar to an extension) versus the specific match format and points system being contested (an application-level agreement, similar to a subprotocol) — both matter, but they operate at different levels.

If your server supports multiple subprotocols but a client connects offering none (an empty array, or simply new WebSocket(url) with no second argument), the server must not send a Sec-WebSocket-Protocol header back. Code that blindly reads socket.protocol without checking for an empty string will misbehave — always verify the negotiated value before assuming a specific message format.

A subprotocol is an application-level messaging convention negotiated on top of the raw WebSocket framing protocol.
The client offers a comma-separated, preference-ordered list via Sec-WebSocket-Protocol; the server picks at most one.
If the server's 101 response omits Sec-WebSocket-Protocol, no subprotocol was agreed and the connection has no negotiated convention.
Subprotocols are commonly used for API versioning or to let one endpoint serve multiple distinct client types.
Extensions (like permessage-deflate) modify frame transport and are transparent to application code, unlike subprotocols.
Browser WebSocket clients can request subprotocols via the constructor's second argument but cannot request extensions directly.
Code should always check the negotiated socket.protocol value rather than assuming a subprotocol was accepted.