Tech-invite3GPPspaceIETF RFCsSIP
9190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 5222

LoST: A Location-to-Service Translation Protocol

Pages: 69
Proposed Standard
Errata
Updated by:  684889179036
Part 2 of 3 – Pages 19 to 43
First   Prev   Next

Top   ToC   RFC5222 - Page 19   prevText

9. Retrieving the Service Boundary via <getServiceBoundary>

As discussed in Section 5.5, the <findServiceResponse> can return a globally unique identifier in the 'serviceBoundary' attribute that can be used to retrieve the service boundary, rather than returning the boundary by value. This is shown in the example in Figure 7 and Figure 8. The client can then retrieve the boundary using the <getServiceBoundary> request and obtains the boundary in the <getServiceBoundaryResponse>, illustrated in the example in Figure 9 and Figure 10. The client issues the request to the server identified in the 'server' attribute of the <serviceBoundaryReference> element. These requests are always directed to the authoritative server and do not recurse.
Top   ToC   RFC5222 - Page 20
   <?xml version="1.0" encoding="UTF-8"?>
   <findService
     xmlns="urn:ietf:params:xml:ns:lost1"
     xmlns:p2="http://www.opengis.net/gml"
     recursive="true"
     serviceBoundary="reference">
     <location id="6020688f1ce1896d" profile="geodetic-2d">
       <p2:Point id="point1" srsName="urn:ogc:def:crs:EPSG::4326">
          <p2:pos>37.775 -122.422</p2:pos>
       </p2:Point>
     </location>
     <service>urn:service:sos.police</service>
   </findService>

    Figure 7: <findService> request and response with service boundary
                                 reference

   <?xml version="1.0" encoding="UTF-8"?>
   <findServiceResponse xmlns="urn:ietf:params:xml:ns:lost1"
     xmlns:p2="http://www.opengis.net/gml">
     <mapping
       expires="2007-01-01T01:44:33Z"
       lastUpdated="2006-11-01T01:00:00Z"
       source="authoritative.example"
       sourceId="7e3f40b098c711dbb6060800200c9a66">
       <displayName xml:lang="en">
         New York City Police Department
       </displayName>
       <service>urn:service:sos.police</service>
       <serviceBoundaryReference
         source="authoritative.example"
         key="7214148E0433AFE2FA2D48003D31172E"/>
       <uri>sip:nypd@example.com</uri>
       <uri>xmpp:nypd@example.com</uri>
       <serviceNumber>911</serviceNumber>
     </mapping>
     <path>
       <via source="resolver.example"/>
       <via source="authoritative.example"/>
     </path>
     <locationUsed id="6020688f1ce1896d"/>
   </findServiceResponse>

       Figure 8: <findServiceResponse> message with service boundary
                                 reference
Top   ToC   RFC5222 - Page 21
   <?xml version="1.0" encoding="UTF-8"?>
   <getServiceBoundary xmlns="urn:ietf:params:xml:ns:lost1"
       key="7214148E0433AFE2FA2D48003D31172E"/>

     Figure 9: Requesting a service boundary with <getServiceBoundary>

    <?xml version="1.0" encoding="UTF-8"?>
    <getServiceBoundaryResponse
      xmlns="urn:ietf:params:xml:ns:lost1">
        <serviceBoundary profile="geodetic-2d">
          <p2:Polygon srsName="urn:ogc:def::crs:EPSG::4326">
            <p2:exterior>
              <p2:LinearRing>
                <p2:pos>37.775 -122.4194</p2:pos>
                <p2:pos>37.555 -122.4194</p2:pos>
                <p2:pos>37.555 -122.4264</p2:pos>
                <p2:pos>37.775 -122.4264</p2:pos>
                <p2:pos>37.775 -122.4194</p2:pos>
              </p2:LinearRing>
            </p2:exterior>
          </p2:Polygon>
        </serviceBoundary>
      <path>
        <via source="resolver.example"/>
        <via source="authoritative.example"/>
      </path>
    </getServiceBoundaryResponse>

               Figure 10: Geodetic service boundary response

10. List Services: <listServices>

