Dear Lyle, Wonderful post!
Please see below. On Wed, May 20, 2015 at 1:58 PM, Bertz, Lyle T [CTO] < [email protected]> wrote: > 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 > https://urldefense.proofpoint.com/v2/url?u=http-3A__jeremydorn.com_json-2Deditor_&d=AwICAg&c=-dg2m7zWuuDZ0MUcV7Sdqw&r=4G36iiEVb2m_v-0RnP2gx9KZJjYQgfvrOCE3789JGIA&m=Cm8YFuZ90nEsfS77q3sytQPJuEAu0GcUfqKwW0uAjA0&s=FBWLx5Ka5nU0-HGkGijyxjxO8Af_RphWtpU3xdkKyPc&e= > ) to visualize the forms and help debug both schema and RFC examples. > > It is very cool to have this schema. Thanks a lot! > 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. > This is indeed a left over comma. We should file an errata. > > 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. > It will be good to define this formally. Richard > > 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": " > https://urldefense.proofpoint.com/v2/url?u=http-3A__json-2Dschema.org_draft-2D04_schema-23&d=AwICAg&c=-dg2m7zWuuDZ0MUcV7Sdqw&r=4G36iiEVb2m_v-0RnP2gx9KZJjYQgfvrOCE3789JGIA&m=Cm8YFuZ90nEsfS77q3sytQPJuEAu0GcUfqKwW0uAjA0&s=s6TdMWKIqF5_s9dkwOef-kxdCschXs4abzfu0x1ga1s&e= > ", > "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://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_alto&d=AwICAg&c=-dg2m7zWuuDZ0MUcV7Sdqw&r=4G36iiEVb2m_v-0RnP2gx9KZJjYQgfvrOCE3789JGIA&m=Cm8YFuZ90nEsfS77q3sytQPJuEAu0GcUfqKwW0uAjA0&s=wmmNx1LkhO9tbyfKs3chpq_FTIQylhv6911l4TkdLlE&e= > -- -- ===================================== | Y. Richard Yang <[email protected]> | | Professor of Computer Science | | http://www.cs.yale.edu/~yry/ | =====================================
_______________________________________________ alto mailing list [email protected] https://www.ietf.org/mailman/listinfo/alto
