($and/ <== DO NOT REMOVE - switch for preventing MathML interpretation of dollar signs on this page)

About

This page is the proposed specification for XDI discovery, a lightweight process for using the XDI protocol discover to the endpoint URI(s) authoritative for an XDI graph or subgraph.

Change Log

Introduction

XDI discovery is a peer-to-peer discovery protocol in which any peer root node in the global XDI graph can serve as a discovery root. XDI discovery may also be used in a hierarchical model when members of a discovery community agree to start discovery from a common root.

Like any federated identifier resolution protocol (e.g., DNS or XRI), the discovery process is one of “walking the chain” of linked identifiers until a discovery result is returned for the final identifier in the chain.

XDI discovery can be performed on an explicit set of peer root addresses, or implicitly on any local XDI address.

An example of explicit discovery would be performing discovery on (https://xdi.example.com/)([+]!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6)(urn:isbn:0451450523). Ignoring caching, this requires:

  1. First performing discovery on the peer root address (https://xdi.example.com/) to find the XDI endpoint URI for ([+]!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6).

  2. Second performing discovery at the XDI endpoint for ([+]!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6) to find the XDI endpoint URI for (urn:isbn:0451450523).

An example of implicit discovery would be performing discovery on +example[#division]*finance. Ignoring caching, this requires:

  1. First performing discovery on the peer root address (+example) to find the XDI endpoint URI for ([#division]).

  2. Second performing discovery at the XDI endpoint for ([#division]) to find the XDI endpoint URI for (*finance).

For XDI discovery, it is assumed that all XDI addresses in the discovery chain have corresponding XDI endpoints that can be queried using the XDI protocol. It is of course possible that some of the XDI addresses in a discovery chain do not have XDI endpoints and must be queried using another discovery protocol such as:

However the view of the XDI TC is that these non-XDI discovery protocols can be easily proxied by XDI servers offering XDI discovery service. These proxies can map responses from other discovery protocols into XDI responses. So the scope of this specification is restricted to pure XDI discovery.

Peer Root Address Rules

  1. XDI discovery only takes place on XDI peer root nodes as defined by the peer-root rule in the Consolidated ABNF. An XDI peer root address MUST be either:

    1. An XDI cross-reference to a native XDI address (i.e., enclosed in parentheses as specified in the Consolidated ABNF).

    2. An XDI cross-reference to a valid URI (i.e., percent-encoded and enclosed in parentheses -- see the xref rule the Consolidated ABNF).

  2. To discover the authoritative peer root address for a local XDI address:
    1. The first arc MUST be transformed into a peer root address by enclosing it in parentheses to make it an XDI cross-reference.
    2. If this peer root is not authoritative for the complete local XDI address, the next arc MUST be transformed into a peer root address and the discovery process repeated at the XDI endpoint for the previous peer root address (see the second example above.)

Endpoint URI Rules

Endpoint URI Attribute Rules

  1. To support XDI Discovery, an XDI endpoint MUST use the <$uri> attribute to describe its endpoint URI literals.

  2. The value of a <$uri> attribute singleton MUST be a valid URI as defined by RFC 3986.

  3. URI literal values MUST be in the fully normalized form defined by the associated URI type specification.
  4. A discoverable XDI root node:
    1. MUST have an attribute singleton with the address <$uri>.

    2. MAY have a URI attribute collection with the address [<$uri].

  5. If the XDI root node has BOTH URI attribute singleton and collection, the <$uri> singleton MUST be mapped into a member of the [<$uri>] collection using a $ref equivalence link (see EquivalenceLinks).

Endpoint URI Attribute Priority Rules

  1. If a [<$uri>] attribute collection is used, the collection MUST be ordered.

  2. Each member of the [<$uri>] collection MUST have exactly one unique ordering statement in the form [<$uri>]<--order-number-->/$ref/[<$uri>]<--member-id--> where <--order-number--> is an ordered attribute instance (e.g., <@3>) containing a non-negative integer representing the ordering priority and <--member-id--> is an unordered attribute instance (e.g., <!:uuid:3a96e460-7be9-11e2-b92a-0800200c0003>) representing the persistent ID of a URI instance.

  3. In the set of <order-number> integers, the lowest value integer MUST be the highest priority. Note that ordering in XDI is zero-based, so zero is the highest priority.

Endpoint URI Time-To-Live (TTL) Attribute Rules

  1. Either the <$uri> attribute singleton or [<$uri>] collection MUST contain a <$ttl> attribute singleton. This is called the URI time-to-live.

  2. The value of a URI expiration attribute MUST be a positive integer expessing the time to live expressed in seconds from the time the discovery response message is received by the XDI client.
  3. If both an <$uri> attribute singleton and the [<$uri>] collection contain a URI time-to-live attribute, the URI time-to-live attribute on the attribute singleton MUST be authoritative.

  4. If the URI time-to-live has passed, the discovery client MUST refresh the endpoint URI value.

Endpoint URI Type Rules

XDI Endpoint URI Types

  1. The default endpoint URI type for XDI discovery is XDI 1.0.
  2. The unversioned XDI address for this endpoint URI type is $xdi.

  3. The versioned XDI address for this endpoint URI type is $xdi$v#1.

  4. To support XDI Discovery:
    1. An XDI endpoint MUST contain a default XDI endpoint URI statement in the form $xdi<$uri>.

    2. The default endpoint URI MUST be an http: or https: URI. For trusted discovery the use of https: URIs is STRONGLY RECOMMENDED.

    3. If an XDI endpoint has more than one XDI endpoint URI, it MUST contain an XDI endpoint URI collection statement in the form $xdi[<$uri>]<--member-id--> where <--member-id--> is an unordered attribute instance.

    4. Each member of the $xdi[<$uri>] collection MUST have exactly one unique ordering context statement in the form $xdi[<$uri>]<--order-number-->/$ref/$xdi[<$uri>]<--member-id--> where <--order-number--> is an ordered attribute instance (e.g., <@3>) containing a non-negative integer representing the ordering priority and <--member-id--> is an unordered attribute instance (e.g., <!:uuid:3a96e460-7be9-11e2-b92a-0800200c0003>) representing the persistent ID of a URI instance.

XDI discovery for URI types other than http: or https: URIs is currently undefined.

Other Endpoint Types

  1. An XDI authority MAY define another endpoint URI type by defining an XDI dictionary address for the endpoint URI type.
  2. An endpoint URI attribute using this type MUST include a statement identifying the endpoint URI in this type context, i.e., it must apply the same rules as specified above for the XDI endpoint URI type.

Starting XDI Endpoint Rules

Before the discovery protocol begins, the XDI client must determine the starting XDI endpoint. This depends on the type of the first peer root address in the discovery chain.

  1. If the first peer root address in the discovery chain contains a cross-reference to an http: or https: URI, e.g., (https://xdi.example.com/) or (=(https://xdi.example.com/)):

    1. Any percent-encoding of the URI required by the XDI ABNF MUST be unencoded.

    2. The unencoded URI MUST be the URI of the XDI endpoint represented by this peer root address.
  2. If the first peer root address in the discovery chain is not an HTTP/S peer root address, e.g., (+example.name) or ([=]!(urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e0001):

    1. The XDI client SHOULD choose a starting XDI endpoint in a discovery community that the client trusts and for which the URI for the first peer root address is well known.

Discovery Protocol Rules

XDI discovery of endpoint URIs from XDI peer root addresses is analogous to DNS discovery of IP addresses from domain names. The client (or proxy) must "walk the chain" of XDI peer root addresses until it reaches either: a) the authoritative XDI endpoint for the discovery query, b) an XDI endpoint containing a current cached copy of the discovery response.

Direct Discovery

In direct discovery, the XDI client performs all discovery steps itself.

  1. The XDI client MUST perform the first discovery step by sending the starting XDI endpoint an XDI $get message requesting one or more of the desired <$uri> attributes for the first peer root address.

    1. If there is more than one discovery step, the XDI client MUST request at least one XDI endpoint type.
    2. If the client desires the starting XDI endpoint to performing dereferencing of the XDI response message as defined in Equivalence Links, it MUST include the <$deref> parameter set to true.

  2. If the XDI endpoint is authoritative for or has a current cache of the discovery request, it MUST return the requested subgraph.
  3. If there is only one discovery step, the protocol completes.
  4. If the XDI endpoint cannot fulfill the discovery request, it MUST return an error and the protocol completes.
  5. If there are multiple discovery steps, the client MUST select the next peer root address and repeat the discovery process at the XDI endpoint URI discovered for the previous peer root address.
  6. This process MUST be continued until the protocol fails or completes.

Proxy Discovery

In proxy discovery, the XDI client requests the starting XDI endpoint to perform all steps necessary to complete discovery, i.e., to act as an XDI client for all discovery requests other than those for which the XDI endpoint is authoritative.

  1. In the first discovery step above, the XDI client MUST set the <$proxy> parameter in the XDI $get message to true.

  2. If the starting XDI endpoint supports proxy discovery, it MUST carry out the direct discovery steps defined above.
  3. The starting XDI endpoint MAY request proxy discovery from other XDI endpoints.
  4. The starting XDI endpoint MUST return the final response (success or failure) to the XDI client.
  5. The starting XDI endpoint SHOULD cache all intermediate responses.

Examples

Following is an example XDI graph for the XDI root node identified by the peer root address ([=]!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e0001) that contains a set of endpoint URI statements conforming to this specification. Note that it also contains a public link contract that authorizes public discovery of these endpoints.

This example is written in XDI Display Format, with line breaks added for readability. See JSON Serialization Rules for the over-the-wire format.

()/$is$ref/                                                   <== inverse reference of peer root address for this XDI authority
  ([=]!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e0001)
([=]!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e0001)/$ref/        <== direct reference of peer root address for this XDI authority
  ()
[<$uri>]<!1&>/&/                                                <== endpoint URI instance ID 1
  "https://xdi.example.com/5678/"
[<$uri>]<!2>&/&/                                                <== endpoint URI instance ID 2
  "https://xdi2.example.com/5678/"
[<$uri>]<!3>&/&/                                                <== endpoint URI instance ID 3
  "https://www.example.com/5678/"
[<$uri>]<$ttl>&/&/                                            <== time-to-live statement (applies to the entire URI collection)
  2500000
<$uri>/$ref/                                                  <== reference to URI 1 as default endpoint URI
  [<$uri>]<!1>
$xdi<$uri>/$ref/                                              <== reference to URI 1 as default XDI endpoint URI
  [<$uri>]<!1>
$html<$uri>/$ref/                                             <== reference to URI 3 as the default HTML endpoint URI
  [<$uri>]<!3>
$xdi[<$uri>]@0/$ref/                                          <== reference to URI 1 as the highest priority XDI endpoint URI
  [<$uri>]<!1>
$xdi[<$uri>]@1/$ref/                                          <== reference to URI 2 as the second highest priority XDI endpoint URI
  [<$uri>]<!2>
$public$do/$get/                                              <== public link contract to get reference to default endpoint URI
  <$uri>
$public$do/$get/                                              <== public link contract to get default XDI endpoint URI
  $xdi<$uri>
$public$do/$get/                                              <== public link contract to get default HTML endpoint URI
  $html<$uri>
$public$do/$get/                                              <== public link contract to get collection of all endpoint URIs
  [<$uri>]

[TODO - Examples of discovery requests/responses against this graph]


CategoryProposal CategoryDiscovery CategoryHighPriority

XdiDiscovery (last edited 2014-03-28 14:53:22 by dan.blum)