JSON-RPC 2.0

## What JSON-RPC 2.0 is **JSON-RPC 2.0** is a stateless, lightweight remote procedure call protocol. Its specification defines a handful of JSON data structures and the rules for processing them, and nothing about the wire underneath. A **Client** is whatever originates Request objects and handles Response objects; a **Server** originates Responses and handles Requests. The core is two objects — the **Request** and the **Response** — and the `id` that ties one to the other. Several protocols, among them the Language Server Protocol, the Model Context Protocol and Ethereum node APIs, carry exactly these objects, so reading them by hand is a skill that transfers. Two conventions run through the text: member names are **case-sensitive**, and "Structured" means an Object or an Array, while "Primitive" means a String, Number, Boolean or Null. ## The Request object | Member | Required? | Rule | |---|---|---| | `jsonrpc` | yes | A String that MUST be exactly `"2.0"` | | `method` | yes | A String naming the method to invoke | | `params` | no | If present, MUST be Structured: an Array or an Object | | `id` | for a call | A String, Number or Null chosen by the Client | What each rule means in practice: - **By position**, `params` is an Array whose values arrive in the order the Server expects. - **By name**, `params` is an Object whose member names MUST match the expected parameter names exactly, including case; a missing expected name MAY produce an error. - **`params` may be omitted** for a method that takes nothing, but it may not be a bare String, Number, Boolean or Null — those are Primitives. - **Method names beginning with `rpc.`** (the word rpc followed by a period) are reserved for rpc-internal methods and system extensions and MUST NOT be used for anything else. - **`id`** SHOULD normally not be Null, and a Number id SHOULD NOT have a fractional part. - **Leaving `id` out** turns the Request into a notification, which gets no reply at all. ## The Response object Outside a batch, every call — every valid Request that carries an `id` — MUST be answered with one Response, a single JSON Object (inside a batch the specification softens this to SHOULD): 1. `jsonrpc`, again exactly `"2.0"`. 2. `id`, REQUIRED, the same value the Request carried. 3. Either `result` or `error`, and never both. `result` is REQUIRED on success and MUST NOT exist on error; `error` is REQUIRED on error, MUST NOT exist otherwise, and is an Object with an integer `code`, a short `message` and an optional `data`. The value of `result` is whatever the method returns; the specification constrains it no further. ## Correlation by id The `id` is the only thing linking a Response to its Request. The Server MUST reply with the same value, and the specification says the member "is used to correlate the context between the two objects". It promises nothing about the order in which separate requests are answered, and inside a batch it explicitly allows Responses in any order. So a Client keeps a table of the requests it has in flight, keyed by `id`, and settles each entry when a Response with that `id` arrives. The specification does not demand that ids be unique, but correlation only works if a Client never has two requests in flight under the same one. The two discouragements on `id` follow from that job: - **Null** is the value the Server itself writes when it could not determine a Request's `id` — after a parse error or an invalid Request. A Client that sends `"id": null` cannot tell its own answer from such a failure. JSON-RPC 1.0 also used a null id to mark notifications, a second source of confusion. - **Fractions** are discouraged because many decimal fractions have no exact binary representation, so an echoed value might not compare equal to the one sent. ## A worked exchange A call by position, and its answer: ```json {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1} {"jsonrpc": "2.0", "result": 19, "id": 1} ``` The same call by name, with a String id; the order of the named members does not matter: ```json {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": "q-7"} {"jsonrpc": "2.0", "result": 19, "id": "q-7"} ``` A call to a method the Server does not have still echoes the `id`, but carries `error` instead of `result`: ```json {"jsonrpc": "2.0", "method": "subtrakt", "params": [42, 23], "id": "q-8"} {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "q-8"} ``` ## Reading a message cold Handed an unfamiliar message, ask four questions in order: 1. Is `jsonrpc` present and exactly `"2.0"`? 2. Is there a `method` (a Request) or a `result` / `error` (a Response)? 3. For a Request, is there an `id` (a call, which will be answered) or not (a notification, which will not)? 4. For a Response, is exactly one of `result` and `error` present, and does its `id` match a request still in flight? Those four checks catch most malformed traffic before any method-specific logic runs, and they are the same whichever protocol happens to be carrying the objects.