1.1.Terminology and Notation

This document uses the following terms and abbreviations that will befurther defined in the document. While this document introduces the feature"entity property map", it will use both the term "property map" and "entityproperty map" to refer to this feature.¶

Transaction:

A request/response exchange between an ALTO client and an ALTO server.¶

Client:

When used with a capital "C", this term refers to an ALTO client. Note that expressions "ALTO client", "ALTO Client", and "Client" are equivalent.¶

Server:

When used with a capital "S", this term refers to an ALTO server. Note that expressions "ALTO server", "ALTO Server", and "Server" are equivalent.¶

EPS:

An abbreviation for Endpoint Property Service.¶

This document uses the notation defined inSection 8.2 of [RFC7285].¶

3.1.Entity

The concept of an ALTO entity generalizes the concept of an ALTO endpointdefined inSection 2.1 of [RFC7285]. An entity is an object that can be anendpoint defined by its network address, but it can also be an objectthat has a defined mapping to a set of one or more network addresses or anobject that is not even related to any network address. Thus, whereas allendpoints are entities, not all entities are endpoints.¶

Examples of entities are:¶

• an ALTO endpoint that represents an application or a host identified by a communication address (e.g., an IPv4 or IPv6 address) in a network,¶
• a PID, defined in[RFC7285], that has a provider-defined, human-readable identifier specified by an ALTO network map, which maps a PID to a set of IPv4 and IPv6 addresses,¶
• an Autonomous System (AS) that has an AS number (ASN) as its identifier and maps to a set of IPv4 and IPv6 addresses, which is defined in[RFC9241],¶
• a country with a code specified in[ISO3166-1] to which applications such as content delivery network (CDN) providers associate properties and capabilities, which is defined in[RFC9241],¶
• a TCP or UDP network flow that is identified by a 5-tuple specifying its source and destination addresses and port numbers, and the IP protocol (TCP or UDP),¶
• a routing element, as specified in[RFC7921], that is associated withrouting capabilities information, or¶
• an Abstract Network Element, as specified in[PATH-VECTOR], that represents an abstraction of a network part such as a router, one or more links, a network domain, or their aggregation.¶

Some of the example entities listed above have already been documented as ALTO entities. The other examples are provided for illustration as potential entities.¶

3.2.Entity Domain

An entity domain defines a set of entities of the same semantic type. Anentity domain is characterized by a type and identified by a name.¶

In this document, an entity is owned by exactly one entity domain name.An entity identifier points to exactly one entity. If two entities in twodifferent entity domains refer to the same physical or logical object, theyare treated as different entities. For example, if an end host has both an IPv4and an IPv6 address, these two addresses will be treated as two entities,defined respectively in the "ipv4" and "ipv6" entity domains.¶

3.3.Entity Property Type

An entity property defines a property of an entity. This is similar to theendpoint property defined inSection 7.1 of [RFC7285]. An entity propertycan convey either network-aware or network-agnostic information. Similar toan entity domain, an entity property is characterized by a type andidentified by a name. An entity property typeMUST be registered with IANA, as specified inSection 12.4.¶

Below are listed some examples with real and fictitious entity domain and propertynames:¶

• an entity in the "ipv4" domain type may have a property whose value is anAutonomous System (AS) number indicating the AS to which this IPv4 addressbelongs and another property named "countrycode" indicating a country code mappingto this address,¶
• an entity identified by its country code in the entity domain type"countrycode", defined in[RFC9241], mayhave a property indicating what delivery protocol is used by a CDN, or¶
• an entity in the "netmap1.pid" domain may have a property that indicatesthe central geographical location of the endpoints it includes.¶

It should be noted that some identifiers may be used for both an entitydomain type and a property type. For example:¶

• the identifier "countrycode" may point to both the entity domain type"countrycode" and the fictitious property type "countrycode".¶
• the identifier "pid" may point to both the entity domain type "pid" and theproperty type "pid".¶

Likewise, the same identifier may point to both a domain name and a propertyname. For example: the identifier "netmap10.pid" may point to either thedomain defined by the PIDs of network map "netmap10" or to a property thatreturns, for an entity defined by its IPv4 address, the PID of "netmap10" thatcontains this entity. Such cases are further explained inSection 4.¶

3.4.New Information Resource and Media Type: ALTO Property Map

This document introduces a new ALTO information resource named property map.An ALTO property map provides a set of properties for one or more sets ofentities. A property may apply to different entity domain types and names.For example, an ALTO property map may define the "ASN" property for both"ipv4" and "ipv6" entity domains.¶

The present extension also introduces a new media type.¶

This document uses the same definition of an information resource asSection 9.1 of [RFC7285]. ALTO uses media types to uniquely indicate the dataformat used to encode the content to be transmitted between an ALTO serverand an ALTO client in the HTTP entity body. In the present case, an ALTOproperty map resource isdefined by the media type "application/alto-propmap+json".¶

A property map can be queried as a GET-mode resource, thus conveying allproperties for all entities indicated in its capabilities. It can also bequeried as a POST-mode resource, thus conveying a selection of properties for a selection of entities.¶

4.1.Entity Identifier and Entity Domain Name

In[RFC7285], an endpoint has an identifier that is explicitly associatedwith the "ipv4" or "ipv6" address domain. Examples are "ipv4:192.0.2.14" and"ipv6:2001:db8::12".¶

In this document, example IPv4 and IPv6 addresses and prefixes are taken from the address ranges reserved for documentation by[RFC5737] and[RFC3849].¶

In this document, an entity must be owned by exactly one entity domain name, and an entity identifier must point to exactly one entity. To ensure this, an entity identifier is explicitly attached to the name of its entity domain, and an entity domain type characterizes the semantics and identifier format of its entities.¶

The encoding format of an entity identifier is further specified inSection 5.1.3 of this document.¶

For instance:¶

