XRD-based Service Discovery

Note: This is a draft specification.

Contents 1 Abstract 2 Terminology 2.1 Definitions and Conventions 3 Overview 3.1 The XRDS Document 3.2 Discovered Services 4 The XRDS document 4.1 Fundamentals 4.2 A simple XRDS document 4.3 Element Definitions 4.3.1 XRDS 4.3.2 XRD 4.3.3 Service 4.3.4 Type 4.3.5 URI 4.3.6 Other elements in a Service element 4.4 Element Priorities 5 XRDS Document Schema 5.1 XRDS Schema 5.2 XRD Schema

Abstract

XRD-based Service Discovery describes the use of an XRDS document to describe and discover services.

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in[RFC2119].

Definitions and Conventions

User:

(AKA "End User" or "Subject".) An entity using a URI as an identifier.

Identifier:

A URI for which services can be discovered via this protocol.

Resource:

A computer software process (or system of processes) that provides one or more services located using this Protocol.

Service:

A particular protocol or operation supported for a given URI, and the information needed to access it.

XRDS Document:

An XML document using the XRDS format which describes services.

Relying Party:

A party responsible for a Relying Party Agent and on whose behalf that Agent acts. A Relying Party is relying on the services provided by a Resource.

Relying Party Agent:

A role to be fulfilled by an agent that uses one or more services discovered as per this specification. The Relying Party Agent discovers the services available from an XRDS document, and may modify its own behavior accordingly.

Overview

The purpose of this specification is to define a method of discovering services from an XRDS document. This specification uses a subset of the full XRDS schema, which is fully defined below. Implementors may wish to refer to the full XRDS schema in XRI Resolution, chapter 3[XRI_Resolution_2.0], though only the subset described in this document is required for compliance with this specification.

The XRDS Document

Extensible Resource Descriptor or XRD is a format defined by the XRI Technical Committee at OASIS. This specification uses only a subset of the full schema, defined in[xrds_schema].

Discovered Services

Services are identified using a well-known service identifier URI. This URI is to be defined by the specification related to the service in question. Services can have associated with them additional metadata such as an endpoint URL at which the service can be used, and an identifier by which the service "knows" the current URI.

The XRDS format allows the use of XML namespaces to extend the service elements with arbitrary additional metadata that is not provided for by the schema defined here.

The XRDS document

Fundamentals

An XRDS document contains a Resource Descriptor, which provides a list of services. These are the services that are available for the URI used to obtain the XRDS document. In the case of some services, additional data is included in the Resource Descriptor for use by the Relying Party Agent in making a request to that service. Such additional data is not specified in this specification but is instead specified in the definition of that service.

The Resource Descriptor also enables preferences for certain services to be expressed through the priority mechanism.

A simple XRDS document

Here is an example of a small XRDS document:

   
  <?xml version="1.0" encoding="UTF-8"?>
  <xrds:XRDS xmlns:xrds="xri://$xrds" xmlns="xri://$xrd*($v*2.0)">
    <XRD>
  
      <Service>
        <Type>http://lid.netmesh.org/sso/2.0</Type>
      </Service>
  
      <Service>
        <Type>http://lid.netmesh.org/sso/1.0</Type>
      </Service>
  
    </XRD>
  </xrds:XRDS>

This document specifies two services.

Note: The XML declaration and the XRDS start-tag appear in all XRDS documents, with the attributes and values shown. The XRD element is the Resource Descriptor. An XRDS document can contain multiple XRD elements; the resolution protocol used to obtain the XRDS document will define which of the XRD elements is to be used.

Element Definitions

These definitions of the elements of a XRDS document are constraints on the XRDS and XRD schemas specified in[xrds_schema]and specify how the elements specified in those schemas are to be interpreted when used with this specification.

All documents to be used with this specification MUST be valid according to the schemas defined in[xrds_schema].

XRDS

The document element of an XRDS document is XRDS, in the XML namespace "xri://$xrds". The XRDS element is a container for one or more XRD elements. The resolution specification used to retrieve the XRDS document will specify which XRD element to use in the event that several are present. This specification only operates on a single nominated XRD element.

XRD

A Resource Descriptor is an XRD element containing a sequence of Service elements. The order of the Service elements is not significant.

Service

A Resource Descriptor MAY contain Service elements, each describing a service.

Note: When an XRDS document contains no Service elements, this indicates that the URL is not intended for use with any service.

Type

Each Service element MAY contain one or more Type elements. A Service element without Type elements is ignored.

Each Type element MUST contain an identifier of some version of some service. This service identifier MUST be a URI.

For each service identified by a Type element there SHOULD be a service specification document. It is RECOMMENDED that the service identifier be a URL that can be used in an ordinary web browser to display that service specification document.