A LoST client can ask a LoST server for the list of services that it understands, primarily for diagnostic purposes. The query does not contain location information, as it simply provides an indication of which services the server can look up, not whether a particular service is offered for a particular area. Typically, only top-level services are included in the answer, implying support for all sub- services. Since the query is answered by the queried server, there is no notion of recursion or indirection. The <listServicesByLocation> (Section 11) query below can be used to find out whether a particular service is offered for a specific location. An example request and response are shown in Figure 11.
Top   ToC   RFC5222 - Page 22
   <?xml version="1.0" encoding="UTF-8"?>
   <listServices
     xmlns="urn:ietf:params:xml:ns:lost1">
     <service>urn:service:sos</service>
   </listServices>

                Figure 11: Example of <ListServices> query

   <?xml version="1.0" encoding="UTF-8"?>
   <listServicesResponse
    xmlns="urn:ietf:params:xml:ns:lost1">
    <serviceList>
     urn:service:sos.ambulance
     urn:service:sos.animal-control
     urn:service:sos.fire
     urn:service:sos.gas
     urn:service:sos.mountain
     urn:service:sos.marine
     urn:service:sos.physician
     urn:service:sos.poison
     urn:service:sos.police
    </serviceList>
    <path>
     <via source="authoritative.example"/>
    </path>
   </listServicesResponse>

               Figure 12: Example of <ListServicesResponse>

11. List Services By Location: <listServicesByLocation>

A LoST client can ask a LoST server for the list of services it knows about for a particular area. The <listServicesByLocation> query contains one or more <location> elements, each from a different location profile (Section 12), and may contain the <service> element. As for <findService>, the server selects the first location element that has a profile the server understands and it can operate either recursively or iteratively; <via> elements track the progress of the request. The query indicates the services that the server can enumerate from within the forest structure of which it is a part. Because LoST does not presume a single, overarching organization of all potential service types, there may be services available within a geographic area that could be described by other LoST servers connected to other forest structures. As an example, the emergency services forest for a region may be distinct from the forests that locate commercial services within the same region.
Top   ToC   RFC5222 - Page 23
   If the query contains the <service> element, the LoST server returns
   only immediate child services of the queried service that are
   available for the provided location.  If the <service> element is
   absent, the LoST service returns all top-level services available for
   the provided location that it knows about.

   A server responds to this query with a
   <listServicesByLocationResponse> response.  This response MAY contain
   <via> elements (see Section 6) and MUST contain a <serviceList>
   element, consisting of a whitespace-separated list of service URNs.
   The query and response are illustrated in Figure 13 and in Figure 14,
   respectively.

   <?xml version="1.0" encoding="UTF-8"?>
   <listServicesByLocation
     xmlns="urn:ietf:params:xml:ns:lost1"
     xmlns:p2="http://www.opengis.net/gml"
     recursive="true">
     <location id="3e19dfb3b9828c3" profile="geodetic-2d">
       <p2:Point srsName="urn:ogc:def:crs:EPSG::4326">
         <p2:pos>-34.407 150.883</p2:pos>
       </p2:Point>
     </location>
     <service>urn:service:sos</service>
   </listServicesByLocation>

           Figure 13: Example of <ListServicesbyLocation> query
Top   ToC   RFC5222 - Page 24
   <?xml version="1.0" encoding="UTF-8"?>
   <listServicesByLocationResponse
    xmlns="urn:ietf:params:xml:ns:lost1">
    <serviceList>
     urn:service:sos.ambulance
     urn:service:sos.animal-control
     urn:service:sos.fire
     urn:service:sos.gas
     urn:service:sos.mountain
     urn:service:sos.marine
     urn:service:sos.physician
     urn:service:sos.poison
     urn:service:sos.police
    </serviceList>
    <path>
     <via source="resolver.example"/>
     <via source="authoritative.example"/>
    </path>
    <locationUsed id="3e19dfb3b9828c3"/>
   </listServicesByLocationResponse>

      Figure 14: Example of <ListServicesByLocationResponse> response

12. Location Profiles

