JSON-RPC 2.0 Specification comments
Nuutti Kotivuori
Hello,
I have some comments to the JSON-RPC 2.0 Specification. The changes are
not major or that important, but since the specification still seems to
be in draft status, I thought I'd contribute.
- Is there really a need to allow True or False as id elements? Or
fractional integers? I would suggest saying that id has to be
of an integer (number) or a string.
- The specification is a bit unclear about the null part in id. The
text reads:
A Request identifier that MUST be a JSON scalar (String, Number,
True, False), but SHOULD normally not be Null [1], and Numbers SHOULD
NOT contain fractional parts [2].
It would be more clear if you say that "MUST be a JSON scalar
(String, Number, True, False, Null), but SHOULD normally not be
Null". As it stands now, it's a bit unclear whether null is allowed
at all. But see below.
- Since the request paragraph talks about requests only, I would
actually just disallow null id altogether in requests. Why fuzzy the
wording?
- Many systems do not have an ordered parameter list for the things
that are called, so it is not possible to intuitively implement the
positional argument variant of params. I would suggest allowing only
the by-name parameter passing method - but this is probably heavily
influenced by personal preference. So, make of this suggestion what
you wish.
- In the response elements, a null id means that an error was detected
before parsing the id from the request. I am wondering here, if
there's really a need to specify that the id element MUST be present,
and it MUST be null, instead of just omitting the id element on error
replies. There should be no confusion for the programmer on how to
interpret this, either way. It is ofcourse kind of cool to separate
the absence of some key vs. the absence of the keys value, but the
JSON-RPC 2.0 specification doesn't really require this separation
anywhere.
The motivation behind this change is that many implementations cannot
even differentiate between missing keys and null values - and all
those implementations will need special code to sometimes emit the id
value and sometimes not.
The actual wording of the spec could be that id may be null, or
missing, in the errors which are reported before id was parsed.
- There is very little in the specification about how to react to
additional keys in the messages. For example, the request
specification says that the 'result' and 'error' keys are mutually
exclusive, and that both can never occur in the same response. But
what if that response has a 'method' parameter as well? Is it a
request or a response then?
It should either be explicitly stated that *any* additional keys in
the JSON-RPC 2.0 messages (outside "params", "result" or "data" in
error keys) MUST result in an immediate "invalid request" error - or
it should be specified exactly what is required of the messages and
all additional keys are to be ignored.
I would support ignoring additional keys, because that allows for
easier extensions to the JSON-RPC protocol without being incompatible
with plain JSON-RPC 2.0 implementations.
The changes required for this would be rather minor. It should be
explicitly specified that one of "method", "error" or "params" MUST
be present in every message (in addition to the "jsonrpc"
element). If it is missing, or there are more than one, "invalid
request" should be emitted.
Also, in this case, I'd suggest dropping the "data" element from
errors, as the data can just be put in the "error" element itself -
but this, again, is a matter of personal preference.
- Just as a note - not everybody uses numeric error codes. If one does
not, it causes a funny half-solution for JSON-RPC 2.0. All the
JSON-RPC 2.0 specified error codes are represented exactly as in the
specification - then all application error codes are mapped to, say,
-1 and then the real error code (a string) is in the data element
somewhere. However, I don't see a simple way to fix this, as
requiring string error codes (which are a *lot* easier to coordinate
with multiple different systems) is again a demand that the ones
using numeric error codes are going to have problems with.
That's everything I could come up with right now.
Thanks in advance,
-- Naked
Matt (MPCM)
> that are called, so it is not possible to intuitively implement the
> positional argument variant of params.
suggestion. Which language(s) are you referencing?
> I would support ignoring additional keys, because that allows for
> easier extensions to the JSON-RPC protocol without being incompatible
> with plain JSON-RPC 2.0 implementations.
on the same topic clients should not be blindly sending additional
keys to server without cause to believe it will impact the call.
> - Just as a note - not everybody uses numeric error codes. If one does
> not, it causes a funny half-solution for JSON-RPC 2.0. All the
> JSON-RPC 2.0 specified error codes are represented exactly as in the
> specification - then all application error codes are mapped to, say,
> -1 and then the real error code (a string) is in the data element
> somewhere. However, I don't see a simple way to fix this, as
> requiring string error codes (which are a *lot* easier to coordinate
> with multiple different systems) is again a demand that the ones
> using numeric error codes are going to have problems with.
IMO. Application related errors belong in the result portion...
--
Matt (MPCM)
Sasha Ovsankin
>> not, it causes a funny half-solution for JSON-RPC 2.0. All the
>> JSON-RPC 2.0 specified error codes are represented exactly as in the
>> specification - then all application error codes are mapped to, say,
>> -1 and then the real error code (a string) is in the data element
>> somewhere. However, I don't see a simple way to fix this, as
>> requiring string error codes (which are a *lot* easier to coordinate
>> with multiple different systems) is again a demand that the ones
>> using numeric error codes are going to have problems with.
>>
> Error objects should only be used to deal with json-rpc related errors
> IMO. Application related errors belong in the result portion...
using result codes? Not in my shop...
Regards,
-- Sasha
Matt (MPCM)
> using result codes? Not in my shop...
you use exceptions and who is using your API.
But if you are throwing lots of custom errors, the client library will
need to handle them, or at a minimum pass them up the stack to the
original invoker to deal with. How you deal with that entirely depends
on who your client audience is and the goals of your api.
--
Matt (MPCM)
Sasha Ovsankin
>> Are you suggesting applications to abandon exceptions and go back to
>> using result codes? Not in my shop...
>>
> I am not suggesting that at all. I think that entirely depends on how
> you use exceptions and who is using your API.
> But if you are throwing lots of custom errors, the client library will
> need to handle them, or at a minimum pass them up the stack to the
> original invoker to deal with. How you deal with that entirely depends
> on who your client audience is and the goals of your api.
throw only one, or none at all (network problems, server down, etc.). In
fact, the client implementations I have seen do this handling pretty
well so as an API designer I may just as well rely on exceptions to
signal abnormal conditions. Makes a lot of things easier.
...Which brings back the point where I agree with Nuutti Kotivuor: if we
are propagating an exception that happened somewhere deep in the server
code then making up informational error code is redundant and is waste
of time. What to do then? Should I use error.code=500 and stick
exception type somewhere in the error.data? I would much rather use
exception class as error.code...
Regards,
-- Sasha