• if an entity is an endpoint with IPv4 address"192.0.2.14", its identifier is associated with entity domain name "ipv4" and is"ipv4:192.0.2.14";¶
• if an entity is a PID named "mypid10" in network map resource "netmap2",its identifier is associated with entity domain name "netmap2.pid" and is"netmap2.pid:mypid10".¶

4.2.Resource-Specific Entity Domain Name

Some entities are defined and identified uniquely and globally in the context of an ALTO server. This is thecase, for instance, when entities are endpoints that are identified by areachable IPv4 or IPv6 address. The entity domain for such entities can beglobally defined and named "ipv4" or "ipv6". Those entity domains are calledresource-agnostic entity domains in this document, as they are not associatedwith any specific ALTO information resources.¶

Some other entities and entity types are only defined relative to a giveninformation resource. This is the case for entities of domain type "pid",which can only be understood with respect to the network map where they aredefined. For example, a PID named "mypid10" may be defined to represent a setS1 of IP addresses in a network map resource named "netmap1". Another networkmap "netmap2" may use the same name "mypid10" and define it to representanother set S2 of IP addresses. The identifier "pid:mypid10" may thus pointto different objects because the information on the originating informationresource is lost.¶

To solve this ambiguity, the present extension introduces the concept ofresource-specific entity domain. This concept applies to domain types whereentities are defined relative to a given information resource. It can alsoapply to entity domains that are defined locally, such as local networks ofobjects identified with a local IPv4 address.¶

In such cases, an entity domain type is explicitly associated with anidentifier of the information resource where these entities are defined. Suchan information resource is referred to as the "specific informationresource". Using a resource-aware entity domain name, an ALTO property mapcan unambiguously identify distinct entity domains of the same type, on whichentity properties may be queried. Examples of resource-specific entity domainnames may look like "netmap1.pid" or "netmap2.pid". Thus, a name associationsuch as "netmap1.pid:mypid10" and "netmap2.pid:mypid10" distinguishesthe two abovementioned PIDs that are both named "mypid10" but in twodifferent resources, "netmap1" and "netmap2".¶

An information resource is defined in the scope of an ALTO Server and so isan entity domain name. The format of a resource-specific entity domain nameis further specified inSection 5.1.2.¶

4.3.Resource-Specific Entity Property Value

Like entity domains, some types of properties are defined relative to aninformation resource. That is, an entity may have a property of a given typewhose values are associated with different information resources.¶

For example, suppose entity "192.0.2.34" defined in the "ipv4" domain has aproperty of type "pid" whose value is the PID to which address "192.0.2.34"is attached in a network map. The mapping of network addresses to PIDs isspecific to a network map and probably different from one network mapresource to another one. Thus, if a property "pid" is defined for entity"192.0.2.34" in two different network maps "netmap1" and "netmap2", the valuefor this property can be a different value in "netmap1" and"netmap2".¶

To support information-resource-dependent property values, this document usesthe same approach as in Section10.8.1 ( "Resource-Specific Endpoint Properties") of[RFC7285]. When a property value depends on agiven information resource, the name of this propertyMUST be explicitlyassociated with the information resource that defines it.¶

For example, the property "pid" queried on entity "ipv4:192.0.2.34" anddefined in both "netmap1" and "netmap2" can be named "netmap1.pid" and"netmap2.pid". This allows a Client to get a property of the same type butdefined in different information resources with a single query.Specifications for the property name format are provided inSection 5.2.¶

4.4.Entity Hierarchy and Property Inheritance

For some domain types, there is an underlying structure that allows entities to be efficiently grouped into a set and be defined by the identifier of this set. This is the case for domain types "ipv4" and "ipv6", where individual Internet addresses can be grouped in blocks. When the same property value applies to a whole set, a Server can define a property for the identifier of this set instead of enumerating all the entities and their properties. This allows a substantial reduction of transmission payload both for the Server and the Client. For example, all the entities included in the set defined by the address block "ipv6:2001:db8::1/64" share the same properties and values defined for this block.¶

Additionally, entity sets sometimes are related by inclusion, hierarchy, or other relations. This allows defining inheritance rules for entity properties that propagate properties among related entity sets. The Server and the Client can use these inheritance rules for further payload savings. Entity hierarchy and property inheritance rules are specified in the documents that define the applicable domain types. The present document defines these rules for the "ipv4" and "ipv6" domain types.¶

For applicable domain types, this document introduces entity property inheritance rules with the following concepts: entity hierarchy, property inheritance, and property value unicity. A detailed specification of entity hierarchy and property inheritance rules is provided inSection 5.1.4.¶

4.5.Supported Properties for Entity Domains in Property Map Capabilities

A property type is not necessarily applicable to any domain type, or an ALTO Server may choose not to provide a property for all applicable domains. For instance, a property type reflecting link bandwidth is likely not defined for entities of a domain of type "countrycode". Therefore, an ALTO server providing property maps needs to specify the properties that can be queried on the different entity domains it supports.¶

This document explains how the Information Resource Directory (IRD) capabilities of a property map resource unambiguously expose which properties a Client can query on a given entity domain:¶

• a field named "mappings" lists the names of the entity domains supported by the property map, and¶
• for each listed entity domain, a list of the names of the applicable properties is provided.¶

An example is provided inSection 10.3. The "mappings" field associates entity domains and properties that can be resource-agnostic or resource-specific. This allows a Client to formulate compact and unambiguous entity property queries, possibly relating to one or more information resources. In particular:¶

• it prevents a Client from querying a property for entity domains for which it is not defined;¶
• it allows a Client to query, for an entity E, values for a property P that are defined in several information resources; and¶
• it allows a Client to query a property P on entities that are defined in several information resources.¶

Further details are provided inSection 7.4.¶

4.6.Defining Information Resource for Resource-Specific Entity Domains