LoST uses location information in <location> elements in requests and <serviceBoundary> elements in responses. Such location information may be expressed in a variety of ways. This variety can cause interoperability problems where a request or response contains location information in a format not understood by the server or the client, respectively. To achieve interoperability, this document defines two mandatory-to-implement baseline location profiles to define the manner in which location information is transmitted. It is possible to standardize other profiles in the future. The baseline profiles are: geodetic-2d: a profile for two-dimensional geodetic location information, as described in Section 12.2;. civic: a profile consisting of civic address location information, as described in Section 12.3.
Top   ToC   RFC5222 - Page 25
   Requests and responses containing <location> or <serviceBoundary>
   elements MUST contain location information in exactly one of the two
   baseline profiles, in addition to zero or more additional profiles.
   The ordering of location information indicates a preference on the
   part of the sender.

   Standards action is required for defining new profiles.  A location
   profile MUST define:

   1.  The token identifying it in the LoST location profile registry.

   2.  The formal definition of the XML to be used in requests, i.e., an
       enumeration and definition of the XML child elements of the
       <location> element.

   3.  The formal definition of the XML to be used in responses, i.e.,
       an enumeration and definition of the XML child elements of the
       <serviceBoundary> element.

   4.  The declaration of whether geodetic-2d or civic is to be used as
       the baseline profile.  It is necessary to explicitly declare the
       baseline profile as future profiles may be combinations of
       geodetic and civic location information.

12.1. Location Profile Usage

A location profile is identified by a token in an IANA-maintained registry (Section 17.5). Clients send location information compliant with a location profile, and servers respond with location information compliant with that same location profile. When a LoST client sends a <findService> request that provides location information, it includes one or more <location> elements. A <location> element carries an optional 'profile' attribute that indicates the location format of the child elements. A client may obtain location information that does not conform to a profile it recognizes, or it may not have the capability to map XML to profiles. In that case, a client MAY omit the profile attribute and the server should interpret the XML location data to the best of its ability, returning a "locationProfileUnrecognized" error if it is unable to do so. The concept of location profiles is described in Section 12. With the ability to specify more than one <location> element, the client is able to convey location information for multiple location profiles in the same request.
Top   ToC   RFC5222 - Page 26
   When a LoST server sends a response that contains location
   information, it uses the <serviceBoundary> elements much like the
   client uses the <location> elements.  Each <serviceBoundary> element
   contains location information conforming to the location profile
   specified in the 'profile' attribute.  A response MAY contain
   multiple mappings or boundaries for the different <location>
   elements, subject to the restrictions below.

   Using the location profiles defined in this document, the following
   rules ensure interoperability between clients and servers:

   1.  A client MUST be capable of understanding the response for the
       baseline profiles it used in the request.

   2.  If a client sends location information conformant to any location
       profile other than the ones described in this document, it MUST
       also send, in the same request, location information conformant
       to one of the baseline profiles.  Otherwise, the server might not
       be able to understand the request.

   3.  A client MUST NOT send multiple <location> objects that are
       derived from different baseline profiles.  In other words, a
       client MUST only send location objects according to the same
       baseline profile in a query, but it MAY contain a location
       element following a baseline profile in addition to some other
       profile.

   4.  If a client has both location information primarily of geodetic
       nature and location information primarily of a civic nature, it
       MUST send separate requests containing each type of location
       information.

   5.  There can only be one instance of each location profile in a
       query.

   6.  Servers MUST implement all profiles described in this document.

   7.  A server uses the first-listed location profile that it
       understands and ignores the others.

   8.  If a server receives a request that only contains location
       information using profiles it does not understand, the server
       responds with a <locationProfileError> (Section 13.1).
Top   ToC   RFC5222 - Page 27
   9.  The <serviceBoundary> element MUST use the same location profile
       that was used to retrieve the answer and indicates which profile
       has been used with the 'profile' attribute.

   These rules enable the use of location profiles not yet specified,
   while ensuring baseline interoperability.  Take, for example, this
   scenario illustrated in Figure 15 and 16.  Client X has had its
   firmware upgraded to support the 'not-yet-standardized-prism-profile'
   location profile.  Client X sends location information to Server Y,
   which does not understand the 'not-yet-standardized-prism-profile'
   location profile.  If Client X also sends location information using
   the geodetic-2D baseline profile, then Server Y will still be able to
   understand the request and provide an understandable response, though
   with location information that might not be as precise or expressive
   as desired.  This is possible because both Client X and Server Y
   understand the baseline profile.
