JSON-RPC 2.0 calls itself transport agnostic — what does that leave a protocol carrying it over HTTP or a byte stream to define?

## What the specification defines — and where it stops The JSON-RPC 2.0 specification describes itself as **transport agnostic**: its concepts "can be used within the same process, over sockets, over http, or in many various message passing environments". What it actually defines is narrow: - the **Request**, **Notification**, **Response** and **Error** objects; - the **batch** Array and its reply rules; - the **reserved error codes** and the reserved `rpc.` method prefix; - the roles: a **Client** originates Requests and handles Responses, a **Server** does the reverse. It defines no framing, no HTTP binding, no connection life cycle, no authentication, no cancellation and no timeout. That is a deliberate scope, and it is why the same objects can sit under very different protocols — the Language Server Protocol, the Model Context Protocol and Ethereum node APIs among them — each of which supplies the missing parts in its own specification. ## The gaps a carrying protocol must fill | Concern | What JSON-RPC 2.0 says | Who decides | |---|---|---| | Message boundaries on a byte stream | Nothing | The carrying protocol | | HTTP method, status codes, headers | Nothing | The carrying protocol or the implementation | | What HTTP returns for a notification | Nothing; JSON-RPC sends no Response | The carrying protocol or the implementation | | Which side may send Requests | One implementation may fill both roles; "this specification does not address that layer of complexity" | The carrying protocol | | Uniqueness of ids | Nothing beyond "established by the Client" | The Client, as the carrying protocol requires | | Cancellation and timeouts | Nothing | The carrying protocol | | Authentication and sessions | Nothing | The carrying protocol or the deployment | ## Over HTTP JSON-RPC 2.0 has no HTTP section at all. (JSON-RPC 1.0 had one, describing serialized objects sent in HTTP POST bodies; 2.0 dropped it along with 1.0's stream rules.) The consequences are concrete: - **Status codes are not specified.** No code is required for `-32601` or any other error. Some implementations answer 200 and let the `error` member carry the failure; others map selected errors onto HTTP statuses. Neither is a JSON-RPC rule. - **The body is authoritative.** The JSON-RPC outcome of a call is the Response's `result` or `error`. An HTTP status is at most an extra signal the carrying protocol chooses to add, and a client that reads only the status misses what the specification actually says happened. - **Silence needs an HTTP shape.** HTTP pairs each request with a response, but JSON-RPC sends nothing for a notification or an all-notification batch, so the carrying protocol must decide what that HTTP response looks like. ## Over a bidirectional stream On a socket or a pair of pipes, both ends can send at any time, and the specification allows one implementation to act as Client and Server at once. Three things then need care: 1. **Framing.** A byte stream has no message boundaries, and JSON-RPC defines none. The carrying protocol picks a technique — a length header in front of each message, or a delimiter between messages — and every reader must follow it. 2. **Telling Requests from Responses.** The objects themselves say which is which: a Request has a `method` member (and an `id` unless it is a notification), while a Response has `result` or `error` and no `method`. 3. **Two id spaces.** Each side establishes the ids of the Requests it sends, and matches incoming Responses only against those. Both sides may use 1, 2, 3 without collision, because a Response always travels back to the side that sent the Request. ## Correlation, cancellation and lost responses The specification ties a Response to a Request by `id` and says nothing about how long to wait. Nor does it say ids must be unique, but a Client that has two requests in flight under one `id` cannot tell their Responses apart. A stuck call cannot be cancelled by anything JSON-RPC defines; protocols that need cancellation define it themselves, for example as a notification naming the `id` to abandon. Whether a call whose Response never arrived may be sent again is a question of invocation semantics under failure, not something this specification addresses. ## A checklist for a new protocol on JSON-RPC 2.0 1. Name the transport and its framing. 2. If HTTP is involved, fix the method, the media type, the status-code policy and what a notification gets back. 3. State which side may send Requests and whether both may. 4. Specify id rules: type, uniqueness among requests in flight, and whether null is forbidden. 5. Define cancellation, timeouts and the connection's start and end. 6. Define the application error codes, outside the reserved band. A protocol that answers all six is complete enough to implement twice and interoperate; one that answers only "it is JSON-RPC" is not.