JSON-RPC 2.0 仕様の日本語訳

業務で使うことになりそうなので、学習の記録として保存しておきます。

AIにやらせたら瞬殺ですが、ChatGPTは指示に従わずに省略したり要約したり誤訳したり、Perplexityは文の順序を入れ替えたりするため、忠犬Geminiを使いつつ、原文と照らし合せながら、可能な限り原文に忠実に（自動+目検）翻訳しました。仕様書の翻訳で省略とか要約とか文の順序入れ替えとかしないでくれ。

JSON-RPC 2.0は、MCPでも使用されている通信プロトコルで、JSON形式で双方向通信するシンプルなものです。

仕様自体もWEB１ページのみの簡単なものです。

JSON-RPC 2.0 Specification

JSON-RPC 2.0 仕様
１．概要（Overview）
２．規約（Conventions）
３．互換性（Compatibility）
４．リクエストオブジェクト（Request Object）
4.1 通知 (Notification)
4.2 パラメーター構造 (Parameter Structures)
５．レスポンスオブジェクト（Response Object）
5.1 エラーオブジェクト（Error Object）
６．バッチ（Batch）
７．例（Examples）
８．拡張（Extensions）
著作権（Copyright）条項

JSON-RPC 2.0 仕様

Origin Date:

2010-03-26 (based on the 2009-05-24 version)

Updated:

2013-01-04

Author:

JSON-RPC Working Group <json-rpc@googlegroups.com>

１．概要（Overview）

JSON-RPCは、ステートレスで軽量なリモートプロシージャコール（RPC）プロトコルです。
主にこの仕様書は、いくつかのデータ構造と、その処理に関するルールを定義しています。
同じプロセス内、ソケット経由、HTTP経由、または様々なメッセージング環境内でその概念を使用できるという点において、このプロトコルは通信手段を問いません。
データ形式としてJSON (RFC 4627)を使用します。
これはシンプルに設計されています！

２．規約（Conventions）

この文書中の “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, “OPTIONAL” といったキーワードは、RFC 2119 に記述されている通りに解釈されます。

JSON-RPCはJSONを利用するため、同じ型システムを持っています（http://www.json.orgまたはRFC 4627を参照）。JSONは、4つのプリミティブ型（文字列、数値、真偽値、null）と2つの構造化型（オブジェクト、配列）を表現できます。この仕様書における “Primitive” という用語は、これら4つのプリミティブなJSON型のいずれかを参照します。”Structured” という用語は、いずれかの構造化されたJSON型を参照します。この文書が何らかのJSON型を参照する場合、最初の文字は常に大文字になります：Object、Array、String、Number、Boolean、Null。
TrueとFalseも大文字です。

クライアントとサーバー間でやり取りされる、何らかのマッチングのために考慮されるすべてのメンバー名は、大文字と小文字を区別すると見なされるべきです。関数（function）、メソッド（method）、プロシージャ（procedure）という用語は、相互に交換可能であると見なすことができます。

クライアントは、リクエストオブジェクトの送信元であり、レスポンスオブジェクトのハンドラーであると定義されます。サーバーは、レスポンスオブジェクトの送信元であり、リクエストオブジェクトのハンドラーであると定義されます。

この仕様の実装は、他の異なるクライアントや同じクライアントに対して、これら両方の役割を、時には同時に簡単に満たすことができます。この仕様は、その複雑なレイヤーについては言及しません。

３．互換性（Compatibility）

JSON-RPC 2.0のリクエストオブジェクトおよびレスポンスオブジェクトは、既存のJSON-RPC 1.0クライアントまたはサーバーでは動作しない可能性があります。しかし、2.0には常に「jsonrpc」という名前のメンバーがあり、その文字列値は「2.0」であるのに対し、1.0にはそれがないため、2つのバージョンを区別することは容易です。ほとんどの2.0の実装は、1.0のピアツーピアやクラスヒンティングの側面は扱わないとしても、1.0のオブジェクトを処理することを検討すべきです。

４．リクエストオブジェクト（Request Object）

RPCコールは、サーバーにリクエストオブジェクトを送信することで表現されます。リクエストオブジェクトは以下のメンバーを持ちます：

jsonrpc

JSON-RPCプロトコルのバージョンを指定する文字列です。
厳密に「2.0」でなければなりません（MUST）。

method

呼び出されるメソッドの名前を含む文字列。「rpc」という単語にピリオド文字（U+002EまたはASCII 46）が続く名前で始まるメソッド名は、RPC内部メソッドと拡張用に予約されており、それ以外の目的で使用してはなりません（MUST NOT）。

params

メソッドの呼び出し中に使用されるパラメーター値を保持する構造化された値です。このメンバーは省略可能です（MAY）。

id