Top   ToC   RFC5222 - Page 28
   <?xml version="1.0" encoding="UTF-8"?>
   <findService
     xmlns="urn:ietf:params:xml:ns:lost1"
     xmlns:gml="http://www.opengis.net/gml"
     xmlns:gs="http://www.opengis.net/pidflo/1.0"
     recursive="true"
     serviceBoundary="value">
     <location id="ABC 123"
         profile="not-yet-standardized-prism-profile">
       <gs:Prism srsName="urn:ogc:def:crs:EPSG::4979">
         <gs:base>
           <gml:Polygon>
             <gml:exterior>
               <gml:LinearRing>
                 <gml:posList>
                   42.556844 -73.248157 36.6
                   42.656844 -73.248157 36.6
                   42.656844 -73.348157 36.6
                   42.556844 -73.348157 36.6
                   42.556844 -73.248157 36.6
                 </gml:posList>
               </gml:LinearRing>
             </gml:exterior>
           </gml:Polygon>
         </gs:base>
         <gs:height uom="urn:ogc:def:uom:EPSG::9001">
           2.4
         </gs:height>
       </gs:Prism>
     </location>
     <location id="DEF 345" profile="geodetic-2d">
       <gml:Point id="point1" srsName="urn:ogc:def:crs:EPSG:4326">
         <gml:pos>42.656844 -73.348157</gml:pos>
       </gml:Point>
     </location>
     <service>urn:service:sos.police</service>
   </findService>

    Figure 15: Example of a <findServices> query with baseline profile
                             interoperability
Top   ToC   RFC5222 - Page 29
   <?xml version="1.0" encoding="UTF-8"?>
   <findServiceResponse
     xmlns="urn:ietf:params:xml:ns:lost1"
     xmlns:p2="http://www.opengis.net/">
     <mapping
       expires="2007-01-01T01:44:33Z"
       lastUpdated="2006-11-01T01:00:00Z"
       source="authoritative.example"
       sourceId="cf19bbb038fb4ade95852795f045387d">
       <displayName xml:lang="en">
         New York City Police Department
       </displayName>
       <service>urn:service:sos.police</service>
       <serviceBoundary profile="geodetic-2d">
         <p2:Polygon srsName="urn:ogc:def::crs:EPSG::4326">
           <p2:exterior>
             <p2:LinearRing>
               <p2:pos>37.775 -122.4194</p2:pos>
               <p2:pos>37.555 -122.4194</p2:pos>
               <p2:pos>37.555 -122.4264</p2:pos>
               <p2:pos>37.775 -122.4264</p2:pos>
               <p2:pos>37.775 -122.4194</p2:pos>
             </p2:LinearRing>
           </p2:exterior>
         </p2:Polygon>
       </serviceBoundary>
       <uri>sip:nypd@example.com</uri>
       <serviceNumber>911</serviceNumber>
     </mapping>
     <path>
       <via source="resolver.example"/>
       <via source="authoritative.example"/>
     </path>
     <locationUsed id="DEF 345"/>
   </findServiceResponse>

    Figure 16: Example of a <findServiceResponse> message with baseline
                         profile interoperability
Top   ToC   RFC5222 - Page 30

12.2. Two-Dimensional Geodetic Profile