A Client willing to query entity properties belonging to a domain needsto know how to retrieve these entities. To this end, the Client can look upthe "mappings" field exposed in IRD capabilities of a property map; seeSection 4.5.This field, in its keys, exposes all the entity domains supported by theproperty map. The syntax of the entity domain identifier specified inSection 5.1.2 allows the client to infer whether the entity domain isresource-specific or not. The Client can extract, if applicable, theidentifier of the specific resource, query the resource, and retrieve the entities. For example:¶

• an entity domain named "netmap1.ipv4" includes the IPv4 addresses thatappear in the "ipv4" field of the endpoint address group of each PID in thenetwork map "netmap1" and that have no meaning outside "netmap1"because, for instance, these are local addresses not reachable outside some private network;¶
• an entity domain named "netmap1.pid" includes the PIDs listed in networkmap "netmap1"; and¶
• an entity domain named "ipv4" is resource-agnostic and covers all thereachable IPv4 addresses.¶

Besides, it is not possible to prevent a Server from mistakenly exposing inappropriate associations of information resources and entity domain types. To prevent failures due to invalid queries, it is necessary to inform the Client which associations are allowed. An informed Client will just ignore inappropriate associations exposed by a Server and avoid error-prone transactions with the Server.¶

For example, the association "costmap3.pid" is not allowed for the followingreason: although a cost map exposes PID identifiers, it does not define theset of addresses included in this PID. Neither does a cost map list all thePIDs on which properties can be queried because a cost map only exposes PIDpairs on which a queried cost type is defined. Therefore, the resource"costmap3" does not enable a Client to extract information on the existingPID entities or on the addresses they contain.¶

Instead, the cost map uses a network map where all the PIDs used in a costmap are defined together with the addresses contained by the PIDs. Thisnetwork map is qualified in this document as the defining informationresource for the entity domain of type "pid", and this concept is explained inSection 4.6.1.¶

4.7.Defining Information Resources for Resource-Specific Property Values

As explained inSection 4.3, a property type maytake values that are resource-specific. This is the case for property type"pid", whose values are by essence defined relative to a specific networkmap. That is, the PID value returned for an IPv4 address is specific to the networkmap defining this PID and may differ from one network map to another one.¶

Another example is provided in[RFC9241],which defines property type "cdni-capabilities". The value of this property isspecific to a Content Delivery Network Interconnection (CDNI) Advertisement resource, which provides a list of CDNIcapabilities. The property is provided for entity domain types "ipv4","ipv6", "asn", and "countrycode". However, a CDNI Advertisement resource does not define PID values for IPv4 addresses, while a network map does not defineCDNI capabilities for IPv4 addresses.¶

Similar to resource-specific entity domains, the Client needs to becognizant of appropriate associations of information resource and propertytypes. Therefore, when specifying and registering a property type whosevalues are resource-specific, the media type of its defining informationresource needs to be specified. For example:¶

• The media type of the defining information resource for property type "pid"is "application/alto-networkmap+json".¶
• The media type of the defining information resource for property type"cdni-capabilities" defined in[RFC9241]is "application/alto-cdni+json".¶

5.1.Entity Domain

EntityDomainName ::= [ [ ResourceID ] '.' ] EntityDomainType

                "[ [ ResourceID ] '.' ]"

    EntityDomainName ::= '.' EntityDomainType

EntityID ::= EntityDomainName ':' DomainTypeSpecificEntityID

5.2.Entity Property

Each entity property has a type to indicate the encoding and the semantics ofthe value of this entity property, and has a name to identify it.¶

EntityPropertyName ::= [ [ ResourceID ] '.' ] EntityPropertyType

6.1.Internet Address Domain Types

The document defines two entity domain types (IPv4 and IPv6) for Internetaddresses. Both types are resource-agnostic entity domain types and hencedefine corresponding resource-agnostic entity domains as well. Since the twodomains use the same hierarchy and inheritance semantics, we define thesemantics together, instead of repeating for each.¶

6.2.Entity Domain Type: PID

The PID entity domain associates property values with the PIDs in a network map.Accordingly, this entity domain always depends on a network map.¶

6.3.Internet Address Properties vs. PID Properties

Because the Internet address and PID domains relate to completely distinct domain types, thequestion may arise as to which entity domain type is the best for a property. In general, theInternet address domain types areRECOMMENDED for properties that are closely relatedto the Internet address or are associated with, and inherited through, hierarchical addresses.¶

The PID domain type isRECOMMENDED for properties that arise from the definition ofthe PID, rather than from the Internet address prefixes in that PID.¶

For example, because Internet addresses are allocated to service providers byblocks of prefixes, an "ISP" property would be best associated with Internetaddress domain types. On the other hand, a property that explains why a PIDwas formed, or how it relates to a provider's network, would best beassociated with the PID domain type.¶

7.1.Media Type

The media type of a property map is "application/alto-propmap+json".¶

7.2.HTTP Method

The property map is requested using the HTTP GET method.¶

7.3.Accept Input Parameters

A property map has no Accept Input parameters.¶

7.4.Capabilities

The capabilities are defined by an object of type PropertyMapCapabilities:¶

    object {      EntityPropertyMapping mappings;    } PropertyMapCapabilities;    object-map {      EntityDomainName -> EntityPropertyName<1..*>;    } EntityPropertyMapping

with fields:¶

mappings:

A JSON object whose keys are names of entity domains and values are thesupported entity properties of the corresponding entity domains.¶

7.5.Uses

The "uses" field of a property map resource in an IRD entry specifies the resources in this same IRD on which this property map directly depends. It is an array of resource identifier(s). This array identifies the defining information resources associated with the resource-specific entity domains and properties that are indicated in this resource.¶

7.6.Response

