View this page "JSON-RPC 1.2 proposal"

[Lorenzo Pastrana]

JSON-RPC 1.2 Are actually completely lagged based on the last
discussions (named parameters, version field, copyright etc...) and
need to be updated before we "Acclaim" them.

I copy pasted the html in an editable page so that can be done.

Click on
http://groups.google.com/group/json-schema/web/json-rpc-1-2-proposal

[Lorenzo Pastrana]

Wrong link sorry..
http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal

[Lorenzo Pastrana]

Edited to conform last discussions (Named params, Version field,
Copyright).

Click on http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal
- or copy & paste it into your browser's address bar if that doesn't
work.

[Lorenzo Pastrana]

Renamed the document from 'proposal' to 'RC1'.

This is an official request for validation.

http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal

[Weston Ruter]

Once we have agreed upon a 1.2 spec, how should we go about safeguarding its integrity? Should we snapshot the document by putting it in with the Files? I guess if things go forward with json-rpc.org we can publish documents there.

[Lorenzo Pastrana]

On Fri, 2008-02-22 at 08:54 -0800, Weston Ruter wrote:
> Once we have agreed upon a 1.2 spec, how should we go about
> safeguarding its integrity? Should we snapshot the document by putting
> it in with the Files? I guess if things go forward with json-rpc.org
> we can publish documents there.

Yep.. of course :)

[Jeffrey Damick]

I would think it makes more sense to keep it here and link from json-rpc.org to some immutable version here..

[Jeffrey Damick]

i updated the samples to match the definition of version (which is
string because the version could be 1.2.3.4).

[Jeffrey Damick]

We should try to have this finalized by 2/29 (Friday).  Are there any other comments / objections with the current 1.2 RC 1 spec in its current form?  

[Matt (MPCM)]

I have been out sick the last few days and am still catching up with
my inbox/lists. I'll review shortly and see if there is anything I
think should be addressed.

In general this friday feels a bit soon, I'm not sure we need to rush
this that much (?). If there are few issues... then it won't matter
anyway I guess.

--
Matt (MPCM)

[Jim Washington]

4.1 states that a server MUST NOT reply to a notification.

Since many of us will be implementing JSON-RPC in HTTP servers, there
may be a small implementation issue with this, since most HTTP servers
are coded so that all requests return some kind of response.

I think that returning response headers + 204 (No content) meets the
intent for notifications, so MUST NOT is a bit strong here. SHOULD NOT
would be preferable, IMO.

- Jim Washington

[Lorenzo Pastrana]

> I think that returning response headers + 204 (No content) meets the
> intent for notifications,

204 (No content) Stays *OK* with the MUST-NOT, since 204 header is an
HTTP (transport) concept, the actual json-rpc doesn't return any data.

My 2c

LP

[Jeffrey Damick]

We've been sitting on the spec for months (if not years?) now.. We just need to put some stake in the ground and move on to the next version(?)..

[Matt (MPCM)]

Can we change notifications so that we are not calling them
unreliable?

I think it is the wrong way of looking that them. As any number of
things could happen transport wise, routing wise, exception wise, that
make regular requests just as 'unreliable'. Perhaps we could stress
that with notifications you will not see any response object,
including any corresponding Error objects.

[Roland Koebler]

I agree.
I strongly recommend to stay at "MUST NOT reply to a Notification".
remember that json-rpc and its transport(s) are COMPLETELY INDEPENDENT!

regards,
Roland

[Roland Koebler]

hi,

> We should try to have this finalized by 2/29 (Friday).

no, definietely not. that's too early, and there are too many bugs in
the so-called "release candidate".

> Are there any other
> comments / objections with the current 1.2 RC 1 spec in its current form?

yes, there are. plenty of them.

there was a discussion some time ago about my 1.2-proposal ("without
version-field") vs. my 2.0-proposal ("with version-field"). As far as I
know, the version-field "won". but if we use a version-field, we should
also clean-up some other things, like I suggested in my 2.0-proposal,
but which has not been done in "1.2 RC 1".

- first of all, the changes that have been made to (my) 1.2-proposal which
resulted in the "1.2 RC 1" are incomplete and inconsistent, and a
clean-up is really necessary (e.g. chapter 3 "compatibility" is
completely outdated).
- there has been the suggestion to rename the "version"-field
to "jsonrpc", which I think is sensible.
- the "version"-field in the response is redundant. this group should
decide if it should be necessary, omitted or optional.
- the error-object should look differently.
- most of the members here agreed that some empty fields may be omitted.
but the "1.2 RC 1" doesn't contain this.
- should it be called 1.2 or 2.0?

I'll modify the "1.2 RC 1" the next days (or create an own version, if
you wish) according to this.

