named parameters? yes or no?

[Roland Koebler]

hi,

I would like to include "named parameters" in the json-rpc 1.1
specification, but mark them as OPTIONAL.
what do you think?

do you want/need "named parameters"?
[ ] I want named parameters
[ ] undecided / I don't need them, but am not against them.
[ ] I don't want named parameters

regards,
Roland

[Arthur Blake]

> do you want/need "named parameters"?

[X] I wanted named parameters, but marked as OPTIONAL.

[ ] I want named parameters
[ ] undecided / I don't need them, but am not against them.
[ ] I don't want named parameters

I can see how they can and will be useful, but I don't particularly
need them any time soon.

[Weston Ruter]

I would like to include "named parameters" in the json-rpc 1.1
specification, but mark them as OPTIONAL.
what do you think?

do you want/need "named parameters"?

[ X ] I want and need named parameters (how can I be more emphatic about this?)

[Kris Zyp]

Thank you, Roland, I appreciate it.
[X] undecided / I don't need them, but am not against them.

[Skylos]

I would like to include "named parameters" in the json-rpc 1.1
specification, but mark them as OPTIONAL.
what do you think?

do you want/need "named parameters"?

[X] I want named parameters

[ ] undecided / I don't need them, but am not against them.
[ ] I don't want named parameters

I don't care if you can make an implementation that doesn't use them.  Only that they're actually can be there!

David

[Jim Washington]

Roland Koebler wrote:
> hi,
>
> I would like to include "named parameters" in the json-rpc 1.1
> specification, but mark them as OPTIONAL.
> what do you think?
>
> do you want/need "named parameters"?

> [X] I want named parameters

> [ ] undecided / I don't need them, but am not against them.
> [ ] I don't want named parameters
>

-Jim Washington

[Matt (MPCM)]

> do you want/need "named parameters"?

> [X] I want named parameters

> [ ] undecided / I don't need them, but am not against them.
> [ ] I don't want named parameters

Preferably in the object form, but yes either way.

[Weston Ruter]

Oh yes, and I strongly prefer named params in the object form.

[Kris Zyp]

Simple Method Description (SMD) is a format for describing a broad range of web services, JSON-RPC being one of them. SMD is used by Dojo for describing web services, and Dustin Machi of Dojo and I have spent a good deal of time last week working on how JSON Schema and SMD could be integrated. I believe SMD and JSON Schema work very well together. SMD has been designed for flexibly describing a variety of web services, and JSON Schema works well to describe the data that is used the by methods in the web services. Together they provide a comprehensive JSON-based representation of web services. SMD has the flexibility of being extremely simple and terse, or it can be very thorough in describing transports, data types, sub-services, and descriptions of these.

I believe that this new SMD (that integrates JSON Schema data typing) would be the best approach for a service description for JSON-RPC. First of all, it is JSON based, JSON-RPC doesn't need to be described in a different format (like XML). Second the new JSON-RPC doesn't need to define it's own service description, but can defer to a service description that is more broadly focused. By using SMD with JSON Schema, JSON-RPC can use a JSON description that can be used by other web services.

Dustin and I do not have a specification ready yet, but I wanted to get our ideas in front of this group through some examples, so we can collaborate and get more feedback on this as we develop this. Dustin has an example of this new SMD at: http://dojotoolkit.org/~dmachi/rpc/ with examples of a variety of web services. For a plain JSON-RPC service, an SMD would look something:

{
 transport: "RAW_POST",  // see Dustin's example for more on these properties
 envelope: "JSON-RPC", 
 serviceUrl: "/service", 
 methods: { 
  add: {
   parameters: [  // an array indicates that positional parameters should be used for this method
    {type: "integer", default: 0},
    {type: "integer", default: 0},
   ],
   returns:"integer"
  },
  divide: {
    description:"Do division",
    parameters: { // an object indicates that named parameters should be used for this method
     divisor:{type:"integer"},
     dividend:{type:"integer"}
    },
    returns:"float"
  },
  simpleMethod: {},// almost all properties are optional, this method description has no requirements on parameters or return type
  getAddress : {
    description : "Takes a person and returns an address",
    parameters : {
     person : {type: // describe this parameter with a schema
      {firstName:{type:"string"},lastName:{type:"string"}}
     },
    },
    returns : // use a schema to describe the return type
        {street:{type:"string"},zip:{type:"string"},state:{type:"string"},town:{type:"string"}}
  }
 }
}