The "geodetic-2d" location profile is identified by the token "geodetic-2d". Clients and servers use this profile by placing the following location shapes into the <serviceBoundary> or into the <location> element (unless indicated otherwise): Point: The <Point> element is described in Section 5.2.1 of [13]. Section 5.2.1 of [13] shows also the specification of a <Point> with either a two-dimensional position (latitude and longitude) or three-dimensional position (latitude, longitude, and altitude). A client MAY use the three-dimensional position, and servers MAY interpret a three-dimensional position as a two-dimensional position by ignoring the altitude value. A <Point> element is not placed into a <serviceBoundary> element. Polygon: The <Polygon> element is described in Section 5.2.2 of [13]. The restriction to 16 points for a polygon contained in Section 7.2.2 of [12] is not applicable to this document. Circle: The <Circle> element is described in Section 5.2.3 of [13]. Ellipse: The <Ellipse> element is described in Section 5.2.4 of [13]. ArcBand: The <ArcBand> element is described in Section 5.2.5 of [13]. When a client uses a <Polygon>, <Circle>, <Ellipse>, or <ArcBand> element within the <location> element, it is indicating that it will be satisfied by query results appropriate to any portion of the shape. It is left to the server to select an appropriate matching algorithm. A server MAY return multiple <mapping> elements if the shape extends across multiple service areas. Servers are not required to return all possible <mapping> elements to avoid denial- of-service attacks in which clients present queries that span a very large number of service boundaries (e.g., presenting a shape covering all of the United States). In the case where the server does not return multiple <mapping> elements, but the shape extends across a service boundary, it is possible that the matching algorithm selected by the LoST server will return results that match a portion of the shape but do not match those specific to a particular point. A client may always select a point from within the shape to avoid this condition. The cases where
Top   ToC   RFC5222 - Page 31
   it does not are generally those where it knows its own position only
   within the shape given.  In emergency service use cases, that may
   result in the PSAP contacted at the URI provided by LoST being
   required to forward a call to one of its neighbors; this is an
   expected part of the overall emergency response system.  In non-
   emergency service use cases, the service deployment model should take
   into account this issue as part of the provisioning model, as the
   combination of the data in the LoST server and the algorithm used for
   mapping determine which contact URIs are returned when shapes are
   used that overlap multiple service areas.

   As a general guideline, any deployed matching algorithm should ensure
   that the algorithm used does not needlessly return no results if
   there are valid results for any portion of the shape.  If an
   authoritative server receives a query for which the area in the query
   overlaps the area for which the server has mapping information, then
   it MUST return either a mapping whose coverage area intersects the
   query area or a redirect to another server whose coverage area is a
   subset of the server's coverage area.

   When geodetic location information of this location profile is placed
   in the <serviceBoundary> element, then the elements with geospatial
   coordinates are alternative descriptions of the same service region,
   not additive geometries.

12.3. Basic Civic Profile

The basic civic location profile is identified by the token 'civic'. Clients use this profile by placing a <civicAddress> element, defined in [10], within the <location> element. Servers use this profile by placing a <civicAddress> element, defined in [10], within the <serviceBoundary> element. A response MAY contain more than one <serviceBoundary> element with profile 'civic'. Each <serviceBoundary> element describes a set of civic addresses that fall within the service boundary, namely, all addresses that textually match the civic address elements provided, regardless of the value of other address elements. A location falls within the mapping's service boundary if it matches any of the <serviceBoundary> elements. Hence, a response may contain multiple <serviceBoundary> elements with civic and/or geodetic location profiles.
Top   ToC   RFC5222 - Page 32

13. Errors, Warnings, and Redirects

When a LoST server cannot fulfill a request completely, it can return either an error or a warning, depending on the severity of the problem. It returns an <errors> element if no useful response can be returned for the query. It returns a <warnings> element as part of another response element if it was able to respond in part, but the response may not be quite what the client had desired. For both elements, the 'source' attribute names the server that originally generated the error or warning, such as the authoritative server. Unless otherwise noted, all elements below can be either an error or a warning, depending on whether a default response, such as a mapping, is included.

13.1. Errors

LoST defines a pattern for errors, defined as <errors> elements in the Relax NG schema. This pattern defines a 'message' attribute containing human-readable text and an 'xml:lang' attribute denoting the language of the human-readable text. One or more such error elements are contained in the <errors> element. The following errors follow this basic pattern: badRequest The server could not parse or otherwise understand a request, e.g., because the XML was malformed. forbidden The server refused to send an answer. This generally only occurs for recursive queries, namely, if the client tried to contact the authoritative server and was refused. internalError The server could not satisfy a request due to misconfiguration or other operational and non-protocol-related reasons. locationProfileUnrecognized None of the profiles in the request were recognized by the server (see Section 12). locationInvalid The geodetic or civic location in the request was invalid. For example, the longitude or latitude values fall outside the acceptable ranges.
Top   ToC   RFC5222 - Page 33
   SRSInvalid
      The spatial reference system (SRS) contained in the location
      element was not recognized or does not match the location profile.

   loop
      During a recursive query, the server was about to visit a server
      that was already in the server list in the <path> element,
      indicating a request loop.

   notFound
      The server could not find an answer to the query.

   serverError
      An answer was received from another LoST server, but it could not
      be parsed or otherwise understood.  This error occurs only for
      recursive queries.

   serverTimeout
      A time out occurred before an answer was received.

   serviceNotImplemented
      The requested service URN is not implemented and no substitution
      was available.

   An example is below:

   <?xml version="1.0" encoding="UTF-8"?>
   <errors xmlns="urn:ietf:params:xml:ns:lost1"
     source="resolver.example">
      <internalError message="Software bug." xml:lang="en"/>
   </errors>

                  Figure 17: Example of an error response
