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


This page describes the proposed specification for XDI discovery, a lightweight process for using the XDI protocol to discover to the endpoint URI(s) authoritative for an XDI graph or subgraph. The full specification will be published in the XDI Discovery 1.0 specification (see XdiOneSpecs).

Change Log


XDI discovery is a peer-to-peer discovery protocol in which any XDI peer graph can serve as a starting point for discovery. XDI discovery may also be used in a hierarchical model when members of a discovery community agree to start discovery from a known peer root.

Like any federated identifier resolution protocol (e.g., DNS), 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:

  1. A sequence of XDI peer root addresses, OR
  2. On an XDI common address (the portion of an XDI address that does not include a peer root node).

Example Steps for Peer Root Discovery

To do discovery on the XDI address (https://xdi.example.com/)(+!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6)(urn:isbn:0451450523) (ignoring caching):

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

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

Note that if the client requests the complete XDI address and any of the intermediate peer roots is authoritative for the balance of the XDI address, that peer root can fulfill the complete query.

Example Steps for Common Address Discovery

To do discovery on the XDI address +example[#division]@3 (ignoring caching):

  1. Transform +example into the peer root (+example).

  2. Perform discovery on the peer root (+example) to find the XDI endpoint IRI.

  3. Determine if the peer root (+example) is authoritative for +example[#division]@3. If so, discovery is complete. If not:

  4. Transform [#division] into the peer root ([#division]).

  5. Perform discovery at the XDI endpoint IRI for (+example) to find the XDI endpoint URI for the peer root ([#division]).

  6. Determine if the peer root (+example)([#division]) is authoritative for +example[#division]@3. If so, discovery is complete. If not:

  7. Transform @3 into the peer root (@3).

  8. Perform discovery at the XDI endpoint IRI for ([#division]) to find the XDI endpoint URI for the peer root (@3).

  9. The peer root (+example)([#division])(@3) MUST be authoritative for common address +example[#division]@3.

Proxying Other Discovery Protocols

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.

Endpoint IRI Rules

Endpoint URI Attribute Rules

  1. To support XDI Discovery, the XDI root node representing an XDI endpoint MUST use the <$iri> attribute to describe the IRI literals for that endpoint.

  2. The value of a <$iri> attribute singleton MUST be a valid IRI as defined by RFC 3987.

  3. IRI literal values MUST be in the fully normalized form defined by the associated IRI type specification.
  4. To be discoverable with this protocol, an XDI root node:
    1. MUST have an attribute singleton with the address <$iri>.

    2. MAY have an IRI attribute collection with the address [<$iri].

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

Endpoint IRI Attribute Priority Rules

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

  2. Each member of the [<$iri>] collection MUST have exactly one unique ordering statement in the form [<$iri>]<--order-number-->/$ref/[<$iri>]<--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 IRI 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 IRI Time-To-Live (TTL) Attribute Rules

  1. Either the <$iri> attribute singleton or [<$iri>] 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 <$iri> attribute singleton and the [<$iri>] collection contain an IRI time-to-live attribute, the IRI time-to-live attribute on the attribute singleton MUST be authoritative.

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

Endpoint IRI Type Rules

XDI Endpoint URI Types

  1. The default endpoint IRI 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 IRI statement in the form <$xdi><$iri>.

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

    3. If an XDI endpoint has more than one XDI endpoint IRI, it MUST contain an XDI endpoint URI collection statement in the form `<$xdi>[<$iri>] that includes both ordered and unordered members as described above.

Other Endpoint Types

XDI discovery for URI types other than http: or https: IRIs is currently undefined. However it may be defined by any XDI authority simply by defining a new attribute context for the <$iri> attribute.

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: IRI, e.g., (https://xdi.example.com/):

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

    2. The unencoded IRI MUST be the IRI 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 (=!:uuid:9ce739f0-7665-11e2-bcfd-0800200c0002):

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

Discovery Protocol Rules

XDI discovery of endpoint IRIs 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 <$iri> 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 IRI 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.

Common Address Discovery

To discover the authoritative peer root address for an XDI common address:

  1. The first arc in the common address MUST be transformed into a first peer root address by enclosing it in parentheses.
  2. Discovery of the XDI endpoint URI for this first peer root MUST be performed as defined above.
  3. The XDI emdpoint IRI for this first peer root MUST be queried to determine if it is authoritative for the complete common address.
  4. If this peer root node is not authoritative for the complete XDI common address, steps 1-3 are repeated for each additional arc in the common address until an authoritative peer root is found or the protocol fails.


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 JSON format. Note that the XDI common root node is represented by the outermost JSON object and has the XDI address "". All of the $iri attributes in this graph are attributes the common root node of this graph.

    "/$is$ref": [
    "(=!:uuid:f81d4fae-7dec-11d0-a765-00a0c91e0001)": {
        "/$ref": [
    "$public$do": {
        "/$get": [
    "[<$iri>]<@0>": {
        "&": "https://xdi.example.com/f81d4fae-7dec-11d0-a765-00a0c91e0001/"
    "[<$iri>]<@1>": {
        "&": "https://xdi2.example.com/f81d4fae-7dec-11d0-a765-00a0c91e0001/"
    "[<$iri>]<@2>": {
        "&": "https://www.example.com/f81d4fae-7dec-11d0-a765-00a0c91e0001/"
    "<$iri>": {
        "/$ref": [
    "<$html><$iri>": {
        "/$ref": [
    "<$xdi><$iri>": {
        "/$ref": [
    "<$xdi>[<$iri>]<@0>": {
        "$ref": [
    "<$xdi>[<$iri>]<@1>": {
        "/$ref": [

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

CategoryProposal CategoryDiscovery CategoryHighPriority

XdiDiscovery (last edited 2015-06-10 23:36:28 by drummond-xns)