クライアントによって確立された識別子で、含まれる場合は文字列、数値、またはNULLの値を含まなければなりません（MUST）。含まれない場合、それは “通知 (notification)” とみなされます。値は通常、Nullであるべきではありません（SHOULD NOT）[1]。数値には小数部を含めるべきではありません（SHOULD NOT）[2]。

idが含まれている場合、サーバーはレスポンスオブジェクトに同じ値で応答しなければなりません（MUST）。このメンバーは、2つのオブジェクト間のコンテキストを関連付けるために使用されます。

[1] リクエストオブジェクトのidメンバーにNullを値として使用することは推奨されません。なぜなら、この仕様では不明なidを持つレスポンスに対してNullの値を使用するからです。また、JSON-RPC 1.0は通知（Notification）に対してid値としてNullを使用するため、処理に混乱を引き起こす可能性があります。

[2]多くの十進小数は二進小数として正確に表現できないため、小数部は問題となる可能性があります。

4.1 通知 (Notification)

通知は、「id」メンバーを持たないリクエストオブジェクトです。通知であるリクエストオブジェクトは、クライアントが対応するレスポンスオブジェクトに関心がないことを意味します。そういうわけで、クライアントにレスポンスオブジェクトを返す必要はありません。サーバーは、バッチリクエスト内にあるものを含め、通知に応答してはなりません（MUST NOT）。

通知は、返されるべきレスポンスオブジェクトを持たないため、定義上、確認可能ではありません。
そのため、クライアントはエラー（例：「Invalid params」、「Internal error」など）を認識することはありません。

4.2 パラメーター構造 (Parameter Structures)

存在する場合、RPCコールのパラメーターは、構造化された値として提供されなければなりません（MUST）。
これは、配列による位置指定、またはオブジェクトによる名前指定のいずれかです。

位置指定：paramsは配列でなければならず（MUST）、サーバーが期待する順序で値を含みます。

名前指定：パラメーターはオブジェクトでなければならず（MUST）、そのメンバー名はサーバーが期待するパラメーター名と一致しなければなりません。期待される名前の欠落は、エラーの生成につながる可能性があります（MAY）。名前は、大文字と小文字を含め、メソッドが期待するパラメーターと完全に一致しなければなりません（MUST）。

５．レスポンスオブジェクト（Response Object）

RPC コールがなされたとき、サーバは通知の場合を除いて、必ずレスポンスを返さなければなりません。レスポンスは、単一のJSONオブジェクトとして表現され、以下のメンバーを持ちます：

jsonrpc

JSON-RPCプロトコルバージョンを示す文字列。厳密に”2.0″ でなければなりません。

result

成功時にはこのメンバーは必須です（REQUIRED）。メソッドの呼び出し中にエラーがあった場合、このメンバーは存在してはなりません（MUST NOT）。このメンバーの値は、サーバーで呼び出されたメソッドによって決定されます。

error

エラー時にはこのメンバーは必須です（REQUIRED）。呼び出し中にエラーがトリガーされなかった場合、このメンバーは存在してはなりません（MUST NOT）。このメンバーの値は、セクション5.1で定義されているオブジェクトでなければなりません（MUST）。

id

このメンバーは必須です（REQUIRED）。リクエストオブジェクトのidメンバーの値と同じでなければなりません（MUST）。リクエストオブジェクトでidを検出するのにエラーがあった場合（例：Parse error/Invalid Request）、それはNullでなければなりません（MUST）。

resultメンバーまたはerrorメンバーのいずれか一方は含まれなければなりませんが（MUST）、両方のメンバーを含んではなりません（MUST NOT）。

5.1 エラーオブジェクト（Error Object）

※直訳だと複雑な表現となり理解しにくい箇所は、意味が変わらないように表現を変えてあります。

RPCコールでエラーが発生した場合、レスポンスオブジェクトは、以下のメンバーを持つerrorメンバー（値はオブジェクト）を含まなければなりません（MUST）：

code

発生したエラーのタイプを示す数値。これは整数でなければなりません（MUST）。

message

エラーの簡単な説明を提供する文字列。メッセージは簡潔な単一の文に限定されるべきです（SHOULD）。

data

エラーに関する追加情報を含む、プリミティブまたは構造化された値。これは省略可能です（MAY）。このメンバーの値はサーバーによって定義されます（例：詳細なエラー情報、ネストされたエラーなど）。

-32768から-32000までのエラーコードは、事前定義されたエラーのために予約されています。この範囲内にあるが、以下で明示的に定義されていないコードは、将来の使用のために予約されています。

エラーコードは次のURLで提示されているXML-RPCとほぼ同じです：http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