Top   ToC   RFC5222 - Page 34

13.2. Warnings

A response MAY contain zero or more warnings. This pattern defines a 'message' attribute containing human-readable text and an 'xml:lang' attribute denoting the language of the human-readable text. One or more such warning elements are contained in the <warnings> element. To provide human-readable text in an appropriate language, the HTTP content negotiation capabilities (see Section 14) MAY be utilized by a server. This version of the specification defines the following warnings: locationValidationUnavailable The <locationValidationUnavailable> element MAY be returned when a server wishes to notify a client that it cannot fulfill a location validation request. This warning allows a server to return mapping information while signaling this exception state. serviceSubstitution The <serviceSubstitution> element MAY be returned when a server was not able to fulfill a <findService> request for a given service URN. For example, a <findService> request with the 'urn:service:sos.police' service URN for a location in Uruguay may cause the LoST service to return a mapping for the 'urn:service:sos' service URN since Uruguay does not make use of the sub-services police, fire, and ambulance. If this warning is returned, then the <service> element in the response provides information about the service URN that refers to the mapping. defaultMappingReturned The <defaultMappingReturned> element MAY be returned when a server was not able to fulfill a <findService> request for a given location but is able to respond with a default URI. For example, a nearby PSAP may be returned.
Top   ToC   RFC5222 - Page 35
   An example of a warning is shown below:

    <?xml version="1.0" encoding="UTF-8"?>
    <findServiceResponse xmlns="urn:ietf:params:xml:ns:lost1"
      xmlns:p2="http://www.opengis.net/">
      <mapping
        expires="2007-01-01T01:44:33Z"
        lastUpdated="2006-11-01T01:00:00Z"
        source="authoritative.example"
        sourceId="fb8ed888433343b7b27865aeb38f3a99">
        <displayName xml:lang="en">
          New York City Police Department
        </displayName>
        <service>urn:service:sos.police</service>
        <serviceBoundary profile="geodetic-2d">
          <p2:Polygon srsName="urn:ogc:def::crs:EPSG::4326">
            <p2:exterior>
              <p2:LinearRing>
                <p2:pos>37.775 -122.4194</p2:pos>
                <p2:pos>37.555 -122.4194</p2:pos>
                <p2:pos>37.555 -122.4264</p2:pos>
                <p2:pos>37.775 -122.4264</p2:pos>
                <p2:pos>37.775 -122.4194</p2:pos>
              </p2:LinearRing>
            </p2:exterior>
          </p2:Polygon>
        </serviceBoundary>
        <uri>sip:nypd@example.com</uri>
        <serviceNumber>911</serviceNumber>
      </mapping>
      <warnings source="authoritative.example">
        <defaultMappingReturned
            message="Unable to determine PSAP for the given location;
                using default PSAP"
            xml:lang="en"/>
      </warnings>
      <path>
        <via source="resolver.example"/>
        <via source="authoritative.example"/>
      </path>
    </findServiceResponse>

                 Figure 18: Example of a warning response
Top   ToC   RFC5222 - Page 36

13.3. Redirects

A LoST server can respond indicating that the querier should redirect the query to another server, using the <redirect> element. The element includes a 'target' attribute indicating the LoST application unique string (see Section 4) that the client SHOULD be contacting next, as well as the 'source' attribute indicating the server that generated the redirect response and a 'message' attribute explaining the reason for the redirect response. During a recursive query, a server receiving a <redirect> response can decide whether it wants to follow the redirection or simply return the response to its upstream querier. The "expires" value in the response returned by the server handling the redirected query indicates the earliest time at which a new query might be needed (see Section 5.2). The query for the same tuple of location and service SHOULD NOT be directed to the server that gave redirect prior to that time. An example is below: <?xml version="1.0" encoding="UTF-8"?> <redirect xmlns="urn:ietf:params:xml:ns:lost1" target="eastpsap.example" source="westpsap.example" message="We have temporarily failed over." xml:lang="en"/> Figure 19: Example of a redirect response

14. LoST Transport: HTTP

