Search code examples
jsonrpcspecificationsjson-rpc

JSON RPC 2.0: Do Extra Fields on Request Objects Violate Specification?

I am writing a JSON RPC conform js library. Are clients allowed by the specification to add custom fields (e.g. headers) along the params field to Request objects?

E.g.

{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "headers": { "original-client": 12 }, "id": 1}

The spec (https://www.jsonrpc.org/specification#request_object) does not mention anything about adding additional fields.

Does my library violate the spec if it does add an header field?

Solution

  • Same question here. (I want to add user auth info / message signature...)

    You are right in that the Specification does not mention anything about additional fields. So legally-speaking, if it is not forbidden, it is allowed.

    On the other hand, I found at least one reference implementation here: www.simple-is-better.org/rpc/jsonrpc.py, which will hit you with an exception if a decoded message contains extra fields. This code is from one of the authors of the JSON-RPC 2.0 specs, Roland Köbler.

    So, YMMV.

    • If your library is only an internal building block for a proprietary system, go ahead.
    • If you need to interface with other JSON-RPC implementations, test each one.
    • If the library is intended for public use, don't do it.

    Edit: I solved this using the following protocol:

    • Before the "payload" message, send a standard-compliant notification with method "rpc.secinfo". (The rpc. prefix is per-spec reserved for extensions)
    • The "params" field contains whatever metadata applies (e.g. username, signature)
    • Example: {"jsonrpc": "2.0", "method": "rpc.secinfo", "params": {"user":"root", "signature":"0xDEADBEEF"}}<DELIM><payload><DELIM>
    • If header data is empty, No special method is pretended (i.e. behaves exactly like standard json-rpc).

    The receiver can decode the header message just like any other call, and just needs to apply (check sig, whatever) the header onto the following message.

    Discussion:

    • allows framing without touching payload
    • allows decoding the header without decoding payload
    • allows using byte-payload as is, particularly allows encrypted+literal payload to coexist (however encrypted payload breaks JSON-RPC compat!)
    • "Unaware" receiver: will throw the rpc.secinfo calls away silently or loudly, but is able to operate. Missing ID indicates a notification, i.e. receiver will not send response back per JSON-RPC spec.
    • "Unaware" sender: Received messages are valid, no-header messages.

    Feel free to reuse this protocol, but please credit this SO answer.