JSON-RPC 1.1 Wd

JSON-RPC 1.1 Working Draft 7 August 2006

JSON-RPC 1.1 Specification

Working Draft 7 August 2006

Previous Versions:
JSON-RPC 1.0
Editors:
Atif Aziz, www.raboof.com
Jan-Klaas Kollhof, jan.kollhof.net

This document is currently a working draft published with the intent of soliciting community feedback. Please send your comments and concerns to the public mailing-list JSON-RPC Yahoo! Group. Make sure you prefix the subject line with ?1.1WD:?, as in ?1.1WD: Comment on errors?.

This specification is designed to provide the developer with the information needed to implement the protocol on the client or server end of a communication bus.

Table of Contents

1. Overview

JSON-RPC is a stateless and light-weight remote procedure call (RPC) protocol for inter-networking applications over HTTP. It uses JSON as the data format for of all facets of a remote procedure call, including all application data carried in parameters.

By leveraging HTTP, JSON-RPC allows implementations to immediately benefit from the widely deployed World Wide Web infrastructure that is well-documented and understood today. It introduces no new HTTP verbs or message header extensions. JSON-RPC relies on JSON for the format of the HTTP message bodies, which allows implementations to benefit from a simple and standard text format that has suitable representations for the most commonly used scalar and structured data types inapplications. It is being quickly and widely adopted for web applications, and for which libraries are readily available in several languages.

The general mechanism for a remote procedure call using JSON-RPC consists of a client establishing a connection with a service and then invoking one or more procedures provided by that service. A single remote procedure call begins life as a request sent from the client to the server. The call ends when the client subsequently receives a response from the server over the same connection. Another call on the same connection is only made once the previous call has ended.

1.1. Goals

The primary goals of this specification are to define the JSON-RPC 1.1 protocol in terms of:

1.2. Non-Goals

JSON-RPC does not address security, correlation, reliability, sessions management, state management and many other features that may be found in other RPC protocols or distributed systems. Developers are instead encouraged to employ features of HTTP and related Internet technologies that can offer some of these features in an equally compelling, robust and satisfying manner. Some features may be defined as extensions by other specifications.

2. Differences From Version 1

The following list (non-comprehensive) summarizes the general changes that have been applied to version 1.0:

3. Requirements

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.

An implementation is not compliant if it fails to satisfy one or more of the MUST requirements for the protocols it implements. An implementation that satisfies all of the MUST and all of the SHOULD requirements for its features is said to be unconditionally compliant; one that satisfies all of the 'must' requirements but not all of the SHOULD requirements for its features is said to be conditionally compliant.

4. Terminology

Below is a summary of some terminology used in this documentation that can help in disambiguation of commonly applied and therefore often overloaded terms:

Client
The agent that is the initiator of the remote procedure call.
Server
Software that implements JSON-RPC, which may hosts one or more JSON-RPC services and which also acts as the gateway to lower-level protocols and transports.
Service
Provider of one or more procedures that may be the target of remote procedure calls by clients.
Procedure
A named operation on a service that may be the target of a remote procedure call. In this document, the terms method and procedure are used to mean the same thing.
Method
Same as Procedure.
Call
An invocation of a procedure on a service that results in a sequential request-response transaction between the client and the server.
Request
The message that frames a call and its parameters.
Response
The message that frames the result of a successful call or the error in the case of a failed call.
Result
The answer for a successful call.
Error
The answer for a failed call.
Notification
A one-way (fire and forget) call that produces no results, including any indication of error.

5. Type System

JSON-RPC shares the same type system as JSON to specify all value components of a call. In its abstract form (grammatic and syntatic details aside), JSON can represent four primitive types?String, Number, Booleans, and Null?and two structured types?Object and Array?that are briefly defined here:

String
A sequence of zero or more Unicode characters.
Number
An integer component optionally prefixed with a minus sign and which may be followed by a fraction part and/or an exponent part.
Boolean
Literally true or false.
Null
Literally null.
Array
An ordered sequence of zero or more elements, where each element hola value is a String, Number, Boolean, Null, Object or another Array. The index of the first element is zero and increments by one for each subequent element.
Object
An unordered collection of zero or more members. Each member is a name/value pair, where a name is a String, and a value is a String, Number, Boolean, Null, Array or another Object.

For the remainder of this document, it is expected that the reader has some familiarity with the basic syntax of JSON text. Otherwise, consult the JSON specification (RFC 4627) for further details.