regards,
Roland

[Roland Koebler]

hi,

> Can we change notifications so that we are not calling them
> unreliable?

why? you cannot rely on notifications.
of course you can propose an other formulation, but the meaning should
stay the same. It's unreliable in the same way as e.g. UDP is.

> As any number of
> things could happen transport wise, routing wise, exception wise, that
> make regular requests just as 'unreliable'.

no. of course, regular requests can get lost, but you can notice this!
and thats a *big difference*. with notifications, you CANNOT DETECT ERRORS
(e.g. lost packets, wrong calls etc.).

regards,
Roland

[Matt (MPCM)]

I just did not care for the wording choice I guess, not getting back
errors does not imply it is unreliable. How does unconfirmed sound?
Perhaps I'm splitting hairs on this. I'll dwell on it tonight and see
if I can find the word(s) I seem to be searching for...

[Lorenzo Pastrana]

On Tue, 2008-02-26 at 13:24 -0800, Matt (MPCM) wrote:
> I just did not care for the wording choice I guess, not getting back
> errors does not imply it is unreliable.

Wording is correct, this is the same difference between tcp and udp.
Network transmissions are unreliable by essence.

Network wise, please think the other way : getting error notification is
the only thing that makes a protocol 'reliable' so if you do not respond
ever to a message, your protocol is inherently 'unreliable' as the
network transmission is.

LP

[Matt (MPCM)]

I understand the metaphor, but I am not sure it maps directly. Since
we are not talking about transports in json-rpc, but data structures
and principles. With UDP you have no way of knowing the data got there
(good, bad, or otherwise).

With notifications, you do not know the side effects. Being unaware of
the side effects (errors or returns) does not mean notifications are
unreliable. The side effects don't change just because the client is
unaware. I guess it is the difference between unconfirmed and
unreliable, and it depends what you think you are relying on...

It's a minor point and not worth splitting hairs over more than this
last comment. : )

[Jeffrey Damick]

Yea me 2, i agree that the transport is independent from main spec.

[Jeffrey Damick]

renamed RC1 to 2.0

[Matt (MPCM)]

Time to poke the fires again : )

What are the topics that need resolving for 2.0 to move forward at
this point?

--
Matt

[Powerman]

As far I understand, client may send several Requests, one after one
(without Batch/Multicall feature), then get several Responses from
server, and order of Responses may not match order of Requests -
that's reason why "id" exists in protocol. In this case I think this
phrase should be moved OUT of Batch/Multicall section because it's
more general:

"Note that the Requests may be processed in parallel, so don't rely on
a specific processing-order of the Requests."

[Tom Robinson]

I am wondering if this example is correct:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid
Request."}, "id": null}

Since the request has no "id" (but is valid JSON so it can be parsed),
it's a notification and should not receive a response.

[Matt (MPCM)]

You are correct, the example is incorrect and needs updating. The only
error a notification should receive is for bad json or internal errors
that trigger before the fact that the request is a notification can be
established.

--
Matt (MPCM)

[Roland Koebler]

Hi,

No, it's not a notification -- it's not even valid JSON-RPC, since
"params" must be an JSON-Array or -Object.

Of course, it could be discussed how a server should handle invalid
JSON-RPC (of if it should handle it at all) and how far it should
"guess" what it was meant to be. But I *strongly* prefer that the
server should *not* handle it at all -- everything else could cause
strange behaviour. So, the example is *correct*.

regards,
Roland

[Tom Robinson]

On Sep 6, 2009, at 3:04 PM, Roland Koebler wrote:

Hi,

I am wondering if this example is correct:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}

<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid

Request."}, "id": null}

Since the request has no "id" (but is valid JSON so it can be parsed),

it's a notification and should not receive a response.

No, it's not a notification -- it's not even valid JSON-RPC, since
"params" must be an JSON-Array or -Object.

Under what conditions should invalid notifications receive error messages? Any "Invalid Request" error?

That would seem to contradict "Every Request, except Notifications, MUST be replied to with a Response."

-tom

[Roland Koebler]