If the entity domains in this property map depend on other resources, the"dependent-vtags" field in the "meta" field of the responseMUST be an arraythat includes the version tags of those resources, and the orderMUST beconsistent with the "uses" field of this property map resource. The datacomponent of a property map response is named "property-map", which is a JSONobject of type PropertyMapData, where:¶

    object {      PropertyMapData property-map;    } InfoResourceProperties : ResponseEntityBase;    object-map {      EntityID -> EntityProps;    } PropertyMapData;    object {      EntityPropertyName -> JSONValue;    } EntityProps;

The ResponseEntityBase type is defined inSection 8.4 of [RFC7285].¶

Specifically, a PropertyMapData object has one member for each entity in the property map. The entity's properties are encoded in the corresponding EntityProps object. EntityProps encodes one name/value pair for each property, where the property names are encoded as strings of type PropertyName. A protocol implementationSHOULD assume that the property value is either a JSONString or a JSON "null" value, and fail to parse if it is not, unless the implementation is using an extension to this document that indicates when and how property values of other data types are signaled.¶

For each entity in the property map:¶

• If the entity is in a resource-specific entity domain, the ALTO serverMUST only return self-defined properties and resource-specific properties that depend on the same resource as the entity does. The ALTO clientMUST ignore any resource-specific property for this entity if the mapping between this resource-specific property and this entity is not indicated, in the IRD, in the "mappings" capability of the property map resource.¶
• If the entity identifier is resource-agnostic, the ALTO serverSHOULD return the self-defined properties and all the resource-specific properties defined in the property-defining information resources that are indicated, in the IRD, in the "mappings" capability of the property map resource, unless property values can be omitted upon some inheritance rules.¶

The ALTO serverMAY omit property values that are inherited rather than explicitly defined in order to achieve more compact encoding. As a consequence,the ALTO ClientMUST NOT assume inherited property values will all be present. If the Client needs inherited values, itMUST use the entity domain's inheritance rules to deduce those values.¶

8.1.Media Type

The media type of a property map resource is "application/alto-propmap+json".¶

8.2.HTTP Method

The filtered property map is requested using the HTTP POST method.¶

8.3.Accept Input Parameters

The input parameters for a filtered property map request are supplied in the entity body of the POST request. This document specifies the input parameters with a data format indicated by the media type "application/alto-propmapparams+json", which is a JSON object of type ReqFilteredPropertyMap. ReqFilteredPropertyMap is designed to support the following cases of client requests:¶

• The client wants the value of a selected set of properties for a selected set of entities;¶
• The client wants all property values on all the entities;¶
• The client wants all entities for which a property is defined but is not interested in their property values; or¶
• The client wants to cross-check whether some entity identifiers are present in the filtered property map but is not interested in their property values.¶

The third case is equivalent to querying the whole unfiltered property map, which can also be achieved with a GET request. Some Clients, however, may prefer to systematically make filtered property map queries, where filtering parameters may sometimes be empty.¶

The JSON object ReqFilteredPropertyMap is specified as follows:¶

                  object {                    EntityID             entities<0..*>;                    [EntityPropertyName   properties<0..*>;]                  } ReqFilteredPropertyMap;

with fields:¶

entities:

A list of entity identifiers for which the specified properties are to be returned. If the list is empty, the ALTO ServerMUST interpret the list as if it contained a list of all entities currently defined in the filtered property map. The domain of each entityMUST be included in the list of entity domains in this resource's "capabilities" field (seeSection 8.4). The ALTO serverMUST interpret entries appearing multiple times as if they appeared only once.¶

properties:

A list of properties to be returned for each entity. If the list is empty, the ALTO SeverMUST interpret the list as if it contained a list of all properties currently defined in the filtered property map. Each specified propertyMUST be included in the list of properties in this resource's "capabilities" field (seeSection 8.4). The ALTO serverMUST interpret entries appearing multiple times as if they appeared only once. This field is optional. If it is absent, the Server returns a property value equal to the literal string "{}" for all the entity identifiers of the "entities" field for which at least one property is defined.¶

Note that the field "properties" is optional. In addition, when the "entities" field is an empty list, it corresponds to a query for all applicable entity identifiers of the filtered property map, with no current interest on any particular property. When the "entities" field is not empty, it allows the Client to check whether the listed entity identifiers can be used as input to a filtered property map query.¶

8.4.Capabilities

The capabilities are defined by an object of type PropertyMapCapabilities, as defined inSection 7.4.¶

8.5.Uses

This is the same as the "uses" field of the property map resource (seeSection 7.5).¶

8.6.Filtered Property Map Response

The responseMUST indicate an error, using ALTO Protocol error handling, as defined inSection 8.5 of [RFC7285], if the request is invalid.¶

Specifically, a filtered property map request can be invalid in the following cases:¶

• The input field "entities" is absent from the Client request. In this case, the ServerMUST return an "E_MISSING_FIELD" error as defined inSection 8.5.2 of [RFC7285].¶

• An entity identifier in the "entities" field of the request is invalid. This occurs when:¶

  • The domain of this entity is not defined in the "mappings" capability of this resource in the IRD, or¶
  • The entity identifier is not valid for the entity domain.¶

  A valid entity identifier never generates an error, even if the filtered property map resource does not define any properties for it.¶

  If an entity identifier in the "entities" field of the request is invalid, the ALTO serverMUST return an "E_INVALID_FIELD_VALUE" error defined inSection 8.5.2 of [RFC7285], and the "value" field of the error messageSHOULD indicate the provided invalid entity identifier.¶

• A property name in the "properties" field of the request is invalid. This occurs when this property name is not defined in the "properties" capability of this resource in the IRD.¶

  When a filtered property map resource does not define a value for a property requested for a particular entity, it is not an error. In this case, the ALTO serverMUST omit that property from the response for that endpoint.¶

  If a property name in the "properties" field in the request is invalid, the ALTO serverMUST return an "E_INVALID_FIELD_VALUE" error defined inSection 8.5.2 of [RFC7285]. The "value" field of the error messageSHOULD indicate the property name.¶