Atif Aziz: It may be worth mentioning here how this specification makes a distinction between JSON, the abstract type system, and JSON text, the syntax for serializing the values. In XML parlance, JSON is the InfoSet and JSON text is the equivalent of XML 1.0.

This document also uses a specific convention to refer to any JSON type. Wherever a JSON type is mentioned, the first letter is always capitalized and the whole word appears in its root form (never in its plural form).

6. Procedure Call (Request)

A remote procedure call is made by sending a request to a remote service using either HTTP POST or HTTP GET. How and where the call is encoded within the HTTP message depends on the HTTP method that is employed. In the case of HTTP POST, the procedure call is carried in the body of the HTTP message whereas in the case of HTTP GET, it is expressed along the path and query components of the HTTP Request-URI.

Suppose that a service exposes a procedure named sum that takes two Number parameters, as in sum(a, b), and returns their sum. The HTTP POST to call this procedure call would be as follows:

Procedure Call Example Using HTTP POST
POST /myservice HTTP/1.1 
User-Agent: Wget/1.6
Host: www.example.com
Content-Type: application/json
Content-Length: 181
Accept: application/json

{
"version" : "1.1",
"method" : "sum",
"params" : [ 17, 25 ]
}

In this example, the method being targeted is provided by a service located at http://www.example.com/myservice. The call is expressed as a JSON Object in the body of the HTTP POST message. The version member of this object tells the receiver the version of the JSON-RPC protocol being used by the client. The method member indicates the procedure being invoked, which is sum in this example. Finally, the params member contains a JSON Array that lists the parameters (in order) to be supplied to the procedure.

The same invocation is shown here using HTTP GET:

Procedure Call Example Using HTTP GET
GET /myservice/sum?a=17&b=25 HTTP/1.1 
User-Agent: Wget/1.6
Host: www.example.com
Accept: application/json


There are two distinctions from the HTTP POST version that are improtant to note. First, an HTTP GET targeting a procedure on a JSON-RPC service is largely indistinguishable from a regular HTTP GET transaction. For this reason, there is no mention of of the JSON-RPC protocol version being used. Second, the entire call is encoded in the HTTP Request-URI. The procedure to invoke is appended to the location of the service, such that it appears as the last component of the URI path component. The call parameters appear as the query component and are named after the formal arguments of the target procedure.

6.1. HTTP Header Requirements

Regardless of whether a remote procedure call is made using HTTP GET or POST, the HTTP request message MUST specify the following headers:

6.2. Call Encoding Using HTTP POST

When using HTTP POST, the call is expressed in the HTTP request body as a JSON Object that carries the following members:

id
OPTIOINAL. A request identifier that can be of any JSON type. This member is essentially maintained for backward compatibility with version 1.0 of the specification where it was used to correlate a response with its request. If this member is present then the server MUST repeat it verbatim on the response.
version
REQUIRED. A String specifying the version of the JSON-RPC protocol to which the client conforms. An implementation conforming to this specification MUST use the exact String value of "1.1" for this member.
method
REQUIRED. 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. In other words, a procedure named system.foobar is considered to have reserved semantics.
Atif Aziz: Ideally, this member would have been named proc to reflect the procedure in RPC, but is being left as method for sake of compatibility. One could permit both, but that could unnecessarily increase complexity. In the text of this document, however, I have tried to stick to the term procedure. If anyone spots any use of the word method, except references to the membermethod, then please let me know.
params
OPTIONAL. An Array or Object that holds the actual parameter values for the invocation of the procedure.

Unless a call is for notification purposes only, bearing one-way semantics, it MUST be replied to with a response.

6.2.1. Named and Positional Parameters

Parameters for a procedure call can be identified by their name, position, or both. The name and position of a parameter is defined by the formal argument list of the target procedure. The first position is zero and increments by one for each subsequent formal argument.

A client can specify parameters by-name, by-position or both using a JSON Object as the value for the params member. Each member of this object becomes a candidate parameter for the call. If the name of the object member consists entirely of decimal digits (0-9) then it identifies the parameter by its position in the formal argument list. In all other instances, the member name identifies the parameter by its name and MUST match exactly (including in case) the name defined by the formal argument.

Suppose a remote procedure called sum that defines three formal arguments called a, b and c. Suppose further that a comes first in the argument list, b second and c third. The following example shows how this procedure would be called using named parameters in an HTTP POST transaction (the headers have been omitted from all examples in this section for sake of brevity):