It is RECOMMENDED that each service identifier include an explicit version identifier, in order to assist the evolution of the service in the future.

URI

A Service element MAY contain one or more URI elements.

Each URI element MUST contain a URI that resolves to an endpoint providing the service (or services) specified by the Type element(s) of that Service element.

That URI MUST be a fully-qualified, absolute URI. Relative URLs are not permitted.

If there is more than one URI element, the URIs in those elements MUST be equivalent for the purpose of using the identified service(s). A Relying Party Agent MAY attempt to use any one or all of the URIs.

If one or more URI elements has a priority attribute, a Relying Party Agent MAY use the priority values as specified in[element_priorities]. The order of URI elements is not significant.

The URI element is OPTIONAL. If a URI element is provided, the service determines the meaning of that element and the protocol to use with it.

Other elements in a Service element

This specification does not define any other elements for use inside a Service element. A service may specify additional service-specific elements for use inside a Service element. These elements MUST be in a separate XML namespace. The use of these elements is dictated by the service specification of that service.

A service MAY make use of other elements defined in the full XRDS or XRD schema but not included in this subset. Such services MUST use these elements in a manner consistent with their intended meaning from the XRI Resolution Specification, chapter 3.[XRI_Resolution_2.0]. Such elements are not meaningful in the context of this specification.

Element Priorities

The OPTIONAL priority attribute MAY be used with the Service and URI elements, allowing the document author to specify preferences for the service or endpoint to be used.

A Relying Party Agent MAY ignore priority attributes.

The priority attribute contains a non-negative integer value.

The following processing rules SHOULD be used by a Relying Party Agent that makes use of the priority attribute:

1. The Relying Party Agent SHOULD select the element instance with the lowest numeric value of the priority attribute. For example, an element with priority attribute value of “10” should be selected before an element with a priority attribute value of “11”, and an element with priority attribute value of “11” should be selected before an element with a priority attribute value of “15”. Zero is the highest priority attribute value. Null is the lowest priority attribute value.
2. If no priority attribute is present, the priority of the associated element is Null.
3. If two or more elements share the same priority value, one SHOULD be selected at random.

The priority of Service elements is considered first, and then the priority of URI elements within each service is considered. For example, consider the following document:

   
  <?xml version="1.0" encoding="UTF-8"?>
  <xrds:XRDS xmlns:xrds="xri://$xrds" xmlns="xri://$xrd*($v*2.0)">
    <XRD>
  
      <Service priority="5">
        <URI>http://example.com/example1</URI>
        <URI priority="15">http://example.com/example2</URI>
      </Service>
  
      <Service>
        <URI priority="35">http://example.com/example4</URI>
        <URI priority="25">http://example.com/example3</URI>
      </Service>
  
    </XRD>
  </xrds:XRDS>

When considering Service and URI priority as per the rules above, the following would be the order of preference for the URI values:

• http://example.com/example2
• http://example.com/example1
• http://example.com/example3
• http://example.com/example4

Note that priority values for URI elements are relevant only within a single Service element, not globally.

XRDS Document Schema

The schemas for the subset of XRDS and XRD used by this specification are defined here.

These schemas are adapted from the full schemas specified in[XRI_Resolution_2.0].

XRDS Schema

   <?xml version="1.0" encoding="UTF-8"?>   
   <xs:schema targetNamespace="xri://$xrds" elementFormDefault="qualified"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xrds="xri://$xrds">

      <!-- Utility patterns -->

      <xs:attributeGroup name="otherattribute">
         <xs:anyAttribute namespace="##other" processContents="lax"/>
      </xs:attributeGroup>

      <xs:group name="otherelement">
         <xs:choice>
            <xs:any namespace="##other" processContents="lax"/>
            <xs:any namespace="##local" processContents="lax"/>
         </xs:choice>
      </xs:group>

      <!-- Patterns for elements -->

      <xs:element name="XRDS">
         <xs:complexType>
            <xs:sequence>
               <xs:group ref="xrds:otherelement" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:attributeGroup ref="xrds:otherattribute"/>
         </xs:complexType>
      </xs:element>

   </xs:schema>