Some identifiers can be interpreted as both an entity name and a property name, as is the case for "pid" if it were erroneously used alone. In such a case, the ServerSHOULD followSection 8.5.2 of [RFC7285], which says:¶

For an E_INVALID_FIELD_VALUE error, the server may include an optional field named "field" in the "meta" field of the response, to indicate the field that contains the wrong value.¶

The response to a valid request is the same as for the property map (seeSection 7.6) except that:¶

• If the requested entities include entities with a resource-agnostic identifier, the "dependent-vtags" field in its "meta" fieldMUST include version tags of all dependent resources appearing in the "uses" field.¶
• If the requested entities only include entities in resource-specific entity domains, the "dependent-vtags" field in its "meta" fieldMUST include the version tags of the resources on which the requested resource-specific entity domains and the requested resource-specific properties are dependent.¶
• The response only includes the entities and properties requested by the client. If an entity in the request is identified by a hierarchical identifier (e.g., a "ipv4" or "ipv6" prefix), the responseMUST return all properties that are present for any address covered by the prefix, even though some of those properties may not be present for all addresses covered by the prefix.¶
• When the input member "properties" is absent from the client request, the Server returns a property map containing all the requested entity identifiers for which one or more properties are defined. For all the entities of the returned map, the returned property value is equal to "{}".¶

The filtered property map responseMUST include all the inherited property values for the requested entities and all the entities that are able to inherit property values from the requested entities. To achieve this goal, the ALTO serverMAY follow two rules:¶

• If a property for a requested entity is inherited from another entity not included in the request, the responseMUST include this property for the requested entity. For example, a full property map may skip a property P for an entity A (e.g., "ipv4:192.0.2.0/31") if P can be derived using inheritance from another entity B (e.g., "ipv4:192.0.2.0/30"). A filtered property map request may include only A but not B. In such a case, the property PMUST be included in the response for A.¶
• If there are entities covered by a requested entity but they have different values for the requested properties, the responseMUST include all those entities and the different property values for them. For example, consider a request for property P of entity A (e.g., "ipv4:192.0.2.0/31"): if P has value v1 for "A1=ipv4:192.0.2.0/32" and v2 for "A2=ipv4:192.0.2.1/32", then the responseSHOULD include A1 and A2.¶

For the sake of response compactness, the ALTO serverSHOULD obey the following rule:¶

• If an entity identifier in the response is already covered by other entities identifiers in the same response, itSHOULD be removed from the response. In the previous example, the entity "A=ipv4:192.0.2.0/31"SHOULD be removed because A1 and A2 cover all the addresses in A.¶

An ALTO client should be aware that the entities in the response may be different from the entities in its request.¶

8.7.Entity Property Type Defined in This Document

This document defines the entity property type "pid". This property typeextends the ALTO endpoint property type "pid" defined inSection 7.1.1 of [RFC7285] as follows: the property has the same semantics and applies toIPv4 and IPv6 addresses; the difference is that the IPv4 and IPv6 addresseshave evolved from the status of endpoints to the status of entities.¶

The defining information resource for property typeMUST be a network map.¶

9.1.Impact on Endpoint Property Service

Since the property map and the filtered property map defined in this documentprovide a functionality that covers the EPSdefined inSection 11.4 of [RFC7285], ALTO servers may prefer to provideproperty map and filtered property map in place of EPS. However, for thelegacy endpoint properties, it is recommended that ALTO servers also provideEPS so that legacy clients can still be supported.¶

9.2.Impact on Resource-Specific Properties

Section 10.8 of [RFC7285] defines two categories of endpoint properties: "resource-specific" and "global". Resource-specific property names areprefixed with the identifier of the resource they depend on, while global propertynames have no such prefix. The property map and the filtered property mapspecified in this document define similar categories of entity properties. Thedifference is that entity property maps do not define "global" entityproperties. Instead, they define self-defined entity properties as aspecial case of "resource-specific" entity properties, where the specificresource is the property map itself. This means that self-definedproperties are defined within the scope of the property map.¶

9.3.Impact on Other Properties

In the present extension, properties can be defined for sets of entityaddresses, rather than just individual endpoint addresses as initially definedin[RFC7285]. This might change the semantics of a property. These sets can be,for example, hierarchical IP address blocks. For instance, a property such as thefictitious "geo-location" defined for a set of IP addresses would have avalue corresponding to a location representative of all the addresses in this set.¶

10.1.Network Map

The examples in this section use a very simple default network map:¶

And another simple alternative network map:¶

10.2.Property Definitions

Beyond "pid", the examples in this section use four additional, fictitious property types for entities of domain type "ipv4": "countrycode", "ASN", "ISP", and "state". These properties are assumed to be resource-agnostic so their name is identical to their type. The entities have the following values:¶

The examples in this section use the property "region" for the PID domain of the default network map with the following values:¶

Note that "-" means the value of the property for the entity is "undefined". So the entity would inherit a value for this property by the inheritance rule if possible. For example, the value of the "ISP" property for "ipv4:192.0.2.1" is "BitsRus" because of "ipv4:192.0.2.0/24". But the "region" property for "pid:defaultpid" has no value because there is no entity from which it can inherit.¶

Similar to the PID domain of the default network map, the examples in this section use the property "ASN" for the PID domain of the alternative network map with the following values:¶

10.3.Information Resource Directory (IRD)

The following IRD defines ALTO Server information resources that are relevant to the Entity Property Service. It provides a property map for the "ISP" and "ASN" properties. The server could have provided a single property map for all four properties, but it does not, presumably because the organization that runs the ALTO server believes that a client is not necessarily interested in getting all four properties.¶

The server provides several filtered property maps. The first returns all four properties, and the second returns only the "pid" property for the default network map and the "alt-network-map".¶