LoST needs an underlying protocol transport mechanism to carry requests and responses. This document defines the use of LoST over HTTP and LoST over HTTP-over-TLS. Client and server developers are reminded that full support of RFC 2616 HTTP facilities is expected. If LoST clients or servers re-implement HTTP, rather than using available servers or client code as a base, careful attention must be paid to full interoperability. Other transport mechanisms are left to future documents. The available transport mechanisms are determined through the use of the LoST U-NAPTR application. In protocols that support content type indication, LoST uses the media type application/lost+xml. When using HTTP [3] and HTTP-over-TLS [4], LoST requests use the HTTP POST method. The HTTP request MUST use the Cache-Control response directive "no-cache" to disable HTTP-level caching even by caches that have been configured to return stale responses to client requests.
Top   ToC   RFC5222 - Page 37
   All LoST responses, including those indicating a LoST warning or
   error, are carried in 2xx responses, typically 200 (OK).  Other 2xx
   responses, in particular 203 (Non-authoritative information), may be
   returned by HTTP caches that disregard the caching instructions. 3xx,
   4xx, and 5xx HTTP response codes indicate that the HTTP request
   itself failed or was redirected; these responses do not contain any
   LoST XML elements.  The 3xx responses are distinct from the redirects
   that are described in Section 13.3; the redirect operation in
   Section 13.3 occur after a LoST server processes the request.  Where
   an HTTP-layer redirect will be general, a LoST server redirect as
   described in Section 13.3 might be specific to a specific service or
   be the result of other processing by the LoST server.

   The HTTP URL is derived from the LoST server name via U-NAPTR
   application, as discussed above.

15. Relax NG Schema

This section provides the Relax NG schema used by the LoST protocol in the compact form. The verbose form is included in Appendix A. namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0" default namespace ns1 = "urn:ietf:params:xml:ns:lost1" ## ## Location-to-Service Translation (LoST) Protocol ## ## A LoST XML instance has three request types, each with ## a corresponding response type: find service, list services, ## and get service boundary. ## start = findService | listServices | listServicesByLocation | getServiceBoundary | findServiceResponse | listServicesResponse | listServicesByLocationResponse | getServiceBoundaryResponse | errors | redirect ## ## The queries. ## div {
Top   ToC   RFC5222 - Page 38
  findService =
    element findService {
      requestLocation,
      commonRequestPattern,
      attribute validateLocation {
        xsd:boolean >> a:defaultValue [ "false" ]
      }?,
      attribute serviceBoundary {
        ("reference" | "value") >> a:defaultValue [ "reference" ]
      }?,
      attribute recursive { xsd:boolean >> a:defaultValue [ "false" ] }?
    }
  listServices = element listServices { commonRequestPattern }
  listServicesByLocation =
    element listServicesByLocation {
      requestLocation,
      commonRequestPattern,
      attribute recursive { xsd:boolean >> a:defaultValue [ "true" ] }?
    }
  getServiceBoundary =
    element getServiceBoundary { serviceBoundaryKey, extensionPoint }
}

##
##       The responses.
##
div {
  findServiceResponse =
    element findServiceResponse {
      mapping+, locationValidation?, commonResponsePattern, locationUsed
    }
  listServicesResponse =
    element listServicesResponse { serviceList, commonResponsePattern }
  listServicesByLocationResponse =
    element listServicesByLocationResponse {
      serviceList, commonResponsePattern, locationUsed
    }
  getServiceBoundaryResponse =
    element getServiceBoundaryResponse {
      serviceBoundary, commonResponsePattern
    }
}

##
##       A pattern common to some of the queries.
##
div {
  commonRequestPattern = service, path?, extensionPoint
Top   ToC   RFC5222 - Page 39
}

##
##       A pattern common to responses.
##
div {
  commonResponsePattern = warnings*, path, extensionPoint
}

##
##       Location in Requests
##
div {
  requestLocation =
    element location {
      attribute id { xsd:token },
      locationInformation
    }+
}

##
##       Location Information
##
div {
  locationInformation =
    extensionPoint+,
    attribute profile { xsd:NMTOKEN }?
}

##
##       Service Boundary
##
div {
  serviceBoundary = element serviceBoundary { locationInformation }+
}

##
##       Service Boundary Reference
##
div {
  serviceBoundaryReference =
    element serviceBoundaryReference {
      source, serviceBoundaryKey, extensionPoint
    }
  serviceBoundaryKey = attribute key { xsd:token }
}