Procedure Call With Named Parameters (1)
{
"version" : "1.1",
"method" : "sum",
"params" : { "a" : 12, "b" : 34, "c" : 56 }
}

Since parameters are identified by their name, the order is insignificant. The same MAY be expressed with parameters appearing in a different order than which is defined by the formal argument list:

Procedure Call With Named Parameters (2)
{
"version" : "1.1",
"method" : "sum",
"params" : { "b" : 34, "c" : 56, "a" : 12 }
}

A client MAY choose to send all or some of the paramters by-position, in or out of sequence. The example below shows the same call being expressed with parameters a and b named after their positions in the formal argument list:

Procedure Call With Named and Positional Parameters
{
"version" : "1.1",
"method" : "sum",
"params" : { "1" : 34, "c" : 56, "0" : 12 }
}

If a client chooses to send parameters exclusively by their position, then it MAY use a JSON Array for the params member of the Procedure Call object as a terser method:

Procedure Call With Positional Parameters Only (Using JSON Array)
{
"version" : "1.1",
"method" : "sum",
"params" : [ 12, 34, 56 ]
}

A server MUST accept all forms of parameter expressions described in this section. The last case, where parameters are sent in an array, was the only one supported in JSON-RPC 1.0. Servers conforming to JSON-RPC 1.1 can therefore continue to support calls from existing JSON-RPC 1.0 clients.

If the value of the params member is any other type except JSON Object or Array, then the server MUST reject the call with an error.

Atif Aziz: Need to add a comment about which error should be specifically returned if the params member is neither JSON Object or Array.

6.2.2. Choosing Between Named and Positional Parameters

Calls that identify all parameters exclusively by-name are RECOMMENDED over any positional parameters for the following reasons:

  1. The call appears more readable and self-contained on the wire, which can aid in logging and diagnosis without having to constantly consult the procudure definitions.
  2. The client gains independence from any change in the order of the formal argument list.
  3. If the formal argument list is large and mostly optional, the client can send only those parameters by-name that it needs to fulfill the purpose of a particular call.

6.2.3. Null Parameters

The Null value MAY be used as the value of any parameter and MUST be taken to mean that the parameter is not being supplied for the call.

6.2.4. Member Sequence

Client implementations SHOULD strive to order the members of the Procedure Call object such that the server is able to employ a streaming strategy to process the contents. At the very least, a client SHOULD ensure that the version member appears first and the params member last. An example how this can be an advantage is where a client tries to invoke a procedure that does not exist on the target service. The server can then skip to the end and issue an error as soon as it reads the value of the method member and finds it to be in error.

Atif Aziz: Allow a server to refuse a request if it does not wish to process a request where the params member appears before method.

6.3. Call Encoding Using HTTP GET

When using HTTP GET, the target procedure and parameters for the call are entirely expressed within the Request-URI of the HTTP message. The target procedure MUST appear as the last component of the Request-URI path component. The procedure's name MUST therefore be preceded by a forward-slash (U+002F or ASCII 47) but MUST NOT end in one.

The parameters are placed in the query component (as defined in RFC 3986) of the Request-URI, which is then formatted using the same scheme as defined for HTML Forms with the get method. Each parameters consists of a name/position and value pair that is separated by the equal sign (U+003D or ASCII 61) and parameters themselves are separated by an ampersand (U+0026 or ASCII 38):

name1=value1&name2=value2&name3=value3?

A client MAY send the parameters in a different order than in which the formal argument list of the target procedure defines them.

6.3.1. Encoding of Call Parameter Values

The client MUST NOT use the JSON syntax for the parameter values. All values MUST be plain text and observe the escaping rules defined for the query component of the URL. After decoding, the server MUST treat all values as if they were sent as JSON String values. The server MAY then perform conversions at its discretion (on a best-attempt basis) if the formal arguments of the target procedure expects other non-String values. This specification does not define any conversion rules or methods.

Parameters named identically on the query string MUST be collapsed into an Array of String values using the same order in which they appear in the query string and identified by the repeating parameter name. For instance, the following query string specifies two parameters only, namely scale and city:

city=london&scale=farenheit&city=zurich&city=new+york

The parameter scale has the single String value of "farenheit" whereas city is an Array of String values equivalent to the JSON text [ "london", "zurich", "new york" ].

It is specifically not possible to send parameters of type Object using HTTP GET.

6.3.2. Safe and Idempotent Procedures Only

