Subject: [alto] ALTO JSON Schema Collection

From: Jensen Zhang <[email-masked]>
Date: Mon, 22 Mar 2021 23:13:24 +0800

Hi all,

As multiple ALTO extensions have been or are going to be published and
introduce multiple versions of the ALTO message formats, I just create a
GitHub repo to maintain a collection of JSON schemas that can be used to
validate ALTO protocol messages in different versions:
https://github.com/openalto/alto-jsonschema

All the JSON schemas use version 7 JSON Schema notation. So far, all the
published RFCs (RFC7285, RFC8189, RFC8895, RFC8896) have been included. The
working drafts that are close to being published are on the way.

Note that each ALTO message format may have multiple versions of JSON
schemas, because multiple standards may extend the same message format. For
example,

1. RFC7285 defines ReqFilteredCostMap, and RFC8189 extends it and modifies
the validation condition. The following ReqFilteredCostMap message can only
pass the validation by JSON schemas applying RFC8189. The RFC7285 version
JSON schema will raise an error about "the required field cost-type is
missing".

~~~
{
    "multi-cost-types": [
        {"cost-mode": "numerical", "cost-metric": "routingcost"},
        {"cost-mode": "numerical", "cost-metric": "shoesize"}
    ],
    "pids" : {
        "srcs" : [ ],
        "dsts" : [ ]
    }
}
~~~

2. RFC7285 defines InfoResourceCostMap, and RFC8896 extends it. The RFC7285
version JSON schema will ignore "meta/calendar-response-attributes" and
pass the validation of the following InfoResourceCostMap message, while the
RFC8896 version schema will raise an error about
"meta/calendar-response-attributes should be an array".

~~~
{
    "meta" : {
        "dependent-vtags" : [
            {
                "resource-id": "my-default-network-map",
                "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"
            }
        ],
        "cost-type" : { "cost-mode" : "numerical", "cost-metric" :
"throughputrating" },
        "calendar-response-attributes" : {}
    },
    "cost-map" : {
        "PID1": {
            "PID1": [ 1, 12, 14, 18, 14, 14, 14, 18, 19, 20, 11, 12],
            "PID2": [13,  4, 15, 16, 17, 18, 19, 20, 11, 12, 13, 14],
            "PID3": [20, 20, 18, 14, 12, 12, 14, 14, 12, 12, 14, 16]
        }
    }
}
~~~

The README file shows the link to each version of the JSON schema file.
Also, the `examples` directory includes all the JSON format ALTO message
examples appearing in RFCs.

There is an online validator demo that you can use to try the schemas:
https://openalto.github.io/alto-jsonschema/

I hope it will be helpful for others. Also, welcome to extend / correct /
improve it.

Best,
Jensen