The filtered property maps for the "ISP", "ASN", "countrycode", and "state" properties do not depend on the default network map (it does not have a "uses" capability) because the definitions of those properties do not depend on the default network map. The filtered property map providing the "pid" property does have a "uses" capability for the default network map because the default network map defines the values of the "pid" property.¶

Note that for legacy clients, the ALTO server provides an Endpoint Property Service for the "pid" property defined for the endpoints of the default network map and the "alt-network-map".¶

The server provides another filtered Property map resource, named "ane-dc-property-map", that returns fictitious properties named "storage-capacity", "ram", and "cpu" for ANEs that have a persistent identifier. The entity domain to which the ANEs belong is self-defined and valid only within the property map.¶

The other property maps in the returned IRD are shown here for purposes of illustration.¶

 GET /directory HTTP/1.1 Host: alto.example.com Accept: application/alto-directory+json,application/alto-error+json HTTP/1.1 200 OK Content-Length: 2713 Content-Type: application/alto-directory+json {   "meta" : {     "default-alto-network-map" : "default-network-map"   },   "resources" : {     "default-network-map" : {       "uri" : "http://alto.example.com/networkmap/default",       "media-type" : "application/alto-networkmap+json"     },     "alt-network-map" : {       "uri" : "http://alto.example.com/networkmap/alt",       "media-type" : "application/alto-networkmap+json"     },     "ia-property-map" : {       "uri" : "http://alto.example.com/propmap/full/inet-ia",       "media-type" : "application/alto-propmap+json",       "capabilities" : {         "mappings": {           "ipv4": [ ".ISP", ".ASN" ],           "ipv6": [ ".ISP", ".ASN" ]         }       }     },     "iacs-property-map" : {       "uri" : "http://alto.example.com/propmap/lookup/inet-iacs",       "media-type" : "application/alto-propmap+json",       "accepts": "application/alto-propmapparams+json",       "capabilities" : {         "mappings": {           "ipv4": [ ".ISP", ".ASN", ".countrycode", ".state" ],           "ipv6": [ ".ISP", ".ASN", ".countrycode", ".state" ]         }       }     },     "region-property-map": {       "uri": "http://alto.example.com/propmap/lookup/region",       "media-type": "application/alto-propmap+json",       "accepts": "application/alto-propmapparams+json",       "uses" : [ "default-network-map", "alt-network-map" ],       "capabilities": {         "mappings": {           "default-network-map.pid": [ ".region" ],           "alt-network-map.pid": [ ".ASN" ]         }       }     },     "ip-pid-property-map" : {       "uri" : "http://alto.example.com/propmap/lookup/pid",       "media-type" : "application/alto-propmap+json",       "accepts" : "application/alto-propmapparams+json",       "uses" : [ "default-network-map", "alt-network-map" ],       "capabilities" : {         "mappings": {           "ipv4": [ "default-network-map.pid",                     "alt-network-map.pid" ],           "ipv6": [ "default-network-map.pid",                     "alt-network-map.pid" ]         }       }     },     "legacy-endpoint-property" : {       "uri" : "http://alto.example.com/legacy/eps-pid",       "media-type" : "application/alto-endpointprop+json",       "accepts" : "application/alto-endpointpropparams+json",       "capabilities" : {         "properties" : [ "default-network-map.pid",                          "alt-network-map.pid" ]       }     },     "ane-dc-property-map": {       "uri" : "http://alto.example.com/propmap/lookup/ane-dc",       "media-type" : "application/alto-propmap+json",       "accepts": "application/alto-propmapparams+json",       "capabilities": {         "mappings": {           ".ane" : [ "storage-capacity", "ram", "cpu" ]         }       }     }   } }

10.4.Full Property Map Example

The following example uses the properties and IRD defined inSection 10.3 to retrieve a property map for entities with the "ISP" and "ASN" properties.¶

Note that, to be compact, the response does not include the entity "ipv4:192.0.2.1" because values of all those properties for this entity are inherited from other entities.¶

Also note that the entities "ipv4:192.0.2.0/28" and "ipv4:192.0.2.16/28" are merged into "ipv4:192.0.2.0/27" because they have the same value of the "ASN" property. The same rule applies to the entities "ipv4:192.0.3.0/28" and "ipv4:192.0.3.16/28". Both "ipv4:192.0.2.0/27" and "ipv4:192.0.3.0/27" omit the value for the "ISP" property because it is inherited from "ipv4:192.0.2.0/23".¶

GET /propmap/full/inet-ia HTTP/1.1Host: alto.example.comAccept: application/alto-propmap+json,application/alto-error+json

HTTP/1.1 200 OKContent-Length: 418Content-Type: application/alto-propmap+json{  "meta": {    "dependent-vtags": [      {"resource-id": "default-network-map",       "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"},      {"resource-id": "alt-network-map",       "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"}    ]  },  "property-map": {    "ipv4:192.0.2.0/23":   {".ISP": "BitsRus"},    "ipv4:192.0.2.0/27":   {".ASN": "65543"},    "ipv4:192.0.3.0/27":   {".ASN": "65544"}  }}

10.5.Filtered Property Map Example #1

The following example uses the filtered property map resource to request the "ISP", "ASN", and "state" properties for several IPv4 addresses.¶

Note that the value of "state" for "ipv4:192.0.2.1" is the only explicitly defined property; the other values are all derived from the inheritance rules for Internet address entities.¶

POST /propmap/lookup/inet-iacs HTTP/1.1Host: alto.example.comAccept: application/alto-propmap+json,application/alto-error+jsonContent-Length: 158Content-Type: application/alto-propmapparams+json{  "entities" : [ "ipv4:192.0.2.0",                 "ipv4:192.0.2.1",                 "ipv4:192.0.2.17" ],  "properties" : [ ".ISP", ".ASN", ".state" ]}