##
Top   ToC   RFC5222 - Page 40
##       Path -
##       Contains a list of via elements -
##       places through which information flowed
##
div {
  path =
    element path {
      element via { source, extensionPoint }+
    }
}

##
##       Location Used
##
div {
  locationUsed =
    element locationUsed {
      attribute id { xsd:token }
    }?
}

##
##       Expires pattern
##
div {
  expires =
    attribute expires { xsd:dateTime | "NO-CACHE" | "NO-EXPIRATION" }
}

##
##       A QName list
##
div {
  qnameList = list { xsd:QName* }
}

##
##       A location-to-service mapping.
##
div {
  mapping =
    element mapping {
      element displayName {
        xsd:string,
        attribute xml:lang { xsd:language }
      }*,
      service,
      (serviceBoundary | serviceBoundaryReference)?,
Top   ToC   RFC5222 - Page 41
      element uri { xsd:anyURI }*,
      element serviceNumber {
        xsd:token { pattern = "[0-9*#]+" }
      }?,
      extensionPoint,
      expires,
      attribute lastUpdated { xsd:dateTime },
      source,
      attribute sourceId { xsd:token },
      message
    }
}

##
##       Location validation
##
div {
  locationValidation =
    element locationValidation {
      element valid { qnameList }?,
      element invalid { qnameList }?,
      element unchecked { qnameList }?,
      extensionPoint
    }
}

##
##       Errors and Warnings Container.
##
div {
  exceptionContainer =
    (badRequest?
     & internalError?
     & serviceSubstitution?
     & defaultMappingReturned?
     & forbidden?
     & notFound?
     & loop?
     & serviceNotImplemented?
     & serverTimeout?
     & serverError?
     & locationInvalid?
     & locationProfileUnrecognized?),
    extensionPoint,
    source
  errors = element errors { exceptionContainer }
  warnings = element warnings { exceptionContainer }
}
Top   ToC   RFC5222 - Page 42
##
##       Basic Exceptions
##
div {

  ##
  ##         Exception pattern.
  ##
  basicException = message, extensionPoint
  badRequest = element badRequest { basicException }
  internalError = element internalError { basicException }
  serviceSubstitution = element serviceSubstitution { basicException }
  defaultMappingReturned =
    element defaultMappingReturned { basicException }
  forbidden = element forbidden { basicException }
  notFound = element notFound { basicException }
  loop = element loop { basicException }
  serviceNotImplemented =
    element serviceNotImplemented { basicException }
  serverTimeout = element serverTimeout { basicException }
  serverError = element serverError { basicException }
  locationInvalid = element locationInvalid { basicException }
  locationValidationUnavailable =
    element locationValidationUnavailable { basicException }
  locationProfileUnrecognized =
    element locationProfileUnrecognized {
      attribute unsupportedProfiles { xsd:NMTOKENS },
      basicException
    }
}

##
##       Redirect.
##
div {

  ##
  ##         Redirect pattern
  ##
  redirect =
    element redirect {
      attribute target { appUniqueString },
      source,
      message,
      extensionPoint
    }
}
Top   ToC   RFC5222 - Page 43
##
##       Some common patterns.
##
div {
  message =
    (attribute message { xsd:token },
     attribute xml:lang { xsd:language })?
  service = element service { xsd:anyURI }?
  appUniqueString =
    xsd:token { pattern = "([a-zA-Z0-9\-]+\.)+[a-zA-Z0-9]+" }
  source = attribute source { appUniqueString }
  serviceList =
    element serviceList {
      list { xsd:anyURI* }
    }
}

##
##       Patterns for inclusion of elements from schemas in
##       other namespaces.
##
div {

  ##
  ##         Any element not in the LoST namespace.
  ##
  notLost = element * - (ns1:* | ns1:*) { anyElement }

  ##
  ##         A wildcard pattern for including any element
  ##         from any other namespace.
  ##
  anyElement =
    (element * { anyElement }
     | attribute * { text }
     | text)*

  ##
  ##         A point where future extensions
  ##         (elements from other namespaces)
  ##         can be added.
  ##
  extensionPoint = notLost*
}

                         Figure 20: RelaxNG schema


(next page on part 3)

Next Section