XML-RPC base64 and date/time value types

[Alexandre Morgaut]

a method published over the web might be either callable from :
- SOAP
- XML-RPC
- JON-RPC
interfaces

RPC interfaces are really simpler than SOAP, but JSON-RPC could
support all method published over XML-RPC

There one thing I identify as not implemented by default in JSON-RPC :
the base64 value type

Here how XML-RPC types can be mapped to JSON(-RPC) types

array -> array
base64 -> ???
boolean -> boolean
date/time -> ???
double -> number
integer -> number
string -> string
struct -> object
nil -> null

JSON don't have date/time and base64 type defined, but if the way to
represent it in JSON-RPC, all implementation which will want to bind
XML-RPC published methods automatically to a JSON-RPC interface might
do it in different ways.

This is a Highway for inconsistency !

And JSON Schema, even if it is useful for a lot of things, wouldn't
help to "Keep It Simple Stupid" (which was what people liked in XML-
RPC compared to SOAP)

So, what about specifying it as simple as possible ?

In a JSON-RPC request or response, they might be represented as an
object with a single property with a specific name :

base64 value:

XML -> <base64>eW91IGNhbid0IHJlYWQgdGhpcyE=</base64>
JSON -> {"base64": "eW91IGNhbid0IHJlYWQgdGhpcyE="}

date/time value:

XML -> <dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>
JSON -> {"dateTime.iso8601": "19980717T14:08:55"}
or shorter :
JSON -> {"dateTime": "19980717T14:08:55"}

This hasn't to be included in the JSON-RPC specification (even if it
would be then more visible)
It might be specified in a separated document as JSON-RPC over HTTP
is.

[Gaetano Giunta]

Alexandre Morgaut wrote:
> a method published over the web might be either callable from :
> - SOAP
> - XML-RPC
> - JON-RPC
> interfaces
>
> RPC interfaces are really simpler than SOAP, but JSON-RPC could
> support all method published over XML-RPC
>
> There one thing I identify as not implemented by default in JSON-RPC :
> the base64 value type
>
> Here how XML-RPC types can be mapped to JSON(-RPC) types
>
> array -> array
> base64 -> ???
> boolean -> boolean
> date/time -> ???
> double -> number
> integer -> number
> string -> string
> struct -> object
> nil -> null
>

Note: nil is not officially supported by XMLRPC, and there are 2
different extensions to implement it (<NIL/> and <EX:NIL/>).
You might as well want to specify this in the reverse mapping.

As for doubles/integers: there is a minor loss of information if using
JSONRPC to transport XMLRPC ints and doubles.
A simple "best practice" could be to always encode in JSONRPC your
double values with a '.0' appended. This way the receiving party can
decide what data type to rebuild, eg:
12.0 => double
12 => int

[Kris Zyp]

As far as date/time goes, the JSON reference implementation
(http://www.json.org/json2.js) as well all browser that have implemented
JSON serialization, serialize dates to plain ISO 8601 dates in UTC (not
objects with a "dateTime.iso8601" property). If you are hoping for
consistency, that is the best path.

JSON.stringify(new Date()) -> "2009-09-07T14:06:38.482Z"

Kris

[Omi]

Inline with Kris, I believe its best to keep the datatype
representation up to JSON aka Javascript as the representation is what
JSON-RPC uses as its base schema.
For base64 and other none integer or boolean types, I believe the
current approach used is to leave the interpretation of the type to
the server and client.

However, if we were to include service discovery within the spec, I
believe we would need to address some of the type issues.

[Alexandre Morgaut]

I proposed the object notation for two reasons :

- to make it easier to detect the type from the value. With a simple
string we need to perform a regex on the string (which should consider
values with only time part, or only date part), and we might convert
into date objects values which were meant to be read as strings

- the date support isn't part of the JSON specification AND dates are
only supported by the "stringify()" method, not by the "parse()" one
(surely because of the problem exposed in my first reason)

But I'm open if we find a solution to this

[Alexandre Morgaut]

I saw in the specification that method names starting with "rpc." are
reserved for extensions
This restriction doesn't exist for property names of object
parameters...
It could... Even if it is allowed by JSON and works in JavaScript,
object property names rarely use the dot "." character

So, to prevent any conflict with object parameter with a "date" or
"base64" property name, they might become as this :

base64 value:

XML -> <base64>eW91IGNhbid0IHJlYWQgdGhpcyE=</base64>

JSON -> {"rpc.base64": "eW91IGNhbid0IHJlYWQgdGhpcyE="}

date/time value:

XML -> <dateTime.iso8601>19980717T14:08:55</dateTime.iso8601>

JSON -> {"rpc.dateTime": "19980717T14:08:55"}


As nil can be exposed as <NIL /> or <EX:NIL />, If the server already
provided XML-RPC with an implementation of NIL, it should still use
the same (and should its clients)
Otherwise It is up to the implementation to provide a default notation
from these both, and a way for the administrator to provide any of
them

Clients and servers can send themselves an information of which
notation it prefer:

Example over HTTP:

via HTTP headers

POST /RPC HTTP/1.0
Host: betty.userland.com
Accept: text/xml, application/json-rpc
X-Accept-Nil: EX:NIL, NIL
Content-Type: text/xml
Content-length: 181

<?xml version="1.0"?>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param> <value><i4>41</i4></value> </param>
</params>
</methodCall>


Here the client says to the server it accept both notations for NIL
X-Accept-Nil: EX:NIL, NIL



via the QueryString


POST /RPC?accept-nil=ex:nil HTTP/1.0
...

here the client says to the server it only support the "<EX:NIL />"
notation


The second technique is easier to implement for existing XML-RPC
clients as they just have to adjust the URL they call

So a server supporting XML-RPC and JSON-RPC can expose all its RPC
method to both services