On Sun, Sep 06, 2009 at 03:33:20PM -0700, Tom Robinson wrote:
> Under what conditions should invalid notifications receive error
> messages? Any "Invalid Request" error?

Any invalid JSON causes an "Parse error."; any valid JSON which is not
valid JSON-RPC causes a "Invalid Request." error.

> That would seem to contradict "Every Request, except Notifications,
> MUST be replied to with a Response."

No. The example string

{"jsonrpc": "2.0", "method": 1, "params": "bar"}

is neither a Request, nor a Notification -- is not even valid JSON-RPC!
It's the same for e.g.
{"jsonrpc:" "2.0", "foo": "bar"}

Maybe the first example it was *meant* to be a notification, but the
server must not guess what the user possibly meant...

regards,
Roland

[Omi]

The example does show the scenario

---------------------------------------------------------

any valid JSON which is not valid JSON-RPC causes a "Invalid
Request." error.

----------------------------------------------------------
since its valid JSON just not valid JSON-RPC. So I guess we can go
back to trying to finalize the spec.
BTW, do we intend to turn it into a RFC when we are done are we going
to keep tweaking it and only publish it here.

[Alexandre Morgaut]

Well, I really think that we need an easier way to publish web
services than the SOAP family

REST and XML/JSON-RPC are really lighter and more efficient ways in
the more commonly cases (which does not mean that JSON-RPC is limited
to HTTP)

So Yes, JSON-RPC should be published as a RFC to generate more stables
implementations and tools.

I only regret some little things :
- why the version property had to be turned into a a "jsonrpc"
property ? (not big deal but just strange as JSON-RPC 1 authors seemed
to support JSON-RPC 2)
- some wants to have batch being ordered... That can be useful
sometimes but shouldn't be a requirement (still under discussion)

A good point is that RFC means in fact "Request For Comments", so JSON-
RPC can start publishing a draft as an RFC candidate.

Even if I think that JSON-RPC over HTTP really gain from REST some
requirements while supporting the GET method, I really have faith in
JSON-RPC itself as a useful way to provide web services.

[Matt (MPCM)]

> I only regret some little things :
>  - why the version property had to be turned into a a "jsonrpc"
> property ? (not big deal but just strange as JSON-RPC 1 authors seemed
> to support JSON-RPC 2)

jsonrpc="2.0" vs version="2.0" ?

The field was added to allow both the server and client bound messages
to indicate the 2.0 handling (reduced fields and object params). As
for the property name, it allows some indication that it is intended
as a jsonrpc2 message, in contrast with other json objects that might
exist in a complex payload.

> Even if I think that JSON-RPC over HTTP really gain from REST some
> requirements while supporting the GET method, I really have faith in
> JSON-RPC itself as a useful way to provide web services.

After several years using heavily in production, I'd it works very
well. Lets me/us focus on our core api/application which often are
complex enough. : )

--
Matt (MPCM)

[Alexandre Morgaut]

I agree that "version":"2.0" wasn't enougth to understand that the
payload is for JSON-RPC
As JSON-RPC is transport protocol and language independent, the
payload is the only place to write "JSON-RPC"

I think we might do as :
- HTTP -> "GET / HTTP/1.1"
- and CGI -> "GATEWAY_INTERFACE = CGI/1.0"
which both include their name in their version property doing like
this:

{"version":"JSON-RPC/2.0", (...)}

The User-Agent HTTP header is full of this notation
ex: "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/
525.13 (KHTML, like Gecko) Chrome/4.0.202.0 Safari/532.0"

[Alexandre Morgaut]

Note that this version notation could be extensible for JSON-RPC
extensions

ex: {"version":"JSON-RPC/2.0 BATCH-TRANSACTION/1.0", (...)}

as some HTTP server which show which "modules" they handle

ex: "Apache/1.3.33 (Debian GNU/Linux) AuthMySQL/2.30 mod_ssl/2.8.22
OpenSSL/0.9.7e"

[Matt (MPCM)]

Not sure this is would be worth the complication, especially because
of what it could become with extensions or future versions. But for
the collisions the lack of it could cause with 1.0 clients, I would
skip the field entirely from the spec.

There are those of us who have systems sending messages back and forth
between our own clients/servers who could skip the field entirely, as
we are purely "2.0" already. I struggle with versions and loose
functionality descriptors in general, as they always seem to lead to
creative clutter of the best intentions (and worst practices).

