Subject: [alto] ALTO JSON schema

From: "Y. Richard Yang" <[email-masked]>
Date: Thu, 14 Mar 2013 15:53:35 -0400

Dear all,

We are revising the ALTO base protocol. One item that we are considering to
change is some clarification of the specification schema for the base
protocol. Attached is a proposed schema. The changes and their impacts are
the following:

- Change 1.

We added a new schema called object-map. The basic problem that we are
trying to solve is the "ambiguity" of JSON deserialization. Specifically,
an JSON object { "a1":"v1", "a2":"v2"} can have interpretations: it is an
object of type
object {
  String a1;
  String a2;
}
or a HashMap object from strings to strings.

Now consider the encoding of a network map:
       "map" : {
         "PID1" : {
           "ipv4" : [
             "192.0.2.0/24",
             "198.51.100.0/24"
           ]
         },
         "PID2" : {
           "ipv4": [
             "198.51.100.128/24"
           ]
         }
       }

Now if we use the first interpretation, we need to define many class types,
one for each given number of PIDs. This is too many classes. We also
considered an array like encoding:
       "map" : [
         {"PID1" : {
           "ipv4" : [
             "192.0.2.0/24",
             "198.51.100.0/24"
           ]
         }},
         {"PID2" : {
           "ipv4": [
             "198.51.100.128/24"
           ]
         }}
       }

But this reads ugly according to several. Hence, we decided to use the
current encoding. But we give a hint that the encoding is better a HashMap
(key/value store), and hence only a single class.

Suppose one uses GSON as a parser, it is quite easy to construct:
   //    Map<String, EndpointAddrGroup> map
   //      = gson.fromJson(json,
   //          new TypeToken<Map<String, EndpointAddrGroup>>()
{}.getType());

IMPACT: It does not change the data format on the wire but conceptually
cleaner.

* Change 2.

We added a new type:
   object {                  // still separate mode and type but syntax
sugar
     CostMode mode;          // to put in the same object
     CostType type;
   } CostID;

This is based on the consensus that we separate mode and type. Wendy put
the motivation of change better than I could. So here is  her words:

"Here's how I'd describe the change. Before, the cost map request &
response messages had "cost-type" and "cost-mode" fields. Now they have
nested "cost-id.type" and "cost-id.mode" fields. That should be a simple
change for any implementation.

For a full map request, the IRD has a similar straight-forward change: in
the capabilities section, the "cost-type" and "cost-mode" fields have been
replaced by the nested "cost-id.type" and "cost-id.mode" fields.

The major difference is in the IRD entry for a filtered cost map request.
Before the server listed all valid types and modes. Now the server
specifies the valid pairs. The advantage is now the client can tell which
combinations are supported. Before, the client found out the hard way.

And the primary motivation for cost-ids is to resolve that problem with
filtered cost maps. Otherwise cost-ids are syntactic sugar."

IMPACT: Existing implementations need to merge cost-mode and cost-type into
a single object, which is a very minor change.

The authors have not made the final decisions to make the changes. Any
comments are highly welcome!

Richard