HTTP/1.1 200 OKContent-Length: 540Content-Type: application/alto-propmap+json{  "meta": {    "dependent-vtags": [      {"resource-id": "default-network-map",       "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"},      {"resource-id": "alt-network-map",       "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"}    ]  },  "property-map": {    "ipv4:192.0.2.0":           {".ISP": "BitsRus", ".ASN": "65543", ".state": "NJ"},    "ipv4:192.0.2.1":           {".ISP": "BitsRus", ".ASN": "65543", ".state": "PA"},    "ipv4:192.0.2.17":           {".ISP": "BitsRus", ".ASN": "65543", ".state": "CT"}  }}

10.6.Filtered Property Map Example #2

The following example uses the filtered property map resource to request the "ASN", "countrycode", and "state" properties for several IPv4 prefixes.¶

Note that the property values for both entities "ipv4:192.0.2.0/26" and "ipv4:192.0.3.0/26" are not explicitly defined. They are inherited from the entity "ipv4:192.0.2.0/23".¶

Also note that some entities like "ipv4:192.0.2.0/28" and "ipv4:192.0.2.16/28" in the response are not explicitly listed in the request. The response includes them because they are refinements of the requested entities and have different values for the requested properties.¶

The entity "ipv4:192.0.4.0/26" is not included in the response because there are neither entities from which it is inherited, nor entities inherited from it.¶

POST /propmap/lookup/inet-iacs HTTP/1.1Host: alto.example.comAccept: application/alto-propmap+json,application/alto-error+jsonContent-Length: 174Content-Type: application/alto-propmapparams+json{  "entities" : [ "ipv4:192.0.2.0/26",                 "ipv4:192.0.3.0/26",                 "ipv4:192.0.4.0/26" ],  "properties" : [ ".ASN", ".countrycode", ".state" ]}

HTTP/1.1 200 OKContent-Length: 774Content-Type: application/alto-propmap+json{  "meta": {    "dependent-vtags": [      {"resource-id": "default-network-map",       "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"},      {"resource-id": "alt-network-map",       "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"}    ]  },  "property-map": {    "ipv4:192.0.2.0/26":  {".countrycode": "us"},    "ipv4:192.0.2.0/28":  {".ASN": "65543",                           ".state": "NJ"},    "ipv4:192.0.2.16/28": {".ASN": "65543",                           ".state": "CT"},    "ipv4:192.0.2.1":     {".state": "PA"},    "ipv4:192.0.3.0/26":  {".countrycode": "us"},    "ipv4:192.0.3.0/28":  {".ASN": "65544",                           ".state": "TX"},    "ipv4:192.0.3.16/28": {".ASN": "65544",                           ".state": "MN"}  }}

10.7.Filtered Property Map Example #3

The following example uses the filtered property map resource to request the"default-network-map.pid" property and the "alt-network-map.pid" property fora set of IPv4 addresses and prefixes.¶

Note that the entity "ipv4:192.0.3.0/27" is decomposed into two entities:"ipv4:192.0.3.0/28" and "ipv4:192.0.3.16/28", as they have different"default-network-map.pid" property values.¶

POST /propmap/lookup/pid HTTP/1.1Host: alto.example.comAccept: application/alto-propmap+json,application/alto-error+jsonContent-Length: 222Content-Type: application/alto-propmapparams+json{  "entities" : [                "ipv4:192.0.2.128",                "ipv4:192.0.2.0/27",                "ipv4:192.0.3.0/27" ],  "properties" : [ "default-network-map.pid",                   "alt-network-map.pid" ]}

HTTP/1.1 200 OKContent-Length: 774Content-Type: application/alto-propmap+json{  "meta": {    "dependent-vtags": [      {"resource-id": "default-network-map",       "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e"},      {"resource-id": "alt-network-map",       "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d"}    ]  },  "property-map": {    "ipv4:192.0.2.128":   {"default-network-map.pid": "defaultpid",                           "alt-network-map.pid": "defaultpid"},    "ipv4:192.0.2.0/27":  {"default-network-map.pid": "pid2",                           "alt-network-map.pid": "pid1"},    "ipv4:192.0.3.0/28":  {"default-network-map.pid": "pid3",                           "alt-network-map.pid": "pid2"},    "ipv4:192.0.3.16/28": {"default-network-map.pid": "pid4",                           "alt-network-map.pid": "pid2"}  }}

10.8.Filtered Property Map Example #4

Here is an example of using the filtered property map to query the regionsfor several PIDs in "default-network-map". The "region" property is specifiedas a self-defined property, i.e., the values of this property are definedby this property map resource.¶

POST /propmap/lookup/region HTTP/1.1Host: alto.example.comAccept: application/alto-propmap+json,application/alto-error+jsonContent-Length: 132Content-Type: application/alto-propmapparams+json{  "entities" : ["default-network-map.pid:pid1",                "default-network-map.pid:pid2"],  "properties" : [ ".region" ]}

HTTP/1.1 200 OKContent-Length: 326Content-Type: application/alto-propmap+json{  "meta" : {    "dependent-vtags" : [       {"resource-id": "default-network-map",        "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62"}    ]  },  "property-map": {    "default-network-map.pid:pid1": {      ".region": "us-west"    },    "default-network-map.pid:pid2": {      ".region": "us-east"    }  }}

10.9.Filtered Property Map for ANEs Example #5

The following example uses the filtered property map resource"ane-dc-property-map" to request properties "storage-capacity" and "cpu" onseveral ANEs defined in this property map.¶

POST /propmap/lookup/ane-dc HTTP/1.1Host: alto.example.comAccept: application/alto-propmap+json,application/alto-error+jsonContent-Length: 155Content-Type: application/alto-propmapparams+json{  "entities" : [".ane:dc21",                ".ane:dc45-srv9",                ".ane:dc6-srvcluster8"],  "properties" : [ "storage-capacity", "cpu"]}