Due to semantics and therefore requirements of HTTP GET, only procedures that are considered safe and idempotent MAY be invoked using HTTP GET. An explanation of what is considered safe and idempotent is provided in Section 9.1 (Safe and Idempotent Methods) of HTTP 1.1 specificiation. A server SHOULD provide a means (through a configuration file, for example) for a service to indicate which of its procedures are safe and idempotent in order to be callable using HTTP GET. In the absence of such means on the other hand, the server MUST allow invocations using HTTP POST only.

A server MUST respond with an error if a client attempts to invoke a procedure that has not been designated by the service as safe for call using HTTP GET.

A procedure callable using HTTP GET SHOULD also be callable using HTTP POST.

6.4. Choosing Between HTTP POST and GET

The choice of the HTTP method for a remote procedure call depends on the consequences of calling the procedure as well as the benefits afforded by each of the two HTTP methods. In general, any remote procedure call can be made using HTTP POST, but some benefits

HTTP GET can be particularly useful when:

6.5. Case-Sensitivity of Procedure and Parameter Names

Conforming implementations MUST treat procedure and parameter names as being case-sensitive such the names bar and BAR would be seen as two distinct entities.

6.6. Procedure Call Parity

The parity of a procedure call is defined by how closely it matches the target procedure's formal definition and argument list. A call is on full parity with the target procedure when it meets all of the following conditions:

  1. All parameters were supplied and none had the Null value.
  2. No extra parameters were supplied.
  3. The values for each parameter matched exactly the expected type.

Note that when parameters are named by-position or by-name, their sequence does not change or contribute to the parity of the call. A call can have full parity with its procedure even if the parameters were not sent in the sequence of the formal argument list.

6.6.1. Call Approximation

A server SHOULD try to adapt a call such that it has the greatest chance of succeeding by making the following adjustments for the actual invocation:

7. Procedure Return (Response)

When a remote procedure call is made, the service MUST reply with a response whether the invocation was successful or not.

7.1. HTTP Status Code Requirements

When the call is made using HTTP POST, the HTTP status code for a successful result MUST be 200.

When the call is made using HTTP GET, the HTTP status code for a successful result SHOULD be 200. If the HTTP GET call requested cache validation as well, the response MAY be 304 (Not Modified). The use of status codes generally related to redirection (e.g., 302 ?Found? or 301 ?Moved Permanently?) of HTTP GET transactions is not strictly prohibited, but service providers are RECOMMENDED instead to use public documentation and communication methods to advertise the relocation of a service.

Clients SHOULD be prepared to handle a status code of 401 (Unauthorized) resulting from an authentication challenge when a call is sent anonymously.

Unless noted otherwise, a status code of 500 (Internal Server Error) MUST be used under the following conditions:

7.2. HTTP Header Requirements

Regardless of the HTTP method used to make the remote procedure call, the HTTP response message MUST specify the following headers:

7.3. Procedure Return Object

Regardless of the HTTP method used to make the remote procedure call, the response body MUST be a JSON Object that carries the following properties or members:

id
OPTIONAL. This MUST be the same value as that of the id member of Procedure Call object to which the response corresponds. This member is maintained for backward compatibility with version 1.0 of the specification where it was used to correlate a response with its request. If the id member was present on the request, then the server MUST repeat it verbatim on the response.
version
REQUIRED. A String specifying the version of the JSON-RPC protocol to which the client conforms. An implementation conforming to this specification MUST use the exact String value of "1.1" for this member. The absence of this member can effectively be taken to mean that the remote server implement version 1.0 of the JSON-RPC protocol.
result
REQUIRED on success. The value that was returned by the procedure upon a successful invocation. This member MUST be entirely omitted in case there was an error invoking the procedure.
error
REQUIRED on error. An Object containing error information about the fault that occured before, during or after the call. This member MUST be entirely omitted if there was no error.

Only one of result or error members MUST be specified, but never both. If both are missing, then the Procedure Return should be treated as if it had the value Null.

Procedure Return Example
HTTP/1.1 200 OK
Connection: close
Content-Length: 23
Content-Type: application/json
Date: Sat, 08 Jul 2006 12:04:08 GMT
Server: Microsoft-IIS/6.0

{
"version" : "1.1",
"result" : 42
}

7.4. Error Object

When a remote procedure call fails, the Procedure Return object MUST contain the error member whose value is a JSON Object with the following properties members:

