A YANG Data Model for Base ALTO Data and Services
Yale University51 Prospect StreetNew HavenCT06511USAxiao.shi@yale.eduYale University51 Prospect StNew HavenCTUSAyang.r.yang@gmail.comAlcatel-Lucent Bell LabsLorenzstrasse 1070435StuttgartGermanymichael.scharf@alcatel-lucent.com
Networks
ALTO Working GroupALTO
The Application-Layer Traffic Optimization (ALTO) protocol
defines a set of network information services, including the network-map service,
the cost-map service, the filtered map services, the endpoint property service, and the endpoint cost service. A meta service, called the information resource directory (IRD) service,
allows an ALTO server to provide ALTO clients with meta information (e.g., the access URI)
about each resource and service it provides. uses a RESTful
design and encodes client request parameters and server responses using JSON. One may
consider that most of these services are based on data maintained at an ALTO
server. Hence, in this document, we explore how one may use the data modeling
language YANG to specify the services defined in . We first define two YANG models for RPC specification and data instance description of
of ALTO services. We then discuss the "standard operations" defined in
NETCONF/RESTCONF to evaluate potential integration.
This document explores how one may use the data modeling language YANG
to specify the network information services defined in the Application-Layer Traffic
Optimization (ALTO) protocol . In particular, this work is
motivated by the recent substantial interest in the networking community to use YANG
in networking protocol specification and development. This interest is highly justified,
given that the potential benefits of using a formal specification can be multifold,
including both precision and the potential of automation. However, at the same time,
data modeling languages are generally domain specific languages (DSL) and hence are restricted by
their specific domains. For example, YANG is developed in the specific domain of modeling
configuration and state data stored at network devices. ALTO information does not fit in this
domain but is highly related: ALTO information should be derived from network configuration
and state data. Hence, modeling ALTO using YANG provides an interesting exercise on how one
may apply YANG slightly outside its original domain.
The initial goal of this document was to produce an ALTO specification using YANG so
that the YANG specification of ALTO, which we refer to as ALTO/YANG, and the original
specification can inter-operate. We refer to an interop specification
as a syntactically equivalent specification. In other words, the ALTO/YANG specification
produces the same behavior as that of the original specification. Unfortunately, as we
have shown in , even without the need to
consider other components such as NETCONF/RESTCONF to construct a complete YANG system, the
basic encoding rule of YANG already makes syntactic equivalence unfeasible. In particular,
makes extensive use of the common key-value store abstraction in
its JSON object encoding. But such encoding cannot be generated using the existing YANG/JSON
encoding. As a result, the focus of this document is on using YANG to define semantically
equivalent ALTO services. We still strive that the syntax generated by ALTO/YANG is
close to that of .
The rest of this document is organized as follows. In Section , we provide an overview
of our design approaches. We discuss three specification approaches, considering the three use cases
of YANG. In Section 3, we discuss more detailed specification issues that we have encountered.
The detailed specification of ALTO/YANG is in Appendix A.
Our design tries to use YANG in three aspects: (1) RPC specification, (2) data instance description,
and (3) standard operations. These three aspects are not mutually exclusive of each other, but assume
different levels of matching and use of YANG.
The RPC specification aspect allows precise specification and automation
of RPC input/output data serialization and deserialization. This aspect of using YANG can be considered
the simplest. The protocol to be specified does not need to match the operational model of YANG. In
Section , we specify a YANG model named alto-service-rpc that uses YANG only in this aspect.
The data instance description and standard operations aspects are analogous to databases.
In relational database, one uses SQL to describe the data schema
(e.g., in CREATE TABLE). We refer to this process of modeling the data as the data instance description aspect. Modeling the data in YANG
does not guarantee full compatibility with the operational model of the existing protocol. In particular,
the data instances specified in a YANG model may be virtual in a protocol design. In
Section , we specify a YANG model named alto-service-did that uses YANG
to specify both RPCs and potential ALTO base data instances to implement certain services.
SQL also defines statements such as SELECT, INSERT, UPDATE, and
DELETE. With a DBMS implementing SQL, when a user has a new set of data to be managed, the user describes
the new data schema. The existing statements are already available to retrieve and manipulate the data.
This substantially reduce the efforts to introduce and manage a new set of data.
We refer to this as the standard operations aspect. In YANG related efforts,
NETCONF and RESTCONF each tries to provide some of these standard operations (e.g., RESTCONF query).
To utilize this aspect, the YANG specification need to be "embedded" in the chosen
specification (e.g., NETCONF). In Section , we discuss specification by
considering that the YANG model has the support of "standard operations" defined in RESTCONF. This document
does not provide a specific specification, and will do so in the next version.
Figure 1 gives the tree diagram of a YANG model named alto-service-rpc to specify ALTO services. As it is clear from the specification, it has only RPCs, which are supported by typedef and grouping not shown in the tree diagram. Such a model is still valuable in that it clarifies the input and output data format of ALTO services.
Figure 2 shows the tree diagram of a second YANG model for ALTO, named alto-service-did. Comparing Figure 1 with
Figure 2, one can observe that a key difference is that the second model first introduces data instances, listed under resources, that an ALTO server may maintain. We use the word "may"
because an ALTO server may not physically store such data. For example, a cost map could be generated on the fly, and hence can be in a sense a virtual data table. One may observe from
our specified instances that we do not specify a data instance to support the endpoint cost
service (ECS), as this can be highly inefficient. For ECS, the value of YANG is mainly in RPC specification.
Our next model considers standard operations. In other words, if an RPC can be implemented using a standard operation, the model may use the standard operation and not specify the RPC.
Consider NETCONF. One may use the NETCONF <get> operation to retrieve the full ALTO network map, cost map, and the Information Resource Directory; with the <filter> parameter, NETCONF may retrieve filtered maps as well as endpoint properties. Hence, one may omit the corresponding RPCs defined in alto-service-did. The exact encoding of using "standard operations", however, can be less compact.
ALTO is a JSON based protocol and makes extensive use of JSON key-value store, which is useful because of its efficiency, inherent uniqueness constraint on the keys, and its natural correspondence to and from structures such as indexed database tables or hashmaps.
For example, the network map is defined as mapping from a PID to an endpoint address group. Here is an example network map in Section 11.2.1.7 of .
As pointed out in , such JSON objects cannot
be modeled in YANG. To achieve the semantical equivalence, we took the approach of modeling it as a "list" with a unique index ("key) in YANG.
According to , the above YANG model correspond to the
following JSON text:
We immediately notice a few disadvantages.
From the YANG validated JSON message alone, it is unclear that the "pid" field is the key
to the list "network-map";
The YANG-validated JSON message is much more verbose, which increases
the payload, especially when the model scales.
The consistency between address-type and endpoint-prefix is not enforced in the above YANG model.
Leafrefs in YANG are heavily tied with XML and XPATH expressions. However, leafrefs cannot
refer to an rpc node (or structures within a rpc node). For example, referring to the input parameters
in rpc input from rpc output could be very useful.
For string types that have inherant relationships (e.g., extension, concatenation), it is useful to be able to extend the patterns of the strings for modularity and extensibility. For example, TypedEndpointAddress in is defined as a string of the format AddressType, followed by the ':' separator, followed by a ip-address EndpointAddress. Definitions of the pattern of an ip-address is readily available in Common YANG Data Types . It is not possible in YANG to inherit, extend, or refer to a pattern of a different string type. Another example is the resource-specific endpoint property, which is defined as a resource ID, followed by the '.' separator (U+002E), followed by a name obeying the same rules as for global endpoint property names.
YANG is unable to augment a typedef or enum type. Hence there is not a good way to
add a cost metric or type of address if the model is fixed.
Using tools like pyang (https://code.google.com/p/pyang/), we can not only validate the YANG module, but also translate the module to DSDL schema and validate instance documents. The limitation is that pyang can only validate XML files and the JSON-XML translation is not well-defined. We provide a few examples of pyang-validated ALTO messages in the appendix.
OpenDayLight (ODL) provides automatic code generation for YANG models. ODL yangtools generates a Java OSGi bundle for a given YANG module, including typedefs and groupings, data instances, and RPCs. One may integrate this bundle in the ODL controller which provides JSON parser and a RESTful API for the YANG RPCs. The datastore is automatically created and managed by ODL as well. The only manual code needed are the bundle activators and the server computation implementation.
This document does not introduce security or privacy concerns.
This document does not have IANA considerations.
The JavaScript Object Notation (JSON) Data Interchange FormatNetwork Configuration Protocol (NETCONF)Application-Layer Traffic Optimization (ALTO) ProtocolYANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)Common YANG Data TypesJSON Encoding of Data Modeled with YANGModeling JSON Messages Using YANGRESTCONF Protocol endpoint-prefix<0..*>;
} EndpointAddrGroup;
There are two challenges:
1) To specify that AddressType is key, we must use the list type,
which is the only type that one can specify key. However, the
current JSON-YANG encoding generates an array, instead of a
key-value map;
2) Ideally, we want to enforce address type and prefix
consistency; for example, an ipv6 prefix in an ipv4 type should
not be allowed. However, we encounter problems. We leave this as
an OPEN ISSUE.
*/
typedef endpoint-address-type {
type union {
type enumeration {
enum ipv4;
enum ipv6;
// EXTENSION: ADD NEW TYPE HERE
}
}
description
"Ref: RFC7285 Sec 2.2.";
}
typedef endpoint-prefix {
type inet:ip-prefix;
description
"endpoint prefix, identical to ip-prefix defined in RFC6991.";
}
grouping endpoint-address-group {
list endpoint-address-group {
key address-type;
leaf address-type {
type endpoint-address-type;
mandatory true;
}
leaf-list endpoint-prefix {
type endpoint-prefix;
}
}
description
"EndpointAddrGroup. RFC7285 Sec. 10.4.5." +
" object-map {
AddressType -> endpoint-prefix<0..*>;
} EndpointAddrGroup;";
}
/**************************************************************
* Definitions for IDs and names
*
* ALTO defines the following concepts that are names and IDs:
*
* pid name (used in network map, cost map),
* resource IDs (used to identify alto network/cost maps),
* version tag (used to indicate uniqueness of resource),
* cost-type-name (used in IRD),
* cost-metric,
* cost-mode
*
* We group their definitions together below.
**************************************************************/
typedef valid-id-string {
type string {
length "1..64";
pattern "[0-9a-zA-Z_\-:@\.]+";
}
description
"Type for valid ID strings.";
}
typedef pid-name {
type valid-id-string;
description
"Name for the PID." +
"RFC7285, Section 10.1. Note: the '.' separator MUST NOT be" +
"used unless specifically indicated in RFC7285 or an" +
" extension document.";
}
typedef resource-id {
type valid-id-string;
description
"Resource-ID.";
}
grouping vtag {
leaf resource-id {
type resource-id;
mandatory true;
}
leaf tag {
type string {
length "1..64";
pattern "[!-~]+";
}
mandatory true;
description
"Tag. RFC7285 Sec. 10.3. U+0021-U+007E";
}
description
"Version tag. Both resource-id and tag must be equal
byte-for-byte. RFC7285 Sec. 10.3." +
" object {
ResourceID resource-id;
JSONString tag;
} VersionTag;";
}
grouping dependent-vtags {
list dependent-vtags {
uses vtag;
min-elements 1;
}
}
/*************************************
Definitions for cost type and cost types
In ALTO, a cost type consists of two required components:
cost-metric,
cost-mode
and an optional description component.
In the IRD, one can name each cost type. Such info is collected
in a hash map called cost types.
*************************************/
typedef cost-metric {
type union {
type enumeration {
enum routingcost {
description
"Default metric. MUST support. RFC7285 Sec. 6.1.1.1.";
}
enum hopcount {
description
"Hopcount metric.";
}
// EXTENSION: Additional cost-metric will be defined here.
}
type string {
length 1..32;
pattern "priv:[0-9a-zA-Z_\-:\.]+";
}
}
description
"Cost metric. for type string,
'priv:' reserved for Private Use.";
}
typedef cost-mode {
type enumeration {
enum numerical {
description
"Numerical cost mode.";
}
enum ordinal {
description
"Ordinal cost mode.";
}
// EXTENSION: Additional cost-mode will be defined here.
}
description
"Cost mode. MUST support at least one of numerical and ordinal";
}
grouping cost-type {
leaf cost-mode {
type cost-mode;
mandatory true;
description
"Cost mode.";
}
leaf cost-metric {
type cost-metric;
mandatory true;
description
"Cost metric.";
}
leaf description {
type string;
description
"Optional description field.";
}
description
"Cost type. RFC7285 Sec. 10.7." +
" object {
CostMetric cost-metric;
CostMode cost-mode;
[JSONString description;]
} CostType;";
}
typedef cost-type-name {
type valid-id-string;
// NOTE: not fully specified in RFC7285, default as valid id
}
grouping cost-types {
list cost-types {
key cost-type-name;
leaf cost-type-name {
type cost-type-name;
}
uses cost-type;
}
description
"RFC 7285 Sec. 9.2.2." +
"object-map {
JSONString -> CostType;
} IRDMetaCostTypes;";
}
/**************************************
* Definitions for endpoint properties *
**************************************/
typedef global-endpoint-property {
type union {
type enumeration {
enum pid {
description "PID property.";
}
// EXTENSION: other options here
}
type string {
pattern "priv:[\w\-:@]+";
}
}
description
"Global endpoint property. RFC7285 Sec. 10.8.2." +
"'priv:' for Private Use " +
" length 1..32; ‘.’ is not allowed";
}
/*
* Ideally we would want to extend the typedef of resource-id and
* global endpoint properties, however, YANG 1.0 does not allow
* that, hence we simply copied the regex for resource-id over
* verbatim.
*/
typedef resource-specific-endpoint-property {
type string {
length "3..97"; //len(resource-id) + 1 + len(global-property)
pattern "(priv:)?[\w\-:@\.]+\.[\w\-:_]+"; // resource-id.property
}
description
"Resource-specific endpoint property.";
}
typedef endpoint-property-type {
type union {
type resource-specific-endpoint-property;
type global-endpoint-property;
}
description
"Endpoint property type. RFC7285 Sec. 10.8.";
}
typedef endpoint-property-value {
type string;
description
"Endpoint property (value).";
}
/*************************************
* Definitions for response header
*************************************/
typedef media-type {
type union {
type string {
pattern "application/alto\-.*";
}
type enumeration {
enum alto-directory+json;
enum alto-networkmap+json;
enum alto-networkmapfilter+json;
enum alto-costmap+json;
enum alto-costmapfilter+json;
enum alto-endpointprop+json;
enum alto-endpointpropparams+json;
enum alto-endpointcost+json;
enum alto-endpointcostparams+json;
enum alto-error+json;
}
}
}
grouping alto-cost {
anyxml cost {
mandatory true;
description
"ALTO cost is a JSONValue, which could be
an object, array, string, etc. (Ref: RFC 7159 Sec.3.)";
}
}
typedef constraint {
type string {
pattern "(gt|ge|lt|le|eq) [0-9]+";
}
description
"RFC7285 Sec. 11.3.2.3. The second part must be in the" +
"same unit as cost-metric, IEEE 754 2008 floating point.";
}
/******************************************
Groupings for ALTO information resource
*******************************************/
/* meta */
grouping IRD-meta {
uses cost-types;
leaf default-alto-network-map {
type resource-id;
mandatory true;
}
}
grouping network-map-meta {
container vtag {
uses vtag;
}
}
grouping cost-map-meta {
uses dependent-vtags {
refine dependent-vtags {
max-elements 1;
}
}
container cost-type {
uses cost-type;
}
}
grouping endpoint-property-meta {
uses dependent-vtags;
}
/* accepts (optional) */
grouping accepts {
leaf-list accepts {
type media-type;
min-elements 1;
}
}
/* capabilities (capabilities) */
grouping IRD-capabilities {
container capabilities {
leaf cost-constraints {
type boolean;
}
leaf-list cost-type-names {
type cost-type-name;
}
leaf-list prop-types {
type endpoint-property-type;
}
}
}
/* uses (optional) */
grouping uses {
leaf-list uses {
type resource-id;
min-elements 1;
}
}
/* Information Resource Directory Grouping */
grouping IRD {
container meta {
uses IRD-meta;
}
uses IRD-data;
}
grouping IRD-data {
list resources {
key resource-id;
leaf resource-id {
type resource-id;
mandatory true;
}
leaf uri {
type inet:uri;
mandatory true;
}
leaf media-type {
type media-type;
mandatory true;
}
uses accepts {
when "current()";
}
uses IRD-capabilities {
when "current()";
}
uses uses {
when "current()";
}
description
"IRDResourceEntry. RFC7285 9.2.2." +
" object {
JSONString uri;
JSONString media-type;
[JSONString accepts;]
[Capabilities capabilities;]
[ResourceID uses<0..*>;]
} IRDResourceEntry;" +
"IRDResourceEntries. RFC7285 9.2.2." +
" object-map {
ResourceID -> IRDResourceEntry;
} IRDResourceEntries;" +
"InformationResourceDirectory. RFC7285 9.2.2." +
" object {
IRDResourceEntries resources;
} InfoResourceDirectory : ResponseEntityBase;";
}
}
/* Network Map Grouping */
grouping network-map {
container meta {
uses network-map-meta;
}
uses network-map-data;
}
grouping network-map-data {
list network-map {
key "pid";
leaf pid {
type pid-name;
}
uses endpoint-address-group;
description
"RFC7285 Sec. 11.2.1.6." +
" object-map {
PIDName -> EndpointAddrGroup;
} NetworkMapData;";
}
description
"Network map. RFC7285 Sec. 11.2.1.6." +
"object {
NetworkMapData network-map;
} InfoResourceNetworkMap : ResponseEntityBase;";
}
/* Cost Map Grouping */
grouping cost-map {
container meta {
uses cost-map-meta;
}
uses cost-map-data;
}
grouping cost-map-data {
list cost-map {
leaf src {
type pid-name;
description
"Source PID.";
}
key "src";
list dst-costs {
leaf dst {
type pid-name;
description
"Destination PID.";
}
key "dst";
uses alto-cost {
description
"Cost from source to destination.";
}
description
"The list represents the inner part of the cost matrix." +
"DstCosts. RFC7285 Sec. 11.2.3.6." +
" object-map {
PIDName -> JSONValue;
} DstCosts;";
}
description
"The list represents the outer part of the cost matrix." +
"CostMapData. RFC7285 Sec. 11.2.3.6." +
" object-map {
PIDName -> DstCosts;
} CostMapData;";
}
description
"Cost map. RFC7285 Sec. 11.2.3.6." +
" object {
CostMapData cost-map;
} InfoResourceCostMap : ResponseEntityBase;";
}
/* Endpoint Property Map Grouping */
grouping endpoint-property-map {
container meta {
uses endpoint-property-meta;
}
uses endpoint-property-map-data;
}
grouping endpoint-property-map-data {
list endpoint-properties {
key endpoint;
leaf endpoint {
type typed-endpoint-address;
mandatory true;
}
list properties {
key property-type;
leaf property-type {
type endpoint-property-type;
mandatory true;
}
leaf property {
type endpoint-property-value;
mandatory true;
}
description
"EndpointProps. RFC7285 Sec. 11.4.1.6." +
" object {
EndpointPropertyType -> JSONValue;
} EndpointProps;";
}
description
"EndpointPropertyMapData. Sec. 11.4.1.6." +
" object-map {
TypedEndpointAddr -> EndpointProps;
} EndpointPropertyMapData;";
}
description
"InfoResourceEndpointProperties. Sec. 11.4.1.6." +
" object {
EndpointPropertyMapData endpoint-properties;
} InfoResourceEndpointProperties : ResponseEntityBase;";
}
/************************************
* RPCs *
************************************/
rpc IRD-service {
output {
container IRD-service {
uses IRD;
}
}
}
rpc network-map-service {
input {
leaf uri {
type inet:uri;
mandatory true;
description
"The uri of the request for the full network map.";
}
}
output {
container network-map-service {
uses network-map;
}
}
}
rpc cost-map-service {
input {
leaf uri {
type inet:uri;
mandatory true;
description
"The uri of the request for the full network map.";
}
}
output {
container cost-map-service {
uses cost-map;
}
}
}
rpc filtered-network-map-service {
description
"inquiries on filtered network map" +
"ReqFilteredNetworkMap. RFC7285 Sec. 11.3.1.3." +
" object {
PIDName pids<0..*>;
[AddressType address-types<0..*>;]
} ReqFilteredNetworkMap;";
input {
leaf-list pids {
must "current()";
type pid-name;
}
leaf-list address-types {
type endpoint-address-type;
}
}
output {
container filtered-network-map-service {
uses network-map;
}
}
}
rpc filtered-cost-map-service {
input {
container cost-type {
must "current()";
uses cost-type;
}
leaf-list constraints {
type constraint;
description
"RFC7285 Sec. 11.3.2.3.";
}
container pids {
leaf-list srcs {
type pid-name;
description
"Source endpoint addresses.";
}
leaf-list dsts {
type pid-name;
description
"Destination endpoint addresses.";
}
description
"PIDFilter: Endpoint addresses. RFC7285 Sec. 11.3.2.3." +
" object {
PIDName srcs<0..*>;
PIDName dsts<0..*>;
} PIDFilter;";
}
}
output {
container filtered-cost-map-service {
uses cost-map;
}
}
}
rpc endpoint-property-service {
description
"inquiries on properties of an endpoint" +
" object {
EndpointPropertyType properties<1..*>;
TypedEndpointAddr endpoints<1..*>;
} ReqEndpointProp;";
input {
leaf-list properties {
type endpoint-property-type;
min-elements 1;
}
leaf-list endpoints {
type typed-endpoint-address;
min-elements 1;
}
}
output {
container endpoint-property-service {
uses endpoint-property-map;
}
}
}
rpc endpoint-cost-service {
description
"ReqEndpointCostMap. RFC7285 Sec. 11.5.1.3." +
" object {
CostType cost-type;
[JSONString constraints<0..*>;]
EndpointFilter endpoints;
} ReqEndpointCostMap;";
input {
container cost-type {
must "current()";
uses cost-type;
}
leaf-list constraints {
type constraint;
description
"RFC7285 Sec. 11.5.1.3.";
}
container endpoints {
must "current()";
leaf-list srcs {
type typed-endpoint-address;
description
"Source endpoint addresses.";
}
leaf-list dsts {
type typed-endpoint-address;
description
"Destination endpoint addresses.";
}
description
" EndpointFilter: Endpoint addr. RFC7285 Sec. 11.5.1.3." +
" object {
[TypedEndpointAddr srcs<0..*>;]
[TypedEndpointAddr dsts<0..*>;]
} EndpointFilter;";
}
}
output {
container endpoint-cost-service {
container meta {
container cost-type {
uses cost-type;
}
}
list endpoint-cost-map {
leaf src {
type typed-endpoint-address;
description
"Source endpoint address.";
}
key "src";
list dst-costs {
leaf dst {
type typed-endpoint-address;
description
"Destination endpoint address.";
}
key "dst";
uses alto-cost {
description
"Cost from source to destination.";
}
description
"The list represents the inner part of the cost matrix." +
"EndpointDstCosts. RFC7285 Sec. 11.5.1.6." +
" object-map {
TypedEndpointAddr -> JSONValue;
} EndpointDstCosts;";
}
description
"The list represents the outer part of the cost matrix." +
"EndpointCostMapData. RFC7285 Sec. 11.5.1.6." +
" object {
EndpointCostMapData endpoint-cost-map;
} InfoResourceEndpointCostMap : ResponseEntityBase;
object-map {
TypedEndpointAddr -> EndpointDstCosts;
} EndpointCostMapData;";
}
}
}
}
}
]]> endpoint-prefix<0..*>;
} EndpointAddrGroup;
There are two challenges:
1) To specify that AddressType is key, we must use the list type,
which is the only type that one can specify key. However, the
current JSON-YANG encoding generates an array, instead of a
key-value map;
2) Ideally, we want to enforce address type and prefix
consistency; for example, an ipv6 prefix in an ipv4 type should
not be allowed. However, we encounter problems. We leave this as
an OPEN ISSUE.
*/
typedef endpoint-address-type {
type union {
type enumeration {
enum ipv4;
enum ipv6;
// EXTENSION: ADD NEW TYPE HERE
}
}
description
"Ref: RFC7285 Sec 2.2.";
}
typedef endpoint-prefix {
type inet:ip-prefix;
description
"endpoint prefix, identical to ip-prefix defined in RFC6991.";
}
grouping endpoint-address-group {
list endpoint-address-group {
key address-type;
leaf address-type {
type endpoint-address-type;
mandatory true;
}
leaf-list endpoint-prefix {
type endpoint-prefix;
}
}
description
"EndpointAddrGroup. RFC7285 Sec. 10.4.5." +
" object-map {
AddressType -> endpoint-prefix<0..*>;
} EndpointAddrGroup;";
}
/**************************************************************
* Definitions for IDs and names
*
* ALTO defines the following concepts that are names and IDs:
*
* pid name (used in network map, cost map),
* resource IDs (used to identify alto network/cost maps),
* version tag (used to indicate uniqueness of resource),
* cost-type-name (used in IRD),
* cost-metric,
* cost-mode
*
* We group their definitions together below.
**************************************************************/
typedef valid-id-string {
type string {
length "1..64";
pattern "[0-9a-zA-Z_\-:@\.]+";
}
description
"Type for valid ID strings.";
}
typedef pid-name {
type valid-id-string;
description
"Name for the PID." +
"RFC7285, Section 10.1. Note: the '.' separator MUST NOT be" +
"used unless specifically indicated in RFC7285 or an" +
" extension document.";
}
typedef resource-id {
type valid-id-string;
description
"Resource-ID.";
}
grouping vtag {
leaf resource-id {
type resource-id;
mandatory true;
}
leaf tag {
type string {
length "1..64";
pattern "[!-~]+";
}
mandatory true;
description
"Tag. RFC7285 Sec. 10.3. U+0021-U+007E";
}
description
"Version tag. Both resource-id and tag must be equal
byte-for-byte. RFC7285 Sec. 10.3." +
" object {
ResourceID resource-id;
JSONString tag;
} VersionTag;";
}
grouping dependent-vtags {
list dependent-vtags {
uses vtag;
min-elements 1;
}
}
/*************************************
Definitions for cost type and cost types
In ALTO, a cost type consists of two required components:
cost-metric,
cost-mode
and an optional description component.
In the IRD, one can name each cost type. Such info is collected
in a hash map called cost types.
*************************************/
typedef cost-metric {
type union {
type enumeration {
enum routingcost {
description
"Default metric. MUST support. RFC7285 Sec. 6.1.1.1.";
}
enum hopcount {
description
"Hopcount metric.";
}
// EXTENSION: Additional cost-metric will be defined here.
}
type string {
length 1..32;
pattern "priv:[0-9a-zA-Z_\-:\.]+";
}
}
description
"Cost metric. for type string,
'priv:' reserved for Private Use.";
}
typedef cost-mode {
type enumeration {
enum numerical {
description
"Numerical cost mode.";
}
enum ordinal {
description
"Ordinal cost mode.";
}
// EXTENSION: Additional cost-mode will be defined here.
}
description
"Cost mode. MUST support at least one of numerical and ordinal";
}
grouping cost-type {
leaf cost-mode {
type cost-mode;
mandatory true;
description
"Cost mode.";
}
leaf cost-metric {
type cost-metric;
mandatory true;
description
"Cost metric.";
}
leaf description {
type string;
description
"Optional description field.";
}
description
"Cost type. RFC7285 Sec. 10.7." +
" object {
CostMetric cost-metric;
CostMode cost-mode;
[JSONString description;]
} CostType;";
}
typedef cost-type-name {
type valid-id-string;
// NOTE: not fully specified in RFC7285, default as valid id
}
grouping cost-types {
list cost-types {
key cost-type-name;
leaf cost-type-name {
type cost-type-name;
}
uses cost-type;
}
description
"RFC 7285 Sec. 9.2.2." +
"object-map {
JSONString -> CostType;
} IRDMetaCostTypes;";
}
/**************************************
* Definitions for endpoint properties *
**************************************/
typedef global-endpoint-property {
type union {
type enumeration {
enum pid {
description "PID property.";
}
// EXTENSION: other options here
}
type string {
pattern "priv:[\w\-:@]+";
}
}
description
"Global endpoint property. RFC7285 Sec. 10.8.2." +
"'priv:' for Private Use " +
" length 1..32; ‘.’ is not allowed";
}
/*
* Ideally we would want to extend the typedef of resource-id and
* global endpoint properties, however, YANG 1.0 does not allow
* that, hence we simply copied the regex for resource-id over
* verbatim.
*/
typedef resource-specific-endpoint-property {
type string {
length "3..97"; //len(resource-id) + 1 + len(global-property)
pattern "(priv:)?[\w\-:@\.]+\.[\w\-:_]+"; // resource-id.property
}
description
"Resource-specific endpoint property.";
}
typedef endpoint-property-type {
type union {
type resource-specific-endpoint-property;
type global-endpoint-property;
}
description
"Endpoint property type. RFC7285 Sec. 10.8.";
}
typedef endpoint-property-value {
type string;
description
"Endpoint property (value).";
}
/*************************************
* Definitions for response header
*************************************/
typedef media-type {
type union {
type string {
pattern "application/alto\-.*";
}
type enumeration {
enum alto-directory+json;
enum alto-networkmap+json;
enum alto-networkmapfilter+json;
enum alto-costmap+json;
enum alto-costmapfilter+json;
enum alto-endpointprop+json;
enum alto-endpointpropparams+json;
enum alto-endpointcost+json;
enum alto-endpointcostparams+json;
enum alto-error+json;
}
}
}
grouping alto-cost {
anyxml cost {
mandatory true;
description
"ALTO cost is a JSONValue, which could be
an object, array, string, etc. (Ref: RFC 7159 Sec.3.)";
}
}
typedef constraint {
type string {
pattern "(gt|ge|lt|le|eq) [0-9]+";
}
description
"RFC7285 Sec. 11.3.2.3. The second part must be in the" +
"same unit as cost-metric, IEEE 754 2008 floating point.";
}
/******************************************
Groupings for ALTO information resource
*******************************************/
/* meta */
grouping IRD-meta {
uses cost-types;
leaf default-alto-network-map {
type leafref {
path "/resources/IRD/resources/resource-id";
}
mandatory true;
}
}
grouping network-map-meta {
container vtag {
uses vtag;
}
}
grouping cost-map-meta {
uses dependent-vtags {
refine dependent-vtags {
max-elements 1;
}
}
container cost-type {
uses cost-type;
}
}
grouping endpoint-property-meta {
uses dependent-vtags;
}
/* accepts (optional) */
grouping accepts {
leaf-list accepts {
type media-type;
min-elements 1;
}
}
/* capabilities (capabilities) */
grouping IRD-capabilities {
container capabilities {
leaf cost-constraints {
type boolean;
}
leaf-list cost-type-names {
type cost-type-name;
}
leaf-list prop-types {
type endpoint-property-type;
}
}
}
/* uses (optional) */
grouping uses {
leaf-list uses {
type leafref {
path "/resources/IRD/resources/resource-id";
}
min-elements 1;
}
}
/* Information Resource Directory Grouping */
grouping IRD {
container meta {
uses IRD-meta;
}
uses IRD-data;
}
grouping IRD-data {
list resources {
key resource-id;
leaf resource-id {
type resource-id;
mandatory true;
}
leaf uri {
type inet:uri;
mandatory true;
}
leaf media-type {
type media-type;
mandatory true;
}
uses accepts {
when "current()";
}
uses IRD-capabilities {
when "current()";
}
uses uses {
when "current()";
}
description
"IRDResourceEntry. RFC7285 9.2.2." +
" object {
JSONString uri;
JSONString media-type;
[JSONString accepts;]
[Capabilities capabilities;]
[ResourceID uses<0..*>;]
} IRDResourceEntry;" +
"IRDResourceEntries. RFC7285 9.2.2." +
" object-map {
ResourceID -> IRDResourceEntry;
} IRDResourceEntries;" +
"InformationResourceDirectory. RFC7285 9.2.2." +
" object {
IRDResourceEntries resources;
} InfoResourceDirectory : ResponseEntityBase;";
}
}
/* Network Map Grouping */
grouping network-map {
container meta {
uses network-map-meta;
}
uses network-map-data;
}
grouping network-map-data {
list network-map {
key "pid";
leaf pid {
type pid-name;
}
uses endpoint-address-group;
description
"RFC7285 Sec. 11.2.1.6." +
" object-map {
PIDName -> EndpointAddrGroup;
} NetworkMapData;";
}
description
"Network map. RFC7285 Sec. 11.2.1.6." +
"object {
NetworkMapData network-map;
} InfoResourceNetworkMap : ResponseEntityBase;";
}
/* Cost Map Grouping */
grouping cost-map {
container meta {
uses cost-map-meta;
}
uses cost-map-data;
}
grouping cost-map-data {
list cost-map {
leaf src {
type pid-name;
description
"Source PID.";
}
key "src";
list dst-costs {
leaf dst {
type pid-name;
description
"Destination PID.";
}
key "dst";
uses alto-cost {
description
"Cost from source to destination.";
}
description
"The list represents the inner part of the cost matrix." +
"DstCosts. RFC7285 Sec. 11.2.3.6." +
" object-map {
PIDName -> JSONValue;
} DstCosts;";
}
description
"The list represents the outer part of the cost matrix." +
"CostMapData. RFC7285 Sec. 11.2.3.6." +
" object-map {
PIDName -> DstCosts;
} CostMapData;";
}
description
"Cost map. RFC7285 Sec. 11.2.3.6." +
" object {
CostMapData cost-map;
} InfoResourceCostMap : ResponseEntityBase;";
}
/* Endpoint Property Map Grouping */
grouping endpoint-property-map {
container meta {
uses endpoint-property-meta;
}
uses endpoint-property-map-data;
}
grouping endpoint-property-map-data {
list endpoint-properties {
key endpoint;
leaf endpoint {
type typed-endpoint-address;
mandatory true;
}
list properties {
key property-type;
leaf property-type {
type endpoint-property-type;
mandatory true;
}
leaf property {
type endpoint-property-value;
mandatory true;
}
description
"EndpointProps. RFC7285 Sec. 11.4.1.6." +
" object {
EndpointPropertyType -> JSONValue;
} EndpointProps;";
}
description
"EndpointPropertyMapData. Sec. 11.4.1.6." +
" object-map {
TypedEndpointAddr -> EndpointProps;
} EndpointPropertyMapData;";
}
description
"InfoResourceEndpointProperties. Sec. 11.4.1.6." +
" object {
EndpointPropertyMapData endpoint-properties;
} InfoResourceEndpointProperties : ResponseEntityBase;";
}
/****************************************************
DATA INSTANCES of all ALTO information resources
unfiltered network-maps, unfiltered cost-maps are all instances
of resources. IRD is also modeled as data.
The design uses augment as the basic approach to implement
inheritance.
****************************************************/
container resources {
config false;
/* Information Resource Directory */
container IRD {
uses IRD;
}
list network-maps {
unique "meta/vtag/resource-id meta/vtag/tag";
uses network-map;
}
list cost-maps {
/*
The dependent-vtags and cost-types in the meta uniquely
identify a cost map. However, the unique statement in YANG
does not allow reference to a list (dependent-vtags).
*/
uses cost-map;
}
container endpoint-property-map {
uses endpoint-property-map;
}
}
/************************************
* RPCs *
************************************/
rpc IRD-service {
output {
container IRD-service {
uses IRD;
}
}
}
rpc network-map-service {
input {
leaf uri {
type leafref {
path "/resources/IRD/resources/uri";
}
mandatory true;
description
"The uri of the request for the full network map.";
}
}
output {
container network-map-service {
uses network-map;
}
}
}
rpc cost-map-service {
input {
leaf uri {
type leafref {
path "/resources/IRD/resources/uri";
}
mandatory true;
description
"The uri of the request for the full network map.";
}
}
output {
container cost-map-service {
uses cost-map;
}
}
}
rpc filtered-network-map-service {
description
"inquiries on filtered network map" +
"ReqFilteredNetworkMap. RFC7285 Sec. 11.3.1.3." +
" object {
PIDName pids<0..*>;
[AddressType address-types<0..*>;]
} ReqFilteredNetworkMap;";
input {
leaf-list pids {
must "current()";
type pid-name;
}
leaf-list address-types {
type endpoint-address-type;
}
}
output {
container filtered-network-map-service {
uses network-map;
}
}
}
rpc filtered-cost-map-service {
input {
container cost-type {
must "current()";
uses cost-type;
}
leaf-list constraints {
type constraint;
description
"RFC7285 Sec. 11.3.2.3.";
}
container pids {
leaf-list srcs {
type pid-name;
description
"Source endpoint addresses.";
}
leaf-list dsts {
type pid-name;
description
"Destination endpoint addresses.";
}
description
"PIDFilter: Endpoint addresses. RFC7285 Sec. 11.3.2.3." +
" object {
PIDName srcs<0..*>;
PIDName dsts<0..*>;
} PIDFilter;";
}
}
output {
container filtered-cost-map-service {
uses cost-map;
}
}
}
rpc endpoint-property-service {
description
"inquiries on properties of an endpoint" +
" object {
EndpointPropertyType properties<1..*>;
TypedEndpointAddr endpoints<1..*>;
} ReqEndpointProp;";
input {
leaf-list properties {
type endpoint-property-type;
min-elements 1;
}
leaf-list endpoints {
type typed-endpoint-address;
min-elements 1;
}
}
output {
container endpoint-property-service {
uses endpoint-property-map;
}
}
}
rpc endpoint-cost-service {
description
"ReqEndpointCostMap. RFC7285 Sec. 11.5.1.3." +
" object {
CostType cost-type;
[JSONString constraints<0..*>;]
EndpointFilter endpoints;
} ReqEndpointCostMap;";
input {
container cost-type {
must "current()";
uses cost-type;
}
leaf-list constraints {
type constraint;
description
"RFC7285 Sec. 11.5.1.3.";
}
container endpoints {
must "current()";
leaf-list srcs {
type typed-endpoint-address;
description
"Source endpoint addresses.";
}
leaf-list dsts {
type typed-endpoint-address;
description
"Destination endpoint addresses.";
}
description
" EndpointFilter: Endpoint addr. RFC7285 Sec. 11.5.1.3." +
" object {
[TypedEndpointAddr srcs<0..*>;]
[TypedEndpointAddr dsts<0..*>;]
} EndpointFilter;";
}
}
output {
container endpoint-cost-service {
container meta {
container cost-type {
uses cost-type;
}
}
list endpoint-cost-map {
leaf src {
type typed-endpoint-address;
description
"Source endpoint address.";
}
key "src";
list dst-costs {
leaf dst {
type typed-endpoint-address;
description
"Destination endpoint address.";
}
key "dst";
uses alto-cost {
description
"Cost from source to destination.";
}
description
"The list represents the inner part of the cost matrix." +
"EndpointDstCosts. RFC7285 Sec. 11.5.1.6." +
" object-map {
TypedEndpointAddr -> JSONValue;
} EndpointDstCosts;";
}
description
"The list represents the outer part of the cost matrix." +
"EndpointCostMapData. RFC7285 Sec. 11.5.1.6." +
" object {
EndpointCostMapData endpoint-cost-map;
} InfoResourceEndpointCostMap : ResponseEntityBase;
object-map {
TypedEndpointAddr -> EndpointDstCosts;
} EndpointCostMapData;";
}
}
}
}
}
]]>
We established that the YANG validated messages cannot be syntactically equivalent to the
ALTO protocol messages. For a selection of the examples in the ALTO protocol, we provide
the YANG validated version of the message for comparison purposes.
The ALTO example of IRD response as specified in Section 9.2.3 of .
The corresponding XML file which is validated by YANG.
num-routingnumericalroutingcostMy defaultnum-hopnumericalhopcountord-routingordinalroutingcostord-hopordinalhopcount
my-default-network-map
my-default-network-maphttp://alto.example.com/networkmapapplication/alto-networkmap+jsonnumerical-routing-cost-maphttp://alto.example.com/costmap/num/routingcostapplication/alto-costmap+jsonnum-routingmy-default-network-mapnumerical-hopcount-cost-maphttp://alto.example.com/costmap/num/hopcountapplication/alto-costmap+jsonnum-hopmy-default-network-mapcustom-maps-resourceshttp://custom.alto.example.com/mapsapplication/alto-directory+jsonendpoint-propertyhttp://alto.example.com/endpointprop/lookupapplication/alto-endpointprop+jsonapplication/alto-endpointpropparams+jsonmy-default-network-map.pidpriv:ietf-example-propendpoint-costhttp://alto.example.com/endpointcost/lookupapplication/alto-endpointcost+jsonapplication/alto-endpointcostparams+jsontruenum-routingnum-hopord-routingord-hop
]]>
The ALTO example of a network map response as specified in Section 11.2.1.7 of .
The corresponding YANG-validated XML file:
my-default-network-mapda65eca2eb7a10ce8b059740b0b2e3f8eb1d4785PID1ipv4192.0.2.0/24198.51.100.0/25PID2ipv4198.51.100.128/25PID3ipv40.0.0.0/0ipv6::/0
]]>
The ALTO example of a filtered cost map response as specified in Section 11.3.2.7 of .
The corresponding YANG-validated XML file:
my-default-network-map75ed013b3cb58f896e839582504f622838ce670fnumericalroutingcostPID1PID10PID21PID32
]]>
The ALTO example of an endpoint property service response as specified in Section 11.4.1.7 of .
The corresponding YANG-validated XML file:
my-default-network-map7915dc0290c2705481c491a2b4ffbec482b3cf62ipv4:192.0.2.34my-default-network-map.pidPID1priv:ietf-example-prop1ipv4:203.0.113.129my-default-network-map.pidPID3
]]>