1.1   Thoughts about RPC

In my opinion, RPC consists of several independent parts:

1. data structure (how requests/responses/errors look like)
2. serializer (i.e. JSON, XML, URI, ...)
3. transport (i.e. Unix Domain Socket, TCP/IP, HTTP)
4. proxy/dispatcher

Unfortunately, these parts are often not treated as independent, which results in unnecessarily complex results [2]. A RPC-specification should only define point 1 ("data structure"), and tell the user which serialization to use [3].

1.2   Differences

2.1   Overview

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. It uses JSON (RFC 4627) as data format, and is transport-independent. It's designed to be simple!

2.2   Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Since JSON-RPC uses JSON, it shares the same type system as JSON (see http://www.json.org or RFC 4627). Whenever this document refers to any JSON type, the first letter is always capitalized: Object, Array, String, Number, True, False, Null.

All names (i.e. method-names or parameter-names) are case-sensitive.

Clients are the origin of Request objects. Servers are the origin of Response objects.

2.3   Request (Procedure Call)

A remote procedure call is made by sending a Request to a remote service. The Request is expressed as a single JSON Object, with the following members:

version

A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".

If version is missing, the server MAY handle the Request as JSON-RPC V1.0-Request.

method

A String containing the name of the procedure to be invoked.

Procedure names that begin with the word system followed by a period character (U+002E or ASCII 46) are reserved for system description / introspection.

params

An Array or Object (OPTIONAL), that holds the actual parameter values for the invocation of the procedure. Can be omitted if empty.

id

A Request identifier that SHOULD be a JSON scalar (String, Number, True, False), but not Null [4].

If omitted, the Request is a Notification.

This id can be used to correlate a Response with its Request. The server MUST repeat it verbatim on the Response.

Every Request, except Notifications, MUST be replied to with a Response.

2.4   Response (Procedure Return)

When a remote procedure call is made, the service MUST reply with a Response (except for Notifications). The Response is expressed as a single JSON Object, with the following members:

result

Required on success, omitted on failure.

The Value that was returned by the procedure. Its contents is entirely defined by the procedure.

This member MUST be entirely omitted if there was an error invoking the procedure.

error

Required on error, omitted on success.

An Object containing error information about the fault that occurred before, during or after the call.

This member MUST be entirely omitted if there was no such fault.

id

The same id as in the Request it is responding to. If there was an error before detecting the id in the Request, it MUST be Null.

Exactly one of result or error MUST be specified. It's not allowed to specify both or none.

For better compatibility with JSON-RPC 1.0-servers, a client MAY however accept both result and error if at least one of these is Null (like in the JSON-RPC 1.0-specification).

Note that there is no version-field. Since the Request already defines the version, there is no need of repeating this version in the Response.

If the server does not completely understand a Request (e.g. because of additional members), it MAY reject the Request (with "Invalid Request.").

2.5   Examples

Syntax:

--> data sent to service
<-- data coming from service

Procedure Call with positional parameters:

--> {"version": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"result": 19, "id": 1}

--> {"version": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"result": -19, "id": 2}

Procedure Call with named parameters:

--> {"version": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"result": 19, "id": 3}

--> {"version": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}
<-- {"result": 19, "id": 4}

Notification:

--> {"version": "2.0", "method": "update", "params": [1,2,3,4,5]}

--> {"version": "2.0", "method": "foobar"}

Procedure Call of non-existent procedure:

--> {"version": "2.0", "method": "foobar", "id": 10}
<-- {"error": {"code": -32601, "message": "Procedure not found."}, "id": 10}

Procedure Call with invalid JSON:

--> {"version": "2.0", "method": "foobar, "params": "bar", "baz"]
<-- {"error": {"code": -32700, "message": "Parse error"}, "id": null}

Procedure Call with invalid JSON-RPC:

--> [1,2,3]
<-- {"error": {"code": -32600, "message": "Invalid JSON-RPC."}, "id": null}

--> {"version": "2.0", "method": 1, "params": "bar"}
<-- {"error": {"code": -32600, "message": "Invalid JSON-RPC."}, "id": null}

2.6   System Description

Procedure names that begin with system. are reserved (see Request (Procedure Call)) for system description / introspection, and SHOULD not be used for anything else.

The Service Descriptions are defined in a related specification.

All Service Descriptions are OPTIONAL.

2.7   Extensions

There may be extensions, specified in related specification. (e.g. for: class-hinting, circular references, DateTime etc.)

All extensions are OPTIONAL.

Copyright (C) 2007 by ...

This document and translations of it may be used to implement JSON-RPC, it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way.

The limited permissions granted above are perpetual and will not be revoked.

This document and the information contained herein is provided "AS IS" and ALL WARRANTIES, EXPRESS OR IMPLIED are DISCLAIMED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.