起源时间: 2010-03-26(基于
2009-05-24版本)
更新: 2013-01-04
作者: JSON-RPC工作组
原文链
接: http://www.jsonrpc.org/specif
ication
翻译: leozvc
JSON-RPC是一个无状态且轻量级的
远程过程调用（RPC）协议。 本规范
主要定义了一些数据结构及其相关的
处理规则。它允许运行在基于
socket,http等诸多不同消息传输环境
的同一进程中。其使用 JSON（RFC
4627）作为数据格式。
它为简单而生 !
文档中关键字"MUST"、"MUST
NOT"、"REQUIRED"、"SHALL"、"S
HALL NOT"、"SHOULD"、"SHOULD
NOT"、"RECOMMENDED"、"MAY"
和 "OPTIONAL" 将在RFC 2119 中得
到详细的解释及描述。
由于JSON-RPC使用JSON，它具有与
其相同的类型系统（见
http://www.json.org或RFC 4627）。
JSON可以表示四个基本类型
（String、Numbers、Booleans和
Null）和两个结构化类型（Objects和
Arrays）。
规范中，术语“Primitive”标记那4种原
始类型，“Structured”标记两种结构化
类型。任何时候文档涉及JSON数据
类型，第一个字母都必须大写：
Object，Array，String，Number，
Boolean，Null。包括Tr ue和False也要
大写。
在客户端与任何被匹配到的服务端之
间交换的所有成员名字应是区分大小
写的。 函数、方法、过程都可以认
为是可以互换的。
客户端被定义为请求对象的来源及响
应对象的处理程序。
服务端被定义为响应对象的起源和请
求对象的处理程序。
该规范的一种实现为可以轻而易
举的填补这两个角色,即使是在同
一时间,同一客户端或其他不相同
的客户端。 该规范不涉及复杂
层。
JSON-RPC 2.0 的请求对象和响应对
象可能无法在现用的JSON-RPC 1.0
客户端或服务端工作，然而我们可以
很容易在两个版本间区分出2.0，总
会包含一个成员命名为 “jsonrpc” 且
值为“2.0”， 而1.0版本是不包含的。
大部分的2.0实现应该考虑尝试处理
1.0的对象，即使不是对等的也应给
其相关提示。
发送一个请求对象至服务端代表一个
rpc调用， 一个请求对象包含下列成
员：
jsonrpc
指定JSON-RPC协议版本的字符
串，必须准确写为“2.0”
me thod
包含所要调用方法名称的字符
串，以rpc开头的方法名，用英文
句号（U+002E or ASCII 46）连接
的为预留给rpc内部的方法名及扩
展名，且不能在其他地方使用。
params
调用方法所需要的结构化参数
值，该成员参数可以被省略。
id
已建立客户端的唯一标识id，值必
须包含一个字符串、数值或NULL
空值。如果不包含该成员则被认
定为是一个通知。该值一般不为
NULL[1]，若为数值则不应该包含
小数 [2] 。
服务端必须回答相同的值如果包含在
响应对象。 这个成员用来两个对象
之间的关联上下文。
[1] 在请求对象中不建议使用NULL作
为id值，因为该规范将使用空值认定
为未知id的请求。另外，由于JSON-
RPC 1.0 的通知使用了空值，这可能
引起处理上的混淆。
[2] 使用小数是不确定性的，因为许
多十进制小数不能精准的表达为二进
制小数。
4.1 通知
没有包含“id”成员的请求对象为通
知， 作为通知的请求对象表明客户
端对相应的响应对象并不感兴趣，本
身也没有响应对象需要返回给客户
端。服务端必须不回复一个通知，包
含那些批量请求中的。
由于通知没有返回的响应对象，所以
通知不确定是否被定义。同样，客户
端不会意识到任何错误（例如参数缺
省，内部错误）。
4.2 参数结构
rpc调用如果存在参数则必须为基本
类型或结构化类型的参数值，要么为
索引数组，要么为关联数组对象。
索引：参数必须为数组，并包含
与服务端预期顺序一致的参数
值。
关联名称：参数必须为对象，并
包含与服务端相匹配的参数成员
名称。没有在预期中的成员名称
可能会引起错误。名称必须完全
匹配，包括方法的预期参数名以
及大小写。
当发起一个rpc调用时，除通知之
外，服务端都必须回复响应。响应表
示为一个JSON对象，使用以下成
员：
jsonrpc
指定JSON-RPC协议版本的字符
串，必须准确写为“2.0”
re sult
该成员在成功时必须包含。
当调用方法引起错误时必须不包
含该成员。
服务端中的被调用方法决定了该
成员的值。
e rror
该成员在失败是必须包含。
当没有引起错误的时必须不包含
该成员。
该成员参数值必须为5.1中定义的
对象。
id
该成员必须包含。
该成员值必须于请求对象中的id成
员值一致。
若在检查请求对象id时错误（例如
参数错误或无效请求），则该值
必须为空值。
响应对象必须包含result或error成
员，但两个成员必须不能同时包含。
5.1 错误对象
当一个rpc调用遇到错误时，返回的
响应对象必须包含错误成员参数，并
且为带有下列成员参数的对象：
code
使用数值表示该异常的错误类
型。 必须为整数。
me ssage
对该错误的简单描述字符串。 该
描述应尽量限定在简短的一句
话。
data
包含关于错误附加信息的基本类
型或结构化类型。该成员可忽
略。 该成员值由服务端定义（例
如详细的错误信息，嵌套的错误
等）。
-32768至-32000为保留的预定义错误
代码。在该范围内的错误代码不能被
明确定义，保留下列以供将来使用。
错误代码基本与XML-RPC建议的一
样，url： http://xmlrpc-
epi.sourceforge.net/specs/rfc.fault_code
s.php
code
me ssage me aning
服务端接收
到无效的
Parse
error语
法解析
错误
json。该错误
发送于服务
器尝试解析
json文本
-32700
Invalid
Request
无效请
求
发送的json不
是一个有效
的请求对
象。
-32600
Method
not
-32601 found找
不到方
法
该方法不存
在或无效
Invalid
params
无效的
无效的方法
参数。
-32602
参数
Internal
-32603 error内
部错误
JSON-RPC内
部错误。
Server
-32000
预留用于自
to
error服
定义的服务
器错误。
-32099 务端错
误
除此之外剩余的错误类型代码可供应
用程序作为自定义错误。
当需要同时发送多个请求对象时，客
户端可以发送一个包含所有请求对象
的数组。
当批量调用的所有请求对象处理完成
时，服务端则需要返回一个包含相对
应的响应对象数组。每个响应对象都
应对应每个请求对象，除非是通知的
请求对象。服务端可以并发的，以任
意顺序和任意宽度的并行性来处理这
些批量调用。
这些相应的响应对象可以任意顺序的
包含在返回的数组中，而客户端应该
是基于各个响应对象中的id成员来匹
配对应的请求对象。
若批量调用的rpc操作本身非一个有
效json或一个至少包含一个值的数
组，则服务端返回的将单单是一个响
应对象而非数组。若批量调用没有需
要返回的响应对象，则服务端不需要
返回任何结果且必须不能返回一个空
数组给客户端。
语法:
--> data sent to Server
data sent to Client
带索引数组参数的rpc调用:
--> {"jsonrpc": "2.0", "method": "su
btract", "params": [42, 23], "id": 1
}
{"jsonrpc": "2.0", "result": 19, "i
d": 1}
--> {"jsonrpc": "2.0", "method": "su
btract", "params": [23, 42], "id": 2
}
{"jsonrpc": "2.0", "result": -19, "
id": 2}
带关联数组参数的rpc调用:
--> {"jsonrpc": "2.0", "method": "su
btract", "params": {"subtrahend": 23
, "minuend": 42}, "id": 3}
{"jsonrpc": "2.0", "result": 19, "i
d": 3}
--> {"jsonrpc": "2.0", "method": "su
btract", "params": {"minuend": 42, "
subtrahend": 23}, "id": 4}
{"jsonrpc": "2.0", "result": 19, "i
d": 4}
通知 :
--> {"jsonrpc": "2.0", "method": "up
date", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "fo
obar"}
不包含调用方法的rpc调用:
--> {"jsonrpc": "2.0", "method": "fo
obar", "id": "1"}
{"jsonrpc": "2.0", "error": {"code"
: -32601, "message": "Method not fou
nd"}, "id": "1"}
包含无效json的rpc调用:
--> {"jsonrpc": "2.0", "method": "fo
obar, "params": "bar", "baz]
{"jsonrpc": "2.0", "error": {"code"
: -32700, "message": "Parse error"},
"id": null}
包含无效请求对象的rpc调用:
--> {"jsonrpc": "2.0", "method": 1,
"params": "bar"}
{"jsonrpc": "2.0", "error": {"code"
: -32600, "message": "Invalid Reques
t"}, "id": null}
包含无效json的rpc批量调用:
--> [
{"jsonrpc": "2.0", "method":
"sum", "params": [1,2,4], "id": "1"
},
{"jsonrpc": "2.0", "method"
]
{"jsonrpc": "2.0", "error": {"code"
: -32700, "message": "Parse error"},
"id": null}
包含空数组的rpc调用:
--> []
{"jsonrpc": "2.0", "error": {"code"
: -32600, "message": "Invalid Reques
t"}, "id": null}
非空且无效的rpc批量调用:
--> [1]
[
{"jsonrpc": "2.0", "error": {"co
de": -32600, "message": "Invalid Req
uest"}, "id": null}
]
无效的rpc批量调用:
--> [1,2,3]
[
{"jsonrpc": "2.0", "error": {"co
de": -32600, "message": "Invalid Req
uest"}, "id": null},
{"jsonrpc": "2.0", "error": {"co
de": -32600, "message": "Invalid Req
uest"}, "id": null},
{"jsonrpc": "2.0", "error": {"co
de": -32600, "message": "Invalid Req
uest"}, "id": null}
]
rpc批量调用:
--> [
{"jsonrpc": "2.0", "method": "su
m", "params": [1,2,4], "id": "1"},
{"jsonrpc": "2.0", "method": "no
tify_hello", "params": [7]},
{"jsonrpc": "2.0", "method": "su
btract", "params": [42,23], "id": "2
"},
{"foo": "boo"},
{"jsonrpc": "2.0", "method": "fo
o.get", "params": {"name": "myself"}
, "id": "5"},
{"jsonrpc": "2.0", "method": "ge
t_data", "id": "9"}
]
[
{"jsonrpc": "2.0", "result": 7,
"id": "1"},
{"jsonrpc": "2.0", "result": 19,
"id": "2"},
{"jsonrpc": "2.0", "error": {"co
de": -32600, "message": "Invalid Req
uest"}, "id": null},
{"jsonrpc": "2.0", "error": {"co
de": -32601, "message": "Method not
found"}, "id": "5"},
{"jsonrpc": "2.0", "result": ["h
ello", 5], "id": "9"}
]
所有都为通知的rpc批量调用:
--> [
{"jsonrpc": "2.0", "method": "no
tify_sum", "params": [1,2,4]},
{"jsonrpc": "2.0", "method": "no
tify_hello", "params": [7]}
]
//Nothing is returned for all notif
ication batches
以rpc开头的方法名预留作为系统扩
展，且必须不能用于其他地方。每个
系统扩展都应该有相关规范文档，所
有系统扩展都应是可选的。
Copyright (C) 2007-2010 by the JSON-
RPC Working Group
This document and translations of it ma y
be used to i mpl ement JSON-RPC, it may
be copied and furnished to others, and
derivative works that c omme nt on or
otherwise explain it or assist in its
i mpl ementati on 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 bemodified in
any way.
