What Is JSON-RPC? – Definition and How It Works
Learn what JSON-RPC is, how requests, responses, notifications, and batching work, and where it is used — including by browser and tool protocols.
JSON-RPC is a remote procedure call protocol using JSON. It is deliberately minimal: a method name, parameters, an identifier, and a matching response — with no opinion about transport.
1. The Message Shapes
{"jsonrpc": "2.0", "method": "Page.navigate",
"params": {"url": "https://example.com"}, "id": 1}
{"jsonrpc": "2.0", "result": {"frameId": "ABC"}, "id": 1}
{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 1}
Each response carries exactly one of result or error, matched to its request by id.
2. Notifications
A message with no id is a notification: the receiver must not reply.
This is how event streams work in bidirectional deployments — a server pushes notifications as things happen, with nothing to correlate them against.
3. Batching
An array of request objects is processed as a batch, and the response is an array of results. Order is not guaranteed, so responses are matched by id rather than by position.
Batching reduces round trips, which matters most over high-latency connections such as a remote browser session.
4. Transport Independence
The specification says nothing about transport. In practice:
| Transport | Typical use |
|---|---|
| HTTP POST | Request-response APIs |
| WebSocket | Bidirectional, event-driven protocols |
| Standard input and output | Local processes, such as language and tool servers |
| Raw TCP | Embedded and internal systems |
That flexibility is why the same protocol appears in very different places.
5. Where You Will Meet It
- Chrome DevTools Protocol — browser automation is JSON-RPC over a WebSocket.
- Language Server Protocol — editors talking to language tooling over standard I/O.
- Model Context Protocol — tool servers exposing capabilities to model clients.
- Blockchain node APIs, which standardised on it early.
Anyone doing browser automation is using JSON-RPC continuously, usually without seeing it.
6. Error Codes
The specification reserves a range for protocol-level errors — parse errors, invalid requests, unknown methods, invalid parameters, internal errors — leaving the rest for applications.
Distinguishing protocol errors from application errors is genuinely useful when debugging: the former mean the message was wrong, the latter that the operation failed.
7. Compared With REST
REST models resources addressed by path and manipulated by HTTP method. JSON-RPC models procedures called by name, and does not use HTTP semantics even when it travels over HTTP.
For bidirectional, event-driven, or non-HTTP protocols, JSON-RPC fits where REST does not — which is why control protocols favour it and public data APIs favour REST.
8. Summary
JSON-RPC is a minimal, transport-independent remote procedure call protocol with requests, responses, notifications, and batching, matched by identifier.
Its simplicity and transport independence are why it underpins browser automation, editor tooling, and model tool servers — protocols that need bidirectional messaging rather than resource semantics.