Enclosed is a JSON Schema document for ALTO that uses version 4 JSON Schema
notation. It has been used with client side editors such as JSON Editor (demo
at http://jeremydorn.com/json-editor/) to visualize the forms and help debug
both schema and RFC examples.
Use it as you like, it is presented here AS IS (no warranties expressed or
implied ;)) as to its accuracy but it has been successfully tested against RFC
examples and other working ALTO code.
MINOR issues exist / were discovered as part of this work:
1. MINOR ERROR IN RFC 7285 there an issue in Section 9.2.3 Example, the last
endpoint-property (path is #/resources/endpoint-property/capabilities) has a
comma even though it is the last property in the object.
2. ANNOYANCES IN JSON Editor reloading the schema can be problematic based upon
the browser you use and the editor does NOT parse dotted property names well at
all (only displays the last portion of the name after the last '.').
3. MINOR ISSUES IN the Schema -
a. There is heavy use of pattern properties & 'additional properties = true'
which is problematic for some tools but in JSON Schema's definition.
b. Overriding the meta definition in the responses is a bit challenging for
editors as the property appears twice in the base object reference - depending
upon the implementation of the inclusion method in JSON schema when using a
$ref results and a property override, the editor may be a bit inconsistent in
the UI and how default values are implemented when the form is initially loaded.
4. Even though it is included in the schema, 'code' (error code) is never used
- we may look at formally defining a response type in the schema to correct
that.
I hope others find it useful. If anyone makes extensions / corrections it
would be great if they make it (or it's location) available on the list.
Lyle
---------- alto.jsd ---------
{
"$schema": "http://json-schema.org/draft-04/schema#";,
"id":"#root",
"oneOf":[
{ "_comment": "Information Resource Directory Response",
"$ref": "#/definitions/InfoResourceDirectory" },
{ "_comment": "Service Information Resource - Network Map Response",
"$ref": "#/definitions/InfoResourceNetworkMap" },
{ "_comment": "Service Information Resource - Cost Map Response",
"$ref": "#/definitions/InfoResourceCostMap" },
{ "_comment": "Service Information Resource - Filtered Map Request",
"$ref": "#/definitions/ReqFilteredNetworkMap" },
{ "_comment": "Service Information Resource - Filtered Cost Map
Request",
"$ref": "#/definitions/ReqFilteredCostMap" },
{ "_comment": "Service Information Resource - Endpoint Properties
Request",
"$ref": "#/definitions/ReqEndpointProp" },
{ "_comment": "Service Information Resource - Endpoint Properties
Response",
"$ref": "#/definitions/InfoResourceEndpointProperties" },
{ "_comment": "Service Information Resource - Endpoint Cost Map
Request",
"$ref": "#/definitions/ReqEndpointCostMap" },
{ "_comment": "Service Information Resource - Endpoint Cost Map
Response",
"$ref": "#/definitions/InfoResourceEndpointCostMapResponse" }
],
"additionalProperties": true,
"definitions" : {
"_comment" : "Sections 8 & 10 as well as common data structures / patterns",
"MediaType" : {
"id":"#mediatype",
"title":"Media Type",
"_comment":"Media Type pattern as defined by RFC 7231 (formerly RFC 2046)",
"type":"string",
"pattern":"[^()<>@,;:\\ \"/?={}/\t[\\]\\\\]+/[^()<>@,;:\\
\"/?={}/\t[\\]\\\\]+(;[^()<>@,;:\\ \"/?={}/\t[\\]\\\\]+=(([^()<>@,;:\\
\"/?={}/\t[\\]\\\\]+)|(\"(?:[^\"\\\\]|\\\\.)*\")))*"
},
"ResponseMeta" : {
"id":"#responsemeta",
"title":"Response Meta Information",
"_comment":"Section 8.4.1",
"type":"object",
"additionalProperties":true
},
"ResponseEntityBase" : {
"id":"#responseentitybase",
"title":"Response Entity Base",
"_comment":"Section 8.4",
"type":"object",
"properties" : {
"meta" : {
"title":"meta information pertaining to the response",
"$ref":"#/definitions/ResponseMeta"
}
},
"additionalProperties":true
},
"code" : {
"id":"#errorcode",
"title":"Error Code",
"_comment":"Section 8.5.2",
"enum" : [ "E_SYNTAX", "E_MISSING_FIELD", "E_INVALID_FIELD_TYPE",
"E_INVALID_FIELD_VALUE" ]
},
"PIDName" : {
"id":"#pidname",
"_comment":"Section 10.1",
"type":"string",
"pattern":"[A-Za-z0-9-:@_.]+",
"maxLength":64,
"minLength":1
},
"ResourceID" : {
"id":"#resourceid",
"_comment":"Section 10.2",
"type":"string",
"pattern":"[A-Za-z0-9-:@_.]+",
"maxLength":64,
"minLength":1
},
"VersionTag" : {
"id":"#versiontag",
"_comment":"Section 10.3",
"title":"Version",
"type":"object",
"properties" : {
"resource-id":{ "$ref" : "#/definitions/ResourceID" },
"tag":{
"type":"string",
"minLength":1,
"maxLength":64,
"pattern":"[\u0021-\u007E]+"
}
},
"required" : [ "resource-id", "tag" ]
},
"TypedEndpointAddr":{
"id":"#typedendpointaddress",
"_comment":"Section 10.4.2",
"title":"Endpoint Address",
"type":"string",
"oneOf" : [
{ "pattern":
"ipv4:((([01]?[0-9][0-9]?)|(2[0-4][0-9])|(25[0-5]))\\.){0,3}((([01]?[0-9][0-9]?)|(2[0-4][0-9])|(25[0-5])))"},
{ "pattern":
"ipv6:(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])):"
},
{ "pattern":
"^((?!ipv4|ipv6)[\u0030-\u0039\u0041-\u005a\u0061-\u007a]+:(.+))" }
]
},
"AddressType":{
"id":"#addresstype",
"_comment":"Section 10.4.2",
"title":"Address Type",
"enum":[ "ipv4", "ipv6" ]
},
"IPV4AddressPrefix" : {
"id":"#ipv4addrprefix",
"_comment":"Section 10.4.4.1",
"type":"string",
"pattern":"((([01]?[0-9][0-9]?)|(2[0-4][0-9])|(25[0-5]))(\\.|(\\/(([12]?\\d)|(3[1-2]))$))){4}"
},
"IPV6AddressPrefix" : {
"id":"#ipv6addressprefix",
"_comment":"Section 10.4.4.2",
"type":"string",
"format":"ipv6"
},
"EndpointAddrGroup" : {
"id":"#endpointaddrgroup",
"_comment":"Section 10.4.5",
"type":"object",
"properties" : {
"ipv4" : {
"type":"array",
"title":"ipv4 prefix list",
"items" : {
"title":"ipv4 prefix (CIDR)",
"$ref" : "#/definitions/IPV4AddressPrefix"
},
"additionalProperties":false
},
"ipv6" : {
"type":"array",
"title":"ipv6 prefix list",
"items" : {
"title":"ipv6 prefix (CIDR)",
"$ref" : "#/definitions/IPV6AddressPrefix"
},
"additionalProperties":false
}
}
},
"CostMode" : {
"title":"Cost Mode",
"_comment":"Section 10.5",
"type":"string",
"enum": [ "numerical", "ordinal" ]
},
"CostMetric" : {
"title":"Cost Metric",
"_comment":"Section 10.6",
"type":"string",
"pattern":"[A-Za-z0-9-:_.]+"
},
"CostType" : {
"title":"Cost Type",
"_comment":"Section 10.7",
"type":"object",
"properties" : {
"cost-mode": { "$ref" : "#/definitions/CostMode" },
"cost-metric": { "$ref" : "#/definitions/CostMetric" },
"description": {
"title":"Description (Optional)",
"type":"string"
}
},
"required": [ "cost-metric", "cost-mode" ]
},
"ResourceSpecificEndpointProperty" : {
"id":"#resourcespecificendpointproperty",
"_comment":"Section 10.8.1",
"title":"Resource Specific Endpoint Property",
"type":"string",
"pattern":"[A-Za-z0-9:-@_]+.pid",
"maxLength": 64,
"minLength":1
},
"GlobalEndpointProperty" : {
"id":"#globalendpointproperty",
"_comment":"Section 10.8.2",
"title":"Global Endpoint Property",
"pattern":"[A-Za-z0-9:-@_]+",
"maxLength":32,
"minLength":1
},
"EndpointPropertyType" : {
"id":"#endpointproperty",
"_comment":"Section 10.8",
"title":"Endpoint Property",
"oneOf": [
{ "$ref" : "#/definitions/ResourceSpecificEndpointProperty" },
{ "$ref" : "#/definitions/GlobalEndpointProperty" }
]
},
"_comment" : "Section 9.2 - Protocol Specification: Information Resource
Directory",
"IRDMetaCostTypes" : {
"id":"#irdmetacosttypes",
"_comment":"Section 9.2.2",
"title":"IRD Metadata - Cost Types",
"type":"object",
"patternProperties" : {
".*" : {
"type":{ "$ref" : "#/definitions/CostType" }
}
}
},
"InfoResourceDirectory" : {
"id":"#inforesourcedirectory",
"_comment":"Section 9.2.2",
"title":"ALTO Information Resource Directory Response",
"type":{"$ref":"#/definitions/ResponseEntityBase"},
"properties": {
"resources": { "$ref" : "#/definitions/IRDResourceEntries" },
"meta" : {
"title":"Meta information pertaining to response",
"$ref":"#/definitions/ResponseMeta",
"properties": {
"cost-types": { "type":{"$ref":"#/definitions/IRDMetaCostTypes"} },
"default-alto-network-map" : { "type" : "string" }
}
}
}
},
"IRDResourceEntries" : {
"id":"#irdresourceentries",
"_comment":"Section 9.2.2",
"_comment2":"Bug in json-editor requires editing in the json window",
"title":"IRD Resource Entries",
"type":"object",
"patternProperties" : {
"[A-Za-z0-9 -:@_.]+" : {
"title":"Entry",
"type":{ "$ref" : "#/definitions/IRDResourceEntry" }
}
},
"additionalProperties":false
},
"Capabilities" : {
"id":"#irdresourcecapabilities",
"_comment":"Section 9.2.2",
"title":"IRD Resource Capabilities",
"type":"object",
"additionalProperties":true
},
"IRDResourceEntry" : {
"id":"#irdresourceentry",
"_comment":"Section 9.2.2",
"title":"Information Resource Entry",
"type":"object",
"properties" : {
"uri":{"type":"string","format":"uri"},
"media-type" : { "$ref" : "#/definitions/MediaType" },
"accepts": { "$ref" : "#/definitions/MediaType" },
"capabilities": { "$ref" : "#/definitions/Capabilities" },
"uses" : {
"type" : "array",
"items" : { "$ref" : "#/definitions/ResourceID" }
}
},
"required" : [ "uri", "media-type" ]
},
"_comment": "Section 11.2 Protocol Specification: Service Information
Resources",
"_comment": "Section 11.2.1 Network Map",
"ServiceMetaInformation" : {
"id":"#serviceinfometadata",
"_comment":"Section 11.1",
"title":"Service Info Metadata",
"$ref":"#/definitions/ResponseMeta",
"properties":{
"vtag":{ "$ref":"#/definitions/VersionTag" },
"dependent-vtags":{
"type":"array",
"items":{ "$ref":"#/definitions/VersionTag" }
}
},
"additionalProperties":true
},
"InfoResourceNetworkMap" : {
"id":"#networkmap",
"_comment":"Section 11.2.1.6",
"title":"ALTO - Map Service - Network Map Response",
"type":{"$ref":"#/definitions/ResponseEntityBase"},
"properties":{
"meta":{ "$ref":"#/definitions/ServiceMetaInformation",
"required": [ "vtag" ]
},
"network-map":{ "$ref":"#/definitions/NetworkMapData" }
},
"additionalProperties":true
},
"NetworkMapData" : {
"id":"#networkmapdata",
"_comment":"Section 11.2.1.6",
"title":"Network Map Data",
"type":"object",
"patternProperties":{
"[A-Za-z0-9-:@_.]+" : {
"$ref":"#/definitions/EndpointAddrGroup"
}
}
},
"_comment": "Section 11.2.3 Cost Map",
"CostMapCapabilities" : {
"id":"#costmapcapabilities",
"_comment":"Section 11.2.3.4 - This is part of the request structure",
"title":"Cost Map Capabilities",
"type":"array",
"items":{
"type":"string",
"maxItems":1
}
},
"InfoResourceCostMap" : {
"id":"#inforesourcecostmap",
"_comment":"Section 11.2.3.6",
"title":"ALTO - Map Service - Cost Map Response",
"type":{"$ref":"#/definitions/ResponseEntityBase"},
"properties":{
"meta":{
"$ref":"#/definitions/ResponseMeta",
"properties":{
"dependent-vtags":{
"type":"array",
"items":{ "$ref":"#/definitions/VersionTag" },
"maxItems":1
},
"cost-type":{ "$ref":"#/definitions/CostType" }
},
"required" : [ "dependent-vtags", "cost-type" ],
"additionalProperties":true
},
"cost-map" : { "$ref":"#/definitions/CostMapData" }
},
"additionalProperties":true
},
"CostMapData" : {
"id":"costmapdata",
"_comment":"Section 11.2.3.6",
"title":"Cost Map Data",
"type":"object",
"patternProperties":{
"[A-Za-z0-9-:@_.]+":{ "$ref":"#/definitions/DstCosts" }
},
"additionalProperties":true
},
"DstCosts" : {
"id":"#dstcosts",
"_comment":"Section 11.2.3.6",
"title":"Destination Costs",
"type":"object",
"patternProperties":{
"[A-Za-z0-9-:@_.]+": { "type":"any" }
},
"additionalProperties":true
},
"_comment":"11.3.1 - Filtered Network Map",
"ReqFilteredNetworkMap" : {
"id":"#reqfiterlednetworkmap",
"_comment":"Section 11.3.1.3",
"title":"ALTO - Map-Filtering Service - Network Map Request",
"type":"object",
"properties":{
"pids":{
"type":"array",
"items":{ "$ref":"#/definitions/PIDName" }
},
"address-types":{
"type":"array",
"items":{ "$ref":"#/definitions/AddressType" }
}
},
"required": [ "pids" ]
},
"_comment":"11.3.2 - Filtered Cost Map",
"ReqFilteredCostMap" : {
"id":"#reqfilteredcostmap",
"_comment":"Section 11.3.2.3",
"title":"ALTO - Map-Filtering Service - Cost Map Request",
"type":"object",
"properties":{
"cost-type":{ "$ref":"#/definitions/CostType" },
"constraints":{
"type":"array",
"items":{ "type":"string" }
},
"pids":{ "$ref":"#/definitions/PIDFilter" }
},
"required": [ "cost-type" ]
},
"PIDFilter" : {
"id":"#pidfilter",
"_comment":"Section 11.3.2.3",
"title":"PID Filter",
"type":"object",
"properties":{
"srcs":{
"type":"array",
"items":{ "$ref":"#/definitions/PIDName" }
},
"dsts":{
"type":"array",
"items":{ "$ref":"#/definitions/PIDName" }
}
},
"required": [ "srcs", "dsts" ]
},
"FilteredCostMapCapabilities" : {
"id":"#mapcapabilitiesfilter",
"_comment":"Section 11.3.2.4",
"title":"Cost Map Capabilities Filter",
"type":"object",
"properties":{
"cost-type-names":{
"type":"array",
"items":{ "type":"string" }
},
"cost-constraints":{ "type":"boolean" }
},
"required": [ "cost-type-names", "cost-constraints" ]
},
"_comment": "Section 11.4.1 - Endpoint Property",
"ReqEndpointProp": {
"id":"#endpointpropertiesreq",
"_comment":"Section 11.4.1.3",
"title":"ALTO - Endpoint Property Service - Request",
"type":"object",
"properties":{
"properties_":{
"type":"array",
"items":{ "$ref":"#/definitions/EndpointPropertyType" }
},
"endpoints":{
"type":"array",
"items":{ "$ref":"#/definitions/TypedEndpointAddr" }
}
},
"required": [ "properties_", "endpoints" ]
},
"EndpointPropertyCapabilities": {
"id":"#endpointpropcapabilities",
"_comment":"Section 11.4.1.4",
"title":"Endpoint Property Capabilities",
"type":"object",
"properties":{
"prop-types":{
"type":"array",
"items":{"$ref":"#/definitions/EndpointPropertyType"}
}
}
},
"InfoResourceEndpointProperties":{
"id":"#endpointpropinforesource",
"_comment":"Section 11.4.1.6",
"title":"ALTO - Endpoint Property Service - Response",
"type":{"$ref":"#/definitions/ResponseEntityBase"},
"properties":{
"meta" : {
"$ref":"#/definitions/ResponseMeta",
"dependent-vtags":{
"type":"array",
"items":{ "$ref":"#/definitions/VersionTag" }
},
"required" : [ "dependent-vtags" ],
"additionalProperties":true
},
"endpoint-properties" : {
"$ref":"#/definitions/EndpointPropertyMapData"
}
}
},
"EndpointPropertyMapData":{
"id":"#endpointpropmapdata",
"_comment":"Section 11.4.1.6",
"title":"Endpoint Property Data",
"type":"object",
"patternProperties":{
"ipv4:.*":{ "$ref":"#/definitions/EndpointProps" },
"ipv6:.*":{ "$ref":"#/definitions/EndpointProps" }
},
"additionalProperties":true
},
"EndpointProps":{
"id":"#endpointprops",
"_comment":"Section 11.4.1.6",
"title":"Endpoint Properties",
"type":"object",
"patternProperties":{
"[A-Za-z0-9:-@_]+":{"type":"any"},
"[A-Za-z0-9:-@_]+.pid":{"type":"any"}
}
},
"_comment": "Section 11.5.1 - Endpoint Cost Service",
"ReqEndpointCostMap":{
"id":"#reqendpointcostmap",
"_comment":"Section 11.5.1.3",
"title":"ALTO - Endpoint Cost Service - Request",
"type":"object",
"properties" : {
"cost-type":{ "$ref":"#/definitions/CostType" },
"constraints":{
"type":"array",
"items":{ "type":"string" }
},
"endpoints":{ "$ref":"#/definitions/EndpointFilter" }
},
"required": [ "cost-type", "endpoints" ]
},
"EndpointFilter" : {
"id":"#endpointfilter",
"_comment":"Section 11.5.1.3",
"title":"Endpoint Filter",
"type":"object",
"properties" : {
"srcs":{
"type":"array",
"items":{ "$ref":"#/definitions/TypedEndpointAddr" }
},
"dsts":{
"type":"array",
"items":{ "$ref":"#/definitions/TypedEndpointAddr" }
}
}
},
"InfoResourceEndpointCostMapResponse" : {
"id":"#endpointcostmapresponse",
"_comment":"Section 11.5.1.6",
"title":"ALTO - Endpoint Cost Service - Response",
"type":{"$ref":"#/definitions/ResponseEntityBase"},
"properties":{
"meta" : {
"cost-type":{ "$ref":"#/definitions/CostType" },
"additionalProperties":true
},
"endpoint-cost-map" : {
"$ref":"#/definitions/EndpointCostMapData"
}
},
"required" : [ "meta", "endpoint-cost-map" ]
},
"EndpointCostMapData" : {
"id":"#endpointcostmapdata",
"_comment":"Section 11.5.1.6",
"title":"Endpoint Cost Map Data",
"patternProperties":{
"ipv4:.*":{ "$ref":"#/definitions/EndpointDstCosts" },
"ipv6:.*":{ "$ref":"#/definitions/EndpointDstCosts" }
},
"additionalProperties":true
},
"EndpointDstCosts" : {
"id":"#endpointdstcosts",
"_comment":"Section 11.5.1.6",
"title":"Endpoint Dst Costs",
"patternProperties":{
"ipv4:.*":{ "type":"any" },
"ipv6:.*":{ "type":"any" }
},
"additionalProperties":true
}
}
}
________________________________
This e-mail may contain Sprint proprietary information intended for the sole
use of the recipient(s). Any use by others is prohibited. If you are not the
intended recipient, please contact the sender and delete all copies of the
message.
_______________________________________________
alto mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/alto