This version field however could be a nice extension in and of
itself... just would not want to see it in the official spec. Somewhat
like SMD.. There are all sorts of things we could push into json-rpc,
I see my role primarily as keeping them out. : )

My $0.02,

--
Matt (MPCM)

[BYK]

I agree with Alexandre. This version would introduce a "defined" way
for extensions in jsonrpc.

[Lorenzo Pastrana]

On Mon, 2009-09-14 at 11:03 -0700, Matt (MPCM) wrote:

Not sure this is would be worth the complication, especially because
of what it could become with extensions or future versions. But for
the collisions the lack of it could cause with 1.0 clients, I would
skip the field entirely from the spec.

There are those of us who have systems sending messages back and forth
between our own clients/servers who could skip the field entirely, as
we are purely "2.0" already.

Fact is, that the field is not intended to differentiate 2.0 from 1.0
but 2.0 from 2.3 and 3.0 and .. it eventually makes a difference from
1.0 but the field is a little more future oriented.

This is why we settled to the importance of a version field.

My O.O2€

Lo.

[Matt (MPCM)]

O.O2€ is worth more than my $0.02 :)

So the field would be used to represent whatever extensions (and
behaviors) the client desires? If those extensions and behaviors be
rolled into the next spec version, the tag could be removed resulting
in something like...

"JSONRPC/2.0" representing the 2.0 spec
"JSONRPC/2.0 MYCUSTOMEXTENSION/1.4" representing the base 2.0 spec
plus something custom.
"JSONRPC/3.0" assuming MYCUSTOMEXTENSION/1.4 is rolled into 3.0

Every request and response object would carry this, else be dropped to
1.0 behavior...

Should the server reject handling of extensions it does not recognize?
Should the server attempt handling of versions greater than it can
recognize?
The official spec version would best be required as the first string
descriptor?


--
Matt (MPCM)

[Alexandre Morgaut]

Hi,

I'm just back from the Ajax Experience
Unfortunatly, not much people talked about JSON-RPC
The only Web Services solutions I saw were :
- REST data services and JSON-RPC from our team,
- and YQL (Yahoo Query Language) from Yahoo
But I couldn't see all the presentation and I surelly missed some
others

Well sorry for this little talk of my life ;-)

I surely had preferred "version":"JSONPRC/2.0" to the actual
"jsonrpc":"2.0"
But as you said JSON-RPC is already implemented by some servers and
client and this would break compatibility with them

More recent clients could send both properties but I fear that some
servers could consider the message as not valid JSON-RPC (I hope not)
As I said first, its not big deal for me, I only explained my point of
view because you invited me to

On the other hand, "PROTOCOL/{versionNumber}" notation is really
String oriented with character delimiters, JSON-RPC must take the
benefit of JSON
Maybe the best would would have been something like that:

// this is not a suggestion for implementation
{"jsonrpc": {"version": "2.0", "method": "subtract", "params":
{"subtrahend": 23, "minuend": 42}, "id": 3}}

But this would break even more the compatibility level with actual and
previous versions

About Extensions

I wrote my second post suggesting extensions a bit quickly, sorry, it
was late, I was reading another JavaScript book talking about DOM
support...
So, more seriously, I finally think extensions could better handled in
JSON-RPC as a JSON object in a dedicated "extensions" property as
bellow

{"jsonrpc": "2.0", "extensions":
{"myext1":"1.4","myext2":"0.42"}, ...}

I'm not sure it is required to specify it directly in the JSON-RPC
spec
It can be good, but it can also be specified in a separated spec

To reply to your questions:

"Should the server reject handling of extensions it does not
recognize ?"

- I think the request should only specify extensions if they are
required, and the server should then reject the request if it doesn't
recognize an extension

"Should the server attempt handling of versions greater than it can
recognize ?"

- Even if potentially possible when all properties are recognized, it
still can be dangerous with unexpected results, it would be best
secured if the server just say it cannot handle it. The client should
be able to downgrade its request once it knows the supported version
from the received response

I agree to not overload the spec and try to status it definitely as
soon as possible
By the way, the definition of how to manage extension could prevent
any further modification requests ;-)

--
Alexandre

[Lorenzo Pastrana]

On Thu, 2009-09-17 at 11:15 -0700, Matt (MPCM) wrote:

O.O2€ is worth more than my $0.02 :)