I made a page for it: http://groups.google.com/group/json-rpc/web/simple-method-description-for-json-rpc-example?hl=en, but it is small, so I just copied it here.

Does this seem like a reasonable approach for a service description for JSON-RPC?

For a little Roland-style voting (thanks for getting that going, Roland)...

[ ] Yes, this has potential to be a recommended service description for JSON-RPC 1.1

[ ] No, we should use ___________ for service description

If so there I believe there are still a number of open questions, and it is still flexible, so I will bring some of the issues to this group if that is allright.

Kris

[Jeffrey Damick]

On Dec 3, 2007 5:44 PM, Roland Koebler <r.ko...@yahoo.de> wrote:

I would like to include "named parameters" in the json-rpc 1.1
specification, but mark them as OPTIONAL.
what do you think?

do you want/need "named parameters"?

 
[X] I want named parameters (and should be REQUIRED for server to support)

[SMM]

[X] I want (but don't need) named parameters

[Roland Koebler]

hi Kris,

> First of all, it is JSON based

first, I want to note that your example below and the one in V2example.smd
is no valid JSON: Comments are not allowed in JSON, and all names in a
JSON-object must be strings, enclosed in "..".

> {
> transport: "RAW_POST", // see Dustin's example for more on these properties
> envelope: "JSON-RPC",
> serviceUrl: "/service",

question: how would this look like without HTTP?
e.g. if I use raw tcp/ip, i.e. with the address 127.0.0.1, port 12345 ?
or if I use something totally different, i.e. USB or RS232?
would "transport" and "serviceUrl" then be simply omitted?

> methods: {
> add: {
> parameters: [ // an array indicates that positional parameters should be used for this method
> {type: "integer", default: 0},
> {type: "integer", default: 0},
> ],
> returns:"integer"
> },
> divide: {
> description:"Do division",
> parameters: { // an object indicates that named parameters should be used for this method
> divisor:{type:"integer"},
> dividend:{type:"integer"}
> },
> returns:"float"
> },

I think this means that I have to specify a method twice if it can be called
both with named or positional parameters. right?

I would probably prefer 1 definition per method (like in your JSON Schema), and
completely let the user decide if he wants to use named or positional parameters.
example (in valid JSON):

"methods": {
"add": {
"parameters": [
{"type": "integer", "default": 0, "name": "summand1"},
{"type": "integer", "default": 0, "name": "summand2"},
],
"returns": "integer"
},
...
}

where "parameters" is always an array, and "name" may be optional.

> Does this seem like a reasonable approach for a service description for JSON-RPC?
>

> [X] Yes, this has potential to be a recommended service description for JSON-RPC 1.1
yes, if it is not transport-specific (=if it works for every transport I chose).

but because I have not yet played with service-descriptions in real
applications, I cannot tell you more...

regards,
Roland

[Weston Ruter]

[ X ] Yes, this has potential to be a recommended service description for JSON-RPC 1.1

I agree with Roland that "parameters" should be expressed in an array with a "name" property, not an object.

Thanks for working on this, Kris.

[Kris Zyp]

> first, I want to note that your example below and the one in V2example.smd
> is no valid JSON: Comments are not allowed in JSON, and all names in a
> JSON-object must be strings, enclosed in "..".

Obviously this is not valid JSON, Dustin just did this for the sake of
readability, and providing comments.

> e.g. if I use raw tcp/ip, i.e. with the address 127.0.0.1, port 12345 ?
> or if I use something totally different, i.e. USB or RS232?
> would "transport" and "serviceUrl" then be simply omitted?

It seems like transport would be useful for specifying that it is TCP/IP.
Maybe something like:
"transport":"TCP/IP",
"serviceUrl","127.0.0.1:12345",

> I think this means that I have to specify a method twice if it can be
> called
> both with named or positional parameters. right?
>
> I would probably prefer 1 definition per method (like in your JSON
> Schema), and
> completely let the user decide if he wants to use named or positional
> parameters.
> example (in valid JSON):

Certainly some servers will want it one way, and one way only (like all 1.0
servers).

>
> "methods": {
> "add": {
> "parameters": [
> {"type": "integer", "default": 0, "name": "summand1"},
> {"type": "integer", "default": 0, "name": "summand2"},
> ],
> "returns": "integer"
> },
> ...
> }
>
> where "parameters" is always an array, and "name" may be optional.

So if the names are omitted, than one can assume that positional parameters
are required for the defined method? Then servers that can only handle
positional parameters can omit names when they want to indicate that only
positional parameters are allowed for this method. That makes sense, I have
no objections to that. However, will there be servers with methods that only
support named parameters? How will that be indicated?

>> [X] Yes, this has potential to be a recommended service description for
>> JSON-RPC 1.1
> yes, if it is not transport-specific (=if it works for every transport I
> chose).

Definitely, I agree.

[Roland Koebler]

> It seems like transport would be useful for specifying that it is TCP/IP.
> Maybe something like:
> "transport":"TCP/IP",
> "serviceUrl","127.0.0.1:12345",

ok.

> > "methods": {
> > "add": {
> > "parameters": [
> > {"type": "integer", "default": 0, "name": "summand1"},
> > {"type": "integer", "default": 0, "name": "summand2"},
> > ],
> > "returns": "integer"
> > },
> > ...
> > }
> >
> > where "parameters" is always an array, and "name" may be optional.
> So if the names are omitted, than one can assume that positional parameters
> are required for the defined method? Then servers that can only handle
> positional parameters can omit names when they want to indicate that only
> positional parameters are allowed for this method.

that would be possible, but somehow inelegant.

I think it would be better to separate the "methods-definition" from the
"which-invocations-does-the-server-support"-definition.

My spontaneous idea would be:
- use some kind of "server-capabilities-description", which says what
capabilities the server has (e.g. "JSON-RPC 1.1", "Extension foo",
"Extension bar", "only positional parameters", ...)
Since I don't have any experience with service descriptions, I don't
know how this should look like in detail, but I think that other
RPCs may have something like this.
- and method-descriptions, which "only" describe the methods.

regards,
Roland

[Dustin]

> It seems like transport would be useful for specifying that it is TCP/IP.
> Maybe something like:
> "transport":"TCP/IP",
> "serviceUrl","127.0.0.1:12345",

Would people prefer "resource" to "serviceUrl" or some other generic
name?

> So if the names are omitted, than one can assume that positional parameters
> are required for the defined method? Then servers that can only handle
> positional parameters can omit names when they want to indicate that only
> positional parameters are allowed for this method. That makes sense, I have
> no objections to that. However, will there be servers with methods that only
> support named parameters? How will that be indicated?
>

I've switched the original example at http://dojotoolkit.org/~dmachi/rpc
to be an array in all cases. I would define the behavior as such:

array w/o a "name" property - client accepts positioned arguments,
server accepts positioned arguments only
array w/ "name" - client MUST accept named parameters, and can
optionally accept positioned parameters as well. Server MUST accept
named parameters.

> > but because I have not yet played with service-descriptions in real
> > applications, I cannot tell you more...

This is really a pretty simple system and has been in use for a couple
of years. However this updated SMD spec is more flexible in that it
is designed allow more service types and for service types to be
combined in a single service definition. I realize that this might
not be important to this group, however it has proven very useful for
Dojo as well as customer rpc types that i've use in several different
projects.

Dustin

[Dustin]

> > > where "parameters" is always an array, and "name" may be optional.
> > So if the names are omitted, than one can assume that positional parameters
> > are required for the defined method? Then servers that can only handle
> > positional parameters can omit names when they want to indicate that only
> > positional parameters are allowed for this method.
>
> that would be possible, but somehow inelegant.

Ewps, I'm not used to this interface and missed this message before my
last reply to Kris' note. It seems to me that this is really a mainly
a client hint. It is up to the envelope to decide how to encode the
parameters and it doesn't care what these settings are.

>
> I think it would be better to separate the "methods-definition" from the
> "which-invocations-does-the-server-support"-definition.
>
> My spontaneous idea would be:
> - use some kind of "server-capabilities-description", which says what
> capabilities the server has (e.g. "JSON-RPC 1.1", "Extension foo",
> "Extension bar", "only positional parameters", ...)
> Since I don't have any experience with service descriptions, I don't
> know how this should look like in detail, but I think that other
> RPCs may have something like this.
> - and method-descriptions, which "only" describe the methods.
>

Its important to keep this simple, and I would rather leave this up to
the loosely defined "envelope". In terms of the dojo.rpc client, this
defines how to encode a message properly for the given transport as
well as how to deserialize. It could potentially do other things too
of course in other environments. Right now some example envelopes
might be "None", "JSON-RPC-1.0", "JSON-RPC-1.1".