types: improve "Request" and "Response" document based on JSON-RPC spec

Author: zchee

types.go

@@ -58,21 +58,34 @@ func (id *ID) UnmarshalJSON(data []byte) error {
 var _ json.Marshaler = (*ID)(nil)
 var _ json.Unmarshaler = (*ID)(nil)
 
-// Request is a request message to describe a request between the client and the server.
+// Request represents a rpc call by sending a request object to a Server.
+// This is a request message to describe a request between the client and the server.
 //
 // Every processed request must send a response back to the sender of the request.
 type Request struct {
-	// JSONRPC is a general message as defined by JSON-RPC.
+	// JSONRPC is a string specifying the version of the JSON-RPC protocol.
+	//
+	// MUST be exactly "2.0".
 	JSONRPC string `json:"jsonrpc"`
 
-	// The request id.
-	ID *ID `json:"id"`
-
-	// The method to be invoked.
+	// Method is a string containing the name of the method to be invoked.
+	//
+	// Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved
+	// for rpc-internal methods and extensions and MUST NOT be used for anything else.
 	Method string `json:"method"`
 
-	// The method's params.
+	// Params is a string containing the name of the method to be invoked.
+	//
+	// Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved
+	// for rpc-internal methods and extensions and MUST NOT be used for anything else.
 	Params *json.RawMessage `json:"params,omitempty"`
+
+	// ID is an identifier established by the Client that MUST contain a String, Number, or NULL value if included.
+	//
+	// If it is not included it is assumed to be a notification.
+	//
+	// The value SHOULD normally not be Null and Numbers SHOULD NOT contain fractional parts.
+	ID *ID `json:"id"`
 }
 
 // IsNotify returns true if this request is a notification.
@@ -81,57 +94,70 @@ func (r *Request) IsNotify() bool {
 }
 
 // Response is a response ressage sent as a result of a request.
+// When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications.
 //
 // If a request doesn't provide a result value the receiver of a request still needs to return a response message to
 // conform to the JSON RPC specification.
 // The result property of the ResponseMessage should be set to null in this case to signal a successful request.
 type Response struct {
-	// JSONRPC is a general message as defined by JSON-RPC.
+	// JSONRPC is a string specifying the version of the JSON-RPC protocol.
+	//
+	// MUST be exactly "2.0".
 	JSONRPC string `json:"jsonrpc"`
 
-	// The request id.
-	ID *ID `json:"id"`
+	// Result is the result of a request.
+	//
+	// This member is REQUIRED on success.
+	// This member MUST NOT exist if there was an error invoking the method.
+	//
+	// The value of this member is determined by the method invoked on the Server.
+	Result *json.RawMessage `json:"result,omitempty"`
 
-	// The error object in case a request fails.
+	// Error is the object in case a request fails.
+	//
+	// This member is REQUIRED on error.
+	// This member MUST NOT exist if there was no error triggered during invocation.
+	//
+	// The value for this member MUST be an Object.
 	Error *Error `json:"error,omitempty"`
 
-	// The result of a request. This member is REQUIRED on success.
-	// This member MUST NOT exist if there was an error invoking the method.
-	Result *json.RawMessage `json:"result,omitempty"`
+	// ID is the request id.
+	//
+	// This member is REQUIRED.
+	// It MUST be the same as the value of the id member in the Request Object.
+	//
+	// If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
+	ID *ID `json:"id"`
 }
 
 // Combined represents a all the fields of both Request and Response.
 type Combined struct {
-	// JSONRPC is a general message as defined by JSON-RPC.
-	JSONRPC string `json:"jsonrpc"`
-
-	// The request id.
-	ID *ID `json:"id,omitempty"`
-
-	// The method to be invoked.
-	Method string `json:"method"`
-
-	// The method's params.
-	Params *json.RawMessage `json:"params,omitempty"`
-
-	// The error object in case a request fails.
-	Error *Error `json:"error,omitempty"`
-
-	// The result of a request. This member is REQUIRED on success.
-	// This member MUST NOT exist if there was an error invoking the method.
-	Result *json.RawMessage `json:"result,omitempty"`
+	JSONRPC string           `json:"jsonrpc"`
+	Method  string           `json:"method"`
+	Params  *json.RawMessage `json:"params,omitempty"`
+	Result  *json.RawMessage `json:"result,omitempty"`
+	Error   *Error           `json:"error,omitempty"`
+	ID      *ID              `json:"id,omitempty"`
 }
 
 // NotificationMessage is a notification message.
 //
 // A processed notification message must not send a response back. They work like events.
 type NotificationMessage struct {
-	// JSONRPC is a general message as defined by JSON-RPC.
+	// JSONRPC is a string specifying the version of the JSON-RPC protocol.
+	//
+	// MUST be exactly "2.0".
 	JSONRPC string `json:"jsonrpc"`
 
-	// Method is the method to be invoked.
+	// Method is a string containing the name of the method to be invoked.
+	//
+	// Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved
+	// for rpc-internal methods and extensions and MUST NOT be used for anything else.
 	Method string `json:"method"`
 
-	// Params is the notification's params.
+	// Params is a string containing the name of the method to be invoked.
+	//
+	// Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved
+	// for rpc-internal methods and extensions and MUST NOT be used for anything else.
 	Params *json.RawMessage `json:"params,omitempty"`
 }