JSON-RPC 1.2 RC1 modifications
Roland Koebler
before modifying the JSON-RPC 1.2 RC1 page, here are my questions and
modification suggestions:
- version-number: should it be 1.2 or 2.0 ?
(since it does not work with jsonrpc1.0, some already suggested to use 2.0)
- version-field: I would rename it to "jsonrpc" because I think this is
better than the meaningless name "version". any comments?
- Request:
"params": I would allow "params" to be omitted if empty. ok?
- Notifications: in my opinion, notifications should omit the
"id"-field, since it's totally useless for notifications.
ok?
"id":null then is a regular request, but I would discourage to
use an id of null. (see my modifications below)
- Response:
"version" or "jsonrpc": should such a version-field be used in the
response? since it carries absolutely no informations (because
it would be exactly the same as in the request), it's not really
necessary.
should it be required, omitted or optional?
"result" and "error": I think only one of these should be send, and
the other should be omitted. ok?
- Extensions:
I think we should discuss how extensions should look like.
should they use special names, should they use additional fields?
and how about compatibility with implementation which don't support them?
and how can the client find out which extensions the server supports?
so, according to my opinions above, the modifications would be the
following. in a few days or as soon as I get some answers to my
questions I will update the google-groups-page.
- 3 Compatibility:
the text here is completely wrong now, after the modifications.
so, I suggest to replace it by:
JSON-RPC 1.2 does not work with JSON-RPC 1.0 clients or servers.
But it's easy to distinguish between JSON-RPC 1.2 and JSON-RPC 1.0
(due to the "jsonrpc"-version-field), and e.g. to create a combined
JSON-RPC 1.0/1.2-server.
- 4 Request:
version: rename to "jsonrpc". (+some shorter formulations)
params: "Can be omitted if empty."
id: should normally not be Null[#]. If omitted, the Request is a Notification.
[#] The use of Null for ``id`` in Requests is discouraged, because this
specification uses an ``id`` of Null for Responses with an unknown
``id``, and because JSON-RPC 1.0 uses an ``id`` of Null for
Notifications.
remove the sentence that a request must contain all 4 members and that
a server should also accept other things.
- 4.1 Notification:
replace the 1st paragraph by:
A Notification is a special Request, without ``id`` and without
Response. The server MUST NOT reply to a Notification, except for
"Parse error" and "Invalid Request".
- 4.2 Parameters
remove the 2 "This MUST be supported." sentences.
- 5. Response
"version": again renamed to "jsonrpc" (+shorter formulation)
remove the sentence "The absence of this member can effectively be
taken to mean that the remote server implement version 1.0 of the
JSON-RPC protocol.", because it is irrelevant: the response MUST
use exactly the same version as the request.
"result":
Required on success, omitted on failure.
...
This member MUST be entirely omitted if there was an error invoking
the procedure.
"error":
Required on error, omitted on success.
...
"This member MUST be entirely omitted if there was no such fault."
and, of course, again remove the sentences about "MUST contain all 4
members" and "SHOULD however also accept". instead, write:
Exactly one of ``result`` or ``error`` MUST be specified. It's not
allowed to specify both or none.
For better compatibility with JSON-RPC 1.0-servers, a client MAY however
accept both ``result`` and ``error`` if at least one of these is Null
(like in the JSON-RPC 1.0-specification).
- 5.1 Error Object:
remove "Since JSON-RPC 1.0 did not..."
6. Examples:
adapt them.
regards,
Roland
Lorenzo Pastrana
> hi,
>
> before modifying the JSON-RPC 1.2 RC1 page, here are my questions and
> modification suggestions:
>
> - version-number: should it be 1.2 or 2.0 ?
> (since it does not work with jsonrpc1.0, some already suggested to use 2.0)
2.0 is fine for me
> - version-field: I would rename it to "jsonrpc" because I think this is
> better than the meaningless name "version". any comments?
I think just the contrary :
'version' is exactly that : a 'meaning' witch qualifies the 1.2 value
'jsonrpc' is an unqualified scalar value with no 'neaning'
But I actually don't care about this one.
> - Request:
> "params": I would allow "params" to be omitted if empty. ok?
Right.
> - Notifications: in my opinion, notifications should omit the
> "id"-field, since it's totally useless for notifications.
> ok?
Right.
> "id":null then is a regular request, but I would discourage to
> use an id of null. (see my modifications below)
> - Response:
> "version" or "jsonrpc": should such a version-field be used in the
> response? since it carries absolutely no informations (because
> it would be exactly the same as in the request), it's not really
> necessary.
> should it be required, omitted or optional?
I put the 'version' field to the response because I felt response
messages should be 'isomorph' to requests. Also it _does_ carry some
informations, especially in mashup.
required ?
> "result" and "error": I think only one of these should be send, and
> the other should be omitted. ok?
For testing presence or 'non null' to be the same, the two fields must
be mutually exclusive.
> so, according to my opinions above, the modifications would be the
> following. in a few days or as soon as I get some answers to my
> questions I will update the google-groups-page.
>
> - 3 Compatibility:
> the text here is completely wrong now, after the modifications.
> so, I suggest to replace it by:
>
> JSON-RPC 1.2 does not work with JSON-RPC 1.0 clients or servers.
>
> But it's easy to distinguish between JSON-RPC 1.2 and JSON-RPC 1.0
> (due to the "jsonrpc"-version-field), and e.g. to create a combined
> JSON-RPC 1.0/1.2-server.
Ok.
> - 4 Request:
> version: rename to "jsonrpc". (+some shorter formulations)
> params: "Can be omitted if empty."
> id: should normally not be Null[#]. If omitted, the Request is a Notification.
>
> [#] The use of Null for ``id`` in Requests is discouraged, because this
> specification uses an ``id`` of Null for Responses with an unknown
> ``id``, and because JSON-RPC 1.0 uses an ``id`` of Null for
> Notifications.
>
> remove the sentence that a request must contain all 4 members and that
> a server should also accept other things.
A request MUST at least contain a 'version/..' and a 'method' field ?
Ok.
> - 4.1 Notification:
> replace the 1st paragraph by:
>
> A Notification is a special Request, without ``id`` and without
> Response. The server MUST NOT reply to a Notification, except for
> "Parse error" and "Invalid Request".
Ok.
> - 4.2 Parameters
> remove the 2 "This MUST be supported." sentences.
Ok.
> - 5. Response
> "version": again renamed to "jsonrpc" (+shorter formulation)
> remove the sentence "The absence of this member can effectively be
> taken to mean that the remote server implement version 1.0 of the
> JSON-RPC protocol.", because it is irrelevant: the response MUST
> use exactly the same version as the request.
See previous reply.
> "result":
> Required on success, omitted on failure.
> ...
> This member MUST be entirely omitted if there was an error invoking
> the procedure.
Mutex
Ok.
> "error":
> Required on error, omitted on success.
> ...
> "This member MUST be entirely omitted if there was no such fault."
Mutex
Ok.
> and, of course, again remove the sentences about "MUST contain all 4
> members" and "SHOULD however also accept". instead, write:
>
> Exactly one of ``result`` or ``error`` MUST be specified. It's not
> allowed to specify both or none.
Ok.
> For better compatibility with JSON-RPC 1.0-servers, a client MAY however
> accept both ``result`` and ``error`` if at least one of these is Null
> (like in the JSON-RPC 1.0-specification).
> - 5.1 Error Object:
> remove "Since JSON-RPC 1.0 did not..."
Ok.
> 6. Examples:
> adapt them.
Sure.
Jeffrey Damick
before modifying the JSON-RPC 1.2 RC1 page, here are my questions and
modification suggestions:
- version-number: should it be 1.2 or 2.0 ?
(since it does not work with jsonrpc1.0, some already suggested to use 2.0)
- version-field: I would rename it to "jsonrpc" because I think this is
better than the meaningless name "version". any comments?
- Request:
"params": I would allow "params" to be omitted if empty. ok?
- Notifications: in my opinion, notifications should omit the
"id"-field, since it's totally useless for notifications.
ok?
"id":null then is a regular request, but I would discourage to
use an id of null. (see my modifications below)
- Response:
"version" or "jsonrpc": should such a version-field be used in the
response? since it carries absolutely no informations (because
it would be exactly the same as in the request), it's not really
necessary.
should it be required, omitted or optional?
"result" and "error": I think only one of these should be send, and
the other should be omitted. ok?
- Extensions:
I think we should discuss how extensions should look like.
should they use special names, should they use additional fields?
and how about compatibility with implementation which don't support them?
and how can the client find out which extensions the server supports?
so, according to my opinions above, the modifications would be the
following. in a few days or as soon as I get some answers to my
questions I will update the google-groups-page.
Roland Koebler
> > - version-field: I would rename it to "jsonrpc" because I think this is
> > better than the meaningless name "version". any comments?
>
> i prefer "version" since it more representative of the purpose for the
> value..
jsonrpc-packet, you immediately see that it is a jsonrpc-package.
if it is named "version", you don't know if it is jsonrpc or maybe
something else.
regards,
Roland
Jeffrey Damick
Matt (MPCM)
Roland mentioned.
--
Matt (MPCM)
Weston Ruter
Roland Koebler
now I tried to make the modifications in google's totally braindead
page editor (tm). you find the now-called "JSON-RPC 2.0 RC1" at:
http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal
regards,
Roland
Matt (MPCM)
like to eat stuff at times.
I'll take a closer look later today, but on an initial scan nothing
jumped out at me :)
--
Matt (MPCM)
CC
I suggest to remove the exceptions for Parse error and invalid request
in the phrase
"The server MUST NOT reply to a Notification, except for "Parse error"
and "Invalid Request"."
We have no use for these replies and it is awkward if the programmer
of the client has to deal with two possible situations of getting or
not getting a response from the server. This is true for synchronous
as well as asynchronous cases.
Roland Koebler
> I suggest to remove the exceptions for Parse error and invalid request
> in the phrase
>
> "The server MUST NOT reply to a Notification, except for "Parse error"
> and "Invalid Request"."
I could remove this sentence, but it wouldn't change anything in the
specified behaviour.
"Parse error" and "Invalid Request" essentially mean, that the jsonrpc-object
was invalid, and the server couldn't even determine if you meant to send a
notification or not.
see json-rpc proposal (2.0 RC1), section "Error Object", error-codes.
regards,
Roland
Jeffrey Damick
Jeffrey Damick
errors are ok for notifications to return?
On Mar 13, 3:20 pm, "Jeffrey Damick" <jeffreydam...@gmail.com> wrote:
> Yeah either allow only system level error responses or don't allow
> anything.. i'd think system level errors would be valuable for the client
> if only for logging purposes and this doesn't defeat purpose of having
> notification to avoid waiting on the time consuming part of actually
> processing the running the method..
>
Roland Koebler
> So I take the silence as agreement with specifying that system level
> errors are ok for notifications to return?
if you want to return system-level errors at all, you also have to
return them for invalid-requests-which-meant-to-be-notifications.
but I removed the confusing sentence in the "JSON-RPC 2.0 RC1", so that
it now reads:
... The server MUST NOT reply to a Notification.
(see: http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal)
note that this doesn't change anything in the specified behaviour.
regards,
Roland