XRD Schema

   <?xml version="1.0" encoding="UTF-8"?>
  <xs:schema targetNamespace="xri://$xrd*($v*2.0)"
     elementFormDefault="qualified" 
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
     xmlns:xrd="xri://$xrd*($v*2.0)">

        <!-- Utility patterns -->

        <xs:attributeGroup name="otherattribute">
                <xs:anyAttribute namespace="##other" processContents="lax"/>
        </xs:attributeGroup>

        <xs:group name="otherelement">
                <xs:choice>
                        <xs:any namespace="##other" processContents="lax"/>
                        <xs:any namespace="##local" processContents="lax"/>
                </xs:choice>
        </xs:group>

        <xs:attributeGroup name="priorityAttrGrp">
                <xs:attribute name="priority" type="xs:nonNegativeInteger" use="optional"/>
        </xs:attributeGroup>

        <xs:attributeGroup name="selectionAttrGrp">
                <xs:attribute name="match" use="optional" default="default">
                        <xs:simpleType>
                                <xs:restriction base="xs:string">
                                        <xs:enumeration value="default"/>
                                        <xs:enumeration value="content"/>
                                        <xs:enumeration value="any"/>
                                        <xs:enumeration value="non-null"/>
                                        <xs:enumeration value="null"/>
                                        <xs:enumeration value="none"/>
                                </xs:restriction>
                        </xs:simpleType>
                </xs:attribute>
                <xs:attribute name="select" type="xs:boolean" use="optional" default="false"/>
        </xs:attributeGroup>

        <xs:complexType name="URIPattern">
                <xs:simpleContent>
                        <xs:extension base="xs:anyURI">
                                <xs:attributeGroup ref="xrd:otherattribute"/>
                        </xs:extension>
                </xs:simpleContent>
        </xs:complexType>

        <xs:complexType name="URIPriorityPattern">
                <xs:simpleContent>
                        <xs:extension base="xrd:URIPattern">
                                <xs:attributeGroup ref="xrd:priorityAttrGrp"/>
                        </xs:extension>
                </xs:simpleContent>
        </xs:complexType>

        <xs:complexType name="StringPattern">
                <xs:simpleContent>
                        <xs:extension base="xs:string">
                                <xs:attributeGroup ref="xrd:otherattribute"/>
                        </xs:extension>
                </xs:simpleContent>
        </xs:complexType>

        <xs:complexType name="StringSelectionPattern">
                <xs:simpleContent>
                        <xs:extension base="xrd:StringPattern">
                                <xs:attributeGroup ref="xrd:selectionAttrGrp"/>
                        </xs:extension>
                </xs:simpleContent>
        </xs:complexType>


        <!-- Patterns for elements -->

        <xs:element name="XRD">
                <xs:complexType>
                        <xs:sequence>
                                <xs:element ref="xrd:Service" minOccurs="0" maxOccurs="unbounded"/>
                                <xs:group ref="xrd:otherelement" minOccurs="0" maxOccurs="unbounded"/>
                        </xs:sequence>
                        <xs:attribute name="id" type="xs:ID"/>
                        <xs:attribute name="idref" type="xs:IDREF" use="optional"/>
                        <xs:attribute name="version" type="xs:string" use="optional" fixed="2.0"/>
                        <xs:attributeGroup ref="xrd:otherattribute"/>
                </xs:complexType>
        </xs:element>

        <xs:element name="Service">
                <xs:complexType>
                        <xs:sequence>
                                <xs:element ref="xrd:Type" minOccurs="0" maxOccurs="unbounded"/>
                                <xs:element ref="xrd:URI" minOccurs="0" maxOccurs="unbounded"/>
                                <xs:group ref="xrd:otherelement" minOccurs="0" maxOccurs="unbounded"/>
                        </xs:sequence>
                        <xs:attributeGroup ref="xrd:priorityAttrGrp"/>
                        <xs:attributeGroup ref="xrd:otherattribute"/>
                </xs:complexType>
        </xs:element>

        <xs:element name="Type">
                <xs:complexType>
                        <xs:simpleContent>
                                <xs:extension base="xrd:URIPattern">
                                        <xs:attributeGroup ref="xrd:selectionAttrGrp"/>
                                </xs:extension>
                        </xs:simpleContent>
                </xs:complexType>
        </xs:element>

        <xs:element name="URI">
                <xs:complexType>
                        <xs:simpleContent>
                                <xs:extension base="xrd:URIPattern">
                                        <xs:attributeGroup ref="xrd:priorityAttrGrp"/>
                                        <xs:attribute name="append">
                                                <xs:simpleType>
                                                        <xs:restriction base="xs:string">
                                                                <xs:enumeration value="none"/>
                                                                <xs:enumeration value="local"/>
                                                                <xs:enumeration value="authority"/>
                                                                <xs:enumeration value="path"/>
                                                                <xs:enumeration value="query"/>
                                                                <xs:enumeration value="qxri"/>
                                                        </xs:restriction>
                                                </xs:simpleType>
                                        </xs:attribute>
                                </xs:extension>
                        </xs:simpleContent>
                </xs:complexType>
        </xs:element>

</xs:schema>