name
REQUIRED. A String value that MUST read "JSONRPCError".
code
REQUIRED. A Number value that indicates the actual error that occurred. This MUST be an integer between 100 and 999.
message
REQUIRED. A String value that provides a short description of the error. The message SHOULD be limited to a single sentence.
error
OPTIONAL. A JSON Null, Number, String or Object value that carries custom and application-specific error information. Error objects MAY be nested using this property.
Error Procedure Return Example
{
"version" : "1.1",
"error" : {
"name" : "JSONRPCError",
"code" : 123,
"message" : "An error occurred parsing the request object.",
"error" : {
"name" : "JSONError",
"message" : "Bad array",
"at" : 42,
"text" : "{\"id\":1,\"method\":\"sum\",\"params\":[1,2,3,4,5}"}
}
}

The following table lists the errors codes defined by this specification:

code Example MessageMeaning
000 Server error A general error occurred on the server prior to procedure invocation on the service.
000 Parse error An error occurred on the server while parsing the JSON text comprising the procedure call.
000 Bad call The procedure call is not valid.
000 Call member out of sequence The server refuses to process the call because a member is not in the required sequence. For example, the params member of the Procedure Call object appeared before version or method members.
000 Service error The call is valid, but a general error occurred during the procedure invocation.
000 Procedure not found The call is valid but the procedure identified by the call could not be located on the service.
Atif Aziz: Assign error codes and add a passage on how they should be interpreted. Particularly, which error codes indicate that a call must not be repeated verbatim without some change.

8. Processing Model

The processing model for the treatment of a remote procedure call is outlined as follows:

9. Services

A JSON-RPC service MUST, at a mimum, support a procedure called system.describe. The result of calling this procedure without any parameters MUST be a Service Description object as described in the next section.

10. Service Description

A service description is a JSON Object with the following members or properties:

sdversion
REQUIRED. A String value that represents the version number of this object and MUST read "1.0" for conforming implementations.
name
REQUIRED. A String value that provides a simple name for the method.
id
REQUIRED. A String value that uniquely and globally identifies the service. The string MUST use the URI Generic Syntax (RFC 3986).
version
OPTIONAL. A String value that indicates version number of the service and MAY be used by the applications for checking compatibility. The version number, when present, MUST include a major and minor component separated by a period (U+002E or ASCII 46). The major and minor components MUST use decimal digits (0 to 9) only. For example, use "2.5" to mean a major version of 2 and a minor version of 5. The use and interpretation of the version number is left at the discretion of the applications treating the Service Description.
summary
OPTIONAL. A String value that summarizes the purpose of the service. This SHOULD be kept to a maximum of 5 sentences and often limited a single phrase like, ?The News Search service allows you to search the Internet for news stories.?
Atif Aziz: Not sure if summary has any useful purpose in a service description. There is the help member to serve a similar purpose anyhow. Also, without this member being typed as Object, it is difficult to imagine how to communicate the language of the text unless one includes a language member (which starts to make things messy).
help
OPTIONAL. A String value that is a URL from where human-readable documentation about the service may be obtained.
address
OPTIONAL. A String value that is the URL of the service end-point to which the remote procedure calls can be targeted. The protocol scheme of this URL SHOULD be http or https. Although this value is optional, it is highly RECOMMENDED that a service always publish its address so that a service description obtained indirectly can be used nonetheless to locate the service.
procs
OPTIONAL. An Array value whose element contain Service Procedure Description objects, each of uniquely describes a single procedure. If the only description of each procedure that a service has is its name, then it MAY instead supply an Array of String elements for this member and where each element uniquely names a procedure.

A service SHOULD NOT include the system.describe procedure in its description as it is assumed that all conforming services MUST support it.

10.1. Service Procedure Description

A procedure description is a JSON Object with the following members and properties:

name
REQUIRED. A String value that provides a simple name for the method.
summary
OPTIONAL. A String value that summarizes the purpose of the service. This SHOULD be kept to a maximum of 3 sentences and often limited to a single phrase like, ?Lets you search for hyperlinks that have been tagged by particular tags.?
Atif Aziz: Not sure if summary has any useful purpose in a service procedure description. There is the help member to serve a similar purpose anyhow. Also, without this member being typed as Object, it is difficult to imagine how to communicate the language of the text unless one includes a language member (which starts to make things messy).
help
OPTIONAL. A String value that is a URL from where human-readable documentation about the procedure may be obtained.
idempotent
OPTIONAL. A Boolean value that indicates whether the procedure is idempotent and therefore essentially safe to invoke over an HTTP GET transaction. This member MUST be present and true for the procedure to be considered idempotent.
params
OPTIONAL. An Array value whose elements are either Procedure Parameter Description objects or String values. If an element each of uniquely describes a single parameter of the procedure. If the only description that is available of each parameter is its name, then a service MAY instead supply an Array of String elements for this member and where each element uniquely names a parameter and the parameter is assumed to be typed as "any". In either case, the elements of the array MUST be ordered after the formal argument list of the procedure being described. If this member is missing or the Null value then the procedure does not expect any parameters.
return
OPTIONAL. An Object value that is structured after the Procedure Parameter Description and which describes the output from the procedure. Otherwise, if it is a String value, then it defines the type of the return value. If this member is missing or is the Null value then the return type of the procedure is defined to be "any".