HTTP/1.1 200 OKContent-Length: 295Content-Type: application/alto-propmap+json{  "meta" : {  },  "property-map": {    ".ane:dc21":      {"storage-capacity" : 40000, "cpu" : 500},    ".ane:dc45-srv9":      {"storage-capacity" : 100, "cpu" : 20},    ".ane:dc6-srvcluster8":      {"storage-capacity" : 6000, "cpu" : 100}  }}

12.1.application/alto-propmap+json Media Type

Type name:

application¶

Subtype name:

alto-propmap+json¶

Required parameters:

n/a¶

Optional parameters:

n/a¶

Encoding considerations:

Encoding considerations are identical to those specified for the "application/json" media type. See[RFC8259].¶

Security considerations:

Security considerations related to the generation and consumption of ALTO Protocol messages are discussed inSection 15 of [RFC7285] andSection 11 of this document.¶

Interoperability considerations:

n/a¶

Published specification:

This document is the specification for this media type. SeeSection 7.1.¶

Applications that use this media type:

ALTO servers and ALTO clients[RFC7285], either standalone or embedded within other applications, when the queried resource is a property map, whether filtered or not.¶

Fragment identifier considerations:

n/a¶

Additional information:

Magic number(s):

n/a¶

File extension(s):

n/a¶

Macintosh file type code(s):

n/a¶

Person & email address to contact for further information:

See Authors' Addresses section.¶

Intended usage:

COMMON¶

Restrictions on usage:

n/a¶

Author:

See Authors' Addresses section.¶

Change controller:

Internet Engineering Task Force (iesg@ietf.org).¶

12.2.alto-propmapparams+json Media Type

Type name:

application¶

Subtype name:

alto-propmapparams+json¶

Required parameters:

n/a¶

Optional parameters:

n/a¶

Encoding considerations:

Encoding considerations are identical to those specified for the "application/json" media type. See[RFC8259].¶

Security considerations:

Security considerations related to the generation and consumption of ALTO Protocol messages are discussed inSection 15 of [RFC7285] andSection 11 of this document.¶

Interoperability considerations:

n/a¶

Published specification:

This document is the specification for this media type. SeeSection 8.3.¶

Applications that use this media type:

ALTO servers and ALTO clients[RFC7285], either standalone or embedded within other applications, when the queried resource is a filtered property map. This media type indicates the data format used by the ALTO client to supply the property map filtering parameters.¶

Fragment identifier considerations:

n/a¶

Additional information:

Magic number(s):

n/a¶

File extension(s):

n/a¶

Macintosh file type code(s):

n/a¶

Person & email address to contact for further information:

See Authors' Addresses section.¶

Intended usage:

COMMON¶

Restrictions on usage:

n/a¶

Author:

See Authors' Addresses section.¶

Change controller:

Internet Engineering Task Force (iesg@ietf.org).¶

12.3.ALTO Entity Domain Types Registry

IANA has created and will maintain the "ALTO Entity Domain Types" registry listed inTable 9. The first row lists information items that must be provided with each registered entity domain type.Section 12.3.2 specifies how to document these items and in addition provides guidance on the security considerations item that must be documented.¶

This registry serves two purposes. First, it ensures uniqueness ofidentifiers referring to ALTO entity domain types. Second, it states therequirements for allocated entity domain types.¶

As specified inSection 5.1.1, identifiers prefixed with "priv:" are reserved for Private Use without a need to register with IANA¶

12.4.ALTO Entity Property Types Registry

IANA has created and will maintain the "ALTO Entity Property Types" registry, which is listed inTable 10.¶

This registry extends the "ALTO Endpoint Property Types" registry, defined in[RFC7285], in that a property type is defined for one or more entity domains, rather than just for IPv4 and IPv6 Internet address domains. An entry in this registry is an ALTO entity property type defined inSection 5.2.1. Thus, a registered ALTO entity property type identifierMUST conform to the syntactical requirements specified in that section.¶

As specified inSection 5.2.1, identifiers prefixed with "priv:" are reserved for Private Use without a need to register with IANA.¶

The first row ofTable 10 lists information items that must be provided with each registered entity property type.¶

New ALTO entity property types are assigned after IETF Review[RFC8126] to ensure that proper documentation regarding the new ALTO entity property types and their security considerations has been provided. RFCs defining new entity property typesSHOULD indicate how a property of a registered type is encoded as a property name. Updates and deletions of ALTO entity property types follow the same procedure.¶

Requests to IANA to add a new value to the registryMUST include thefollowing information:¶

Identifier:

The identifier for the desired ALTO entity property type. TheformatMUST be as defined inSection 5.2.1 of this document.¶

Intended Semantics:

ALTO entity properties carry with them semantics to guidetheir usage by ALTO clients. Hence, a document defining a new typeSHOULDprovide guidance to both ALTO service providers and applications utilizingALTO clients as to how values of the registered ALTO entity property shouldbe interpreted.¶

Media type of defining information resource:

when the property type allows values to be defined relative to a given information resource, the latter is referred to as the "defining information resource"; see the description inSection 4.7. For each property type, the potential defining information resources have one common media type. This unique common media type is specific to the property type andMUST be specified.¶

Security Considerations:

ALTO entity properties expose information to ALTOclients. ALTO service providers should be cognizant of the securityramifications related to the exposure of an entity property.¶

In security considerations, the request should also discuss the sensitivityof the information and why it is required for ALTO-based operations.Regarding this discussion, the requestSHOULD follow the recommendations ofthe "ALTO Endpoint Property Types" registry inSection 14.3 of [RFC7285].¶

IANA has registered the identifier "pid", which is listed inTable 10. Semantics for this property are documented inSection 7.1.1 of [RFC7285]. No security issues related to the exposure of a"pid" identifier are considered, as it is exposed with the Network MapService defined and mandated in[RFC7285].¶