That might not last :) but IANAE(conomist)

So the field would be used to represent whatever extensions (and
behaviors) the client desires?

The version field is actually more comparable to the HTTP/1.1 token than the UA string header; that is : version field represented JSON-RPC only, extensions where intentionally un-specified .. except for the entry point.

Should the server reject handling of extensions it does not recognize?
Should the server attempt handling of versions greater than it can
recognize?
The official spec version would best be required as the first string
descriptor?

IMHO :

The server MUST behave as expected by the JSON-RPC Major.minor Version specs.

The server MAY be able to handle previous versions requests, and MUST be able if so, to respond in the appropriate dialect.

One implicit thing that could clarify the extensions mechanism is that an extension in terms of JSON-RPC should be a server-implemented method callable down the rpc.* namespace, nothing more fancy.

If the extesion is some kind of internal processing stuff it should not have any publicity in the extension space ...

My 0.013594€

Lo.

[Matt (MPCM)]

@Alexandre Morgaut

> I'm just back from the Ajax Experience
> Unfortunatly, not much people talked about JSON-RPC

I attended the first few Ajax Experience conferences and enjoyed them
quite a lot. The keynotes mostly and the conversations, and I was glad
to meet and chat with Kris Zip and others about JSON-RPC, JSON-Schema,
Persevere. And also to defend JSON to people who would XML the
world :).

Was kind of sad to have missed it this year, and seemingly a chance to
meet you in person.

--
Matt (MPCM)

[Alexandre Morgaut]

>
> I attended the first few Ajax Experience conferences and enjoyed them
> quite a lot. The keynotes mostly and the conversations, and I was glad
> to meet and chat with Kris Zip and others about JSON-RPC, JSON-Schema,
> Persevere. And also to defend JSON to people who would XML the
> world :).
>

[mode JSON-RPC off]
JSON and Server-Side JavaScript were quite well promoted
We even had the surprised to be criticized because we used XML instead
of JSON to define tables and entity Models.
This can also be done in JSON in Wakanda, but as said Douglas
Crockford, JSON is an "interchange" data format. In fact, the XML was
only used because of the autocompletion available in Netbeans with an
XML Schema, this should come in the future for JSON with JSON Schema..

We really like the work of Kris Zip on JSON Schema and Persevere
Maybe one day we'll join Persevere and Wakanda project (and why not
Narwhal). Nodejs is also interesting.

[mode JSON-RPC on]
I had a talk with Douglas about JSON Hijacking which could become an
issue if we try to expose batch requests on HTTP GET
He said it's up to the server to check the validity of the request
JSON Hijacking mostly work because lot of servers accept to reply to
requests not requiring JSON mediatype
They should at least refuse all requests whose accept header include
the possibility to serve JavaScript
I'll expose it to the JSON-RPC over HTTP thread

[Raistlin Majere]

There isn't specified, how to use batch requests on HTTP GET. Because
I must use named parameters of GET, so I can't use it twice or more.
For example:
...?method=firstAction&id=1
...?method=secondAction&id=2
How can I merge this two requests in to one HTTP GET batch request?

[Matt (MPCM)]

"Must use named parameters of GET"?

Mapping the individual portions of a request object into the path or
the query string in HTTP does make batch sending less clear. I prefer
passing the entire request object as a string on a key, in my examples
below I selected key `jsonrpc`.

Various ways I've coded my test server to check against the query
string:

http://www.json-rpc.info/jsonrpc2php_http/example_2_client.html

--
Matt (MPCM)

[Alexandre Morgaut]

I completed this discussion in the JSON-RPC over HTTP discussion

http://groups.google.com/group/json-rpc/browse_thread/thread/54d207d166b11f95?hl=en#b9e01289499d4fc7

Where I suggested same solution as Matt (I just used a different key,
here it is "batch" but "jsonrpc" should be better)

GET /rpc?batch=<encoded JSON-RPC batch array> HTTP/1.1
Host: http://rpcserver.com
X-Json-Hijack: false

Matt told he will update the JSON-RPC over HTTP with several
precisions
You can see on his testing page that he is looking for the more
reliables syntaxes

The "X-Json-Hijack" HTTP header I proposed was here to prevent data
from being stolen with JSON Hijacking because Batches are expressed as
JSON Arrays
It could take any value, the point is that the html script tag used
for this hack can't set custom HTTP headers