コード message 意味
-32700 “Parse error” サーバーによって無効なJSONが受信されました。JSONテキストの解析中にサーバーでエラーが発生しました。
-32600 “Invalid Request” 送信されたJSONは有効なリクエストオブジェクトではありません。
-32601 “Method not found” メソッドが存在しないか、利用できません。
-32602 “Invalid params” メソッドのパラメーターが無効です。
-32603 “Internal error” 内部的なJSON-RPCエラーです。
-32000 ～ -32099 Server error 実装定義のサーバーエラー用に予約されています。

残りの空きの部分は、アプリケーション定義のエラーに使用できます。

コード	message	意味
-32700	“Parse error”	サーバーによって無効なJSONが受信されました。JSONテキストの解析中にサーバーでエラーが発生しました。
-32600	“Invalid Request”	送信されたJSONは有効なリクエストオブジェクトではありません。
-32601	“Method not found”	メソッドが存在しないか、利用できません。
-32602	“Invalid params”	メソッドのパラメーターが無効です。
-32603	“Internal error”	内部的なJSON-RPCエラーです。
-32000 ～ -32099	Server error	実装定義のサーバーエラー用に予約されています。

６．バッチ（Batch）

複数のリクエストオブジェクトを同時に送信するために、クライアントはリクエストオブジェクトで満たされた配列を送信することができます（MAY）。

サーバーは、すべてのバッチリクエストオブジェクトが処理された後に、対応するレスポンスオブジェクトを含む配列で応答すべきです（SHOULD）。通知に対するレスポンスオブジェクトがあってはならない（SHOULD NOT）ことを除いて、各リクエストオブジェクトに対してレスポンスオブジェクトが存在すべきです（SHOULD）。サーバーは、バッチRPCコールを、任意の順序で、任意の並列度で処理する一連の同時タスクとして処理することができます（MAY）。

バッチコールから返されるレスポンスオブジェクトは、配列内で任意の順序で返されても良いものとします（MAY）。

クライアントは、各オブジェクト内のidメンバーに基づいて、一連のリクエストオブジェクトと、一連のレスポンスオブジェクトとの間のコンテキストを照合すべきです（SHOULD）。

バッチRPCコール自体が、有効なJSONまたは少なくとも1つの値を持つ配列として認識されない場合、サーバーからのレスポンスは単一のレスポンスオブジェクトでなければなりません（MUST）。クライアントに送信されるレスポンス配列にレスポンスオブジェクトが含まれていない場合、サーバーは空の配列を返してはならず（MUST NOT）、何も返すべきではありません（SHOULD）。

７．例（Examples）

書式：

--> サーバへ送信されたデータ
<-- クライアントへ送信されたデータ

定位置パラメータによるRPC呼出：

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

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

名前付きパラメータによるRPC呼出：

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

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

通知：

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

存在しないメソッドのRPC呼出：

--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}

不正なJSONによるRPC呼出：

--> {"jsonrpc": "2.0", "method": "foobar, "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 Request"}, "id": null}

RPC呼出バッチ、不正なJSON：

--> [
  {"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 Request"}, "id": null}

不正なバッチ（空ではない）によるRPC呼出：

--> [1]
<-- [
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
]

不正なバッチによるRPC呼出：

--> [1,2,3]
<-- [
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
]

RPC呼出バッチ：

--> [
        {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
        {"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
        {"foo": "boo"},
        {"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
        {"jsonrpc": "2.0", "method": "get_data", "id": "9"} 
    ]
<-- [
        {"jsonrpc": "2.0", "result": 7, "id": "1"},
        {"jsonrpc": "2.0", "result": 19, "id": "2"},
        {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
        {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "5"},
        {"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
    ]

RPC呼出バッチ（全て通知）：

--> [
        {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
        {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]}
    ]
<-- //Nothing is returned for all notification batches

８．拡張（Extensions）

「rpc.」で始まるメソッド名は、システム拡張のために予約されており、それ以外の目的で使用してはなりません（MUST NOT）。各システム拡張は、関連する仕様書で定義されています。すべてのシステム拡張は、オプションです（OPTIONAL）。

著作権（Copyright）条項

Copyright (C) 2007-2010 by the JSON-RPC Working Group

この文書とその翻訳はJSON-RPCの実装に利用することができ、複製して他者に提供することができます。また、この文書にコメントしたり、説明したり、その実装を助けたりする二次的な著作物も、上記の著作権表示とこの段落がそれらすべての複製物および二次的著作物に含まれることを条件に、いかなる種類の制限もなく、全体または一部を準備、複製、出版、および配布することができます。ただし、この文書自体はいかなる方法でも変更することはできません（may not be modified）。
上記で付与された限定的な許可は永続的であり、撤回されることはありません。
この文書およびここに記載されている情報は「現状のまま」（AS IS）で提供され、すべての明示的または黙示的な保証は否認されます。これには、本情報を使用してもいかなる権利も侵害しないという保証、または商品性や特定の目的への適合性に関する黙示的な保証が含まれますが、これらに限定されるものではありません。