10.2. Procedure Parameter Description

A procedure description is a JSON Object with the following members and properties:

name
REQUIRED. A String value that provides a simple name for parameter.
type
OPTIONAL. A String value that denotes the expected value type for the parameter. If this member is not supplied or is the Null value then the type is defined "any".

10.2.1. Parameter and Return Type Strings

The type member of the Procedure Parameter Description MAY be one of the following String values:

"bit"
Boolean
"num"
Number
"str"
String
"arr"
Array
"obj"
Object
"any"
Boolean, Number, String, Array or Object
"nil"
None (valid only for procedure return type)

If another String value is found then it must be treated the same as "any".

The "nil" string MUST NOT be used to describe the type of a procedure's formal argument. Rather, it is strictly reserved to denote the return type of a procedure that is not expected to produce a result. In other words, the result member of the Procedure Return object resulting from a call to such procedure is not interesting because it will always be the Null value.

It is valid for a call to supply the Null value for any parameter no matter how it is typed in its description.

10.3. Service Description Example

Below is an example of Service Description object that describes a fictious DemoService service that resides at the address http://www.example.com/service and which publishes a single procedure called sum with two Number parameters, namely a and b, and which returns a Number result.

Service Description Example
{
"name" : "DemoService",
"id" : "urn:uuid:41544946-415a-495a-5645-454441534646",
"summary" : "A simple demonstration service.",
"help" : "http://www.example.com/service/index.html",
"address" : "http://www.example.com/service",
"procs" : [
{
"name" : "sum",
"summary" : "Sums two numbers.",
"help" : "http://www.example.com/service/sum.html",
"params" : [
{ "name" : "a", "type" : "num" },
{ "name" : "b", "type" : "num" } ],
"return" : {
"type" : "num"
},
{
"name" : "time",
"summary" : "Returns the current date and time in ISO 8601 format.",
"help" : "http://www.example.com/service/time.html",
"return" : {
"type" : "string"
}
]
}

10.4. Language of the Description Objects

The summary members of the Service Description and Procedure Description objects contain human-readable text. A service MAY use the Accept-Language header from the HTTP request message to deliver a localized text for its String value. Likewise, the URL for the help members MAY also point a page that contains the localized documentation. However, the documentation at the URL SHOULD also provide hyperlinks to the documentation in other languages if the translations are available.

11. Service, Procedure and Parameter Names

In JSON-RPC, service, procedure, parameters identifiable by name. The names of all these artifacts SHOULD only include:

All other characters in a name, although not technically excluded here, could severely limit the reach of the service and its procedures given certain environments, scenarios and especially programming languages.

12. Object Extensions

Objects defined in this specification (Procedure Call, Procedure Return, Error) MAY contain additional members not specifically mentioned. Such member names SHOULD be prefixed with the Dollar sign (U+0024 or ASCII 36), as in $extension.

Atif Aziz: The reason for choosing the Dollar sign is related to the JavaScript heritage. According to the ECMAScript Language Specification (ECMA-262), ?The Dollar sign is intended for use only in mechanically generated code.? Although the general convention in Internet protocols is to use the letter X followed by a dash (U+002D or ASCII 45), as in x-extension, the Dollar sign seems like a more natural and appropriate fit for JSON-RPC. Should we really be caring about the JavaScript/JSON heritage in a communication protocol? One downside of using Dollar sign is that it reserved in the Query component of the URI Generic Syntax (RFC 2396).
Atif Aziz: Add comment about CGI binding for extensions on the Procedure Call object?

13. Limitations

It is worth noting that JSON-RPC is limited by the inability to represent cyclic object graphs in JSON text. Therefore implementations SHOULD take care that parent-child, sibling and cross-reference relationships result in error at the client end when making the remote procedure call or server end when responding with the result of the call. There are two possible ways to control this:

As soon as either configured limit is breached, the client or server fail the call with an error.