From Yadis

The key words and word pairs, "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL", in this document are to be interpreted as described in RFC 2119.

Back to Yadis Protocol.

7. The Yadis Resource Descriptor

This is Clause 7 of Yadis Specification Version 0.8

7.1 Overview of the Yadis Resource Descriptor

Note: We considered providing both a text and an XML-based format, in order to make it as easy as possible for Relying Parties to use service information available through Yadis IDs. However, we came to the conclusion that requiring both a text and an XML based format provides only small additional value, while using an XML based format enables use of standard parsing tools.

We have chosen a simple, extensible XML document called an Extensible Resource Descriptor (XRD). The format of XRD documents is being specified by the XRI Technical Committee of OASIS (see XRI Resolution 2.0 specification).

The Yadis Resource Descriptor provides a list of identifiers of Services. These are the Services that know the User identified by the Yadis ID used to obtain the Yadis Resource Descriptor. In the case of some Services, additional data is included for use by the Relying Party in making a request to the Service.

The Resource Descriptor also enables the User to specify which of the Services it prefers be used.

7.2 A simple Yadis Resource Descriptor

Here is an example of a small Yadis Resource Descriptor:

 
 
   
 
     
       http://lid.netmesh.org/sso/2.0b5
     
 
     
       http://lid.netmesh.org/sso/1.0
     
 
   
 

This Resource Descriptor specifies two services.

7.2.1 XRD

A Yadis Resource Descriptor document consists of an XRD container (the XRDS element) with a Yadis Resource Descriptor (the XRD element). A resource descriptor contains a sequence of service descriptions. Each service description is a Service element.

The order of the service descriptions is not significant.

A Yadis Resource Descriptor document MUST include at least one XRD element.

7.2.2 Service

An XRD element in a Yadis Resource Descriptor MAY contain one or more Service elements describing a Yadis service.

Each Yadis Service element consists of a Type element plus optional elements.

Note: We encourage identity protocol designers to be brief.

Note: A Yadis Resource Descriptor that has no Service elements describing a Yadis service is permitted.

7.2.3 Type

Each Yadis Service element MUST contain at least one Type element.

Each Type element MUST contain an identifier of some version of some service. This service identifier MUST be a URI or XRI. It MUST identify a single version of that service.

For each service identified by a Type element there SHOULD be a service specification document. It is RECOMMENDED that the service identifier be resolvable to a locator for that service specification document.

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

7.2.4 XRDS

A Yadis Resource Descriptor consists of a single XRDS element. It begins with the opening of an XRDS element tag and two XML namespace declarations:

  
  
          
This is followed by:
          
declarations of any other XML namespaces that will be used,
          
  >

          
to close the XRDS element tag,
          
an XRD element with Service elements
          
and
          
  

          
to end the XRDS element.
          

            [edit]
          

          
7.3 Other parts of a Yadis Resource Descriptor
          
Here is an example of a larger Yadis Resource Descriptor:
          
 
 
   
 
     
       http://openid.net/signon/1.0
       http://www.myopenid.com/server
       http://jimmy.myopenid.com/
     
 
     
       http://openid.net/signon/1.0
       http://www.example.com/openid
       
         http://users.example.com/james.s
       
     
 
     
       http://openid.net/signon/1.0
       http://www.livejournal.com/openid/server.bml
       
         http://www.livejournal.com/users/jimmy/
       
     
 
     
       http://lid.netmesh.org/sso/2.0b5
     
 
     
       http://lid.netmesh.org/sso/1.0
     
 
   
 

          

            [edit]
          

          
7.3.1 URI element
          
A Yadis Service element MAY contain one or more URI elements. Each URI element specifies a resource that will provide the service.
          
Each URI element MUST contain a URI that identifies a resource providing the service (or services) specified by the Type element(s) of that Service element.
          
That URI MUST be an absolute URL, not a relative URL, URL reference, or other URI.
          
Note: It is our intention that this element may contain any URI or may contain an IRI, as specified by [RFC 3987]. This will be specified in a later version of this specification.
          
If a Relying Party chooses a Service element that contains one or more URI elements, that Relying Party MUST recognize and use a URI element of that Service element.
          
If there is more than one URI element, the URIs in those elements MUST be equivalent for the purpose of using the service. A Relying Party MAY attempt to use any one or all of the URIs.
          
If one or more URI elements has a priority attribute, a Relying Party MAY use the priority values as specified in Clause 2.4.3 of the XRI Resolution 2.0 specification.
          
The order of URI elements is not significant.
          
The URI element is OPTIONAL.
          

            [edit]
          

          
7.3.2 Priority attribute
          
The OPTIONAL priority attribute of the Service element allows the User to specify preferences for the Service to be used. The example above indicates that the User prefers the OpenID protocol using the server, http://www.myopenid.com/server, and that the last choice is LID version 1.0.
          
In keeping with the goal of ease of implementation, a Relying Party MAY ignore the priority attribute. A Relying Party that recognizes and uses the priority attribute in one or more Service elements MUST follow the specification of priority attributes in Clause 2.4.3 of the XRI Resolution 2.0 specification.
          

            [edit]
          

          
7.3.3 Other elements in a Service element
          
Yadis does not specify any other elements for a Service element. A Service MAY define and use other elements.
          
Note: This allows a Service element to indicate things that are specific to that service. As examples, the OpenID specification defines the optional Delegate element, which specifies a URL by which the OpenID server knows the User.
          
If a Relying Party intends to chose a particular service, that Relying Party MUST recognize and use all elements specified by a service specification for inclusion in a Service element for that service.
          
A Relying Party MAY ignore all other elements in a Service element. A Relying Party MAY recognize and use any elements in a Service element, which are specified by the XRD schema.
          
A Relying Party using a Yadis Resource Descriptor MAY ignore any element of that document except for the elements specified here and any elements specified by a service specification.
          
Any Relying Party not using a particular service MAY ignore any element of Yadis Resource Descriptor that is specified by the service specification of that service. The use of elements specified by a service specification is determined by that service specification.
          

            [edit]
          

          
7.3.4 Other elements in an XRD
          
An XRD in a Yadis Resource Descriptor document may contain Service elements that do not identify Yadis services. A Relying Party MAY ignore all such Service elements.
          
A Yadis service MUST NOT require the use of a Service element that does not identify that Yadis service in a Type element of that Service element.
          
A Relying Party MAY ignore all other elements in an XRD element.
          
A Relying Party MAY recognize and use any elements in an XRD element, which are specified by the XRD schema.
          
A Yadis service MUST NOT require the use of any elements of an XRD other than the Service elements that identify the services of that Yadis Service.
          

            [edit]
          

          
7.3.5 Other services
          
The examples so far have been for single sign-on services, the scenario described in Section 4.1. A Yadis service MAY offer other services. A Yadis service is NOT REQUIRED to offer a single sign-on service.
          
For example, the following Resource Descriptor specifies a number of LID services available at the resource identified by the users Yadis ID:
          
 
 
   
 
     
       http://lid.netmesh.org/sso/2.0b5
     
 
     
       http://lid.netmesh.org/sso/1.0
     
 
     
       http://lid.netmesh.org/post/sender/2.0b5
     
 
     
       http://lid.netmesh.org/post/receiver/2.0b5
     
 
     
       http://lid.netmesh.org/relying-party/2.0b5
     
 
     
       http://lid.netmesh.org/traversal/2.0b5
     
 
     
       http://lid.netmesh.org/format-negotiation/2.0b5
     
 
   
 

          

            [edit]
          

          
7.3.6 Other XRDs and other elements in the XRDS
          
The XRDS schema permits more than one XRD in an XRDS and permits other elements in an XRDS, in addition to XRD elements. Such documents are valid Yadis Resource Descriptors.
          
A Relying Party MUST examine the last of the XRD elements in an XRDS returned in response to a request for a Yadis Resource Descriptor document.
          
A Relying Party MAY ignore all other elements in an XRDS.
          

            [edit]
          

          
7.4 Schema for the Yadis Resource Descriptor
          
The schemas of the Yadis Resource Descriptor document are the XRDS and XRD schemas contained in Appendix A, XML Schema for XRDS and XRD, of working draft 9 of the XRI Resolution 2.0 specification.
          
A Yadis Resource Descriptor document MUST conform to the XRDS schema. A Yadis Resource Descriptor is an XRD element; it MUST be contained in an XRDS element and MUST conform to the XRD schema.
          
Until such time as those schemas may be adopted by OASIS, we copy them here.
          

            [edit]
          

          
XRDS Schema
          
     
  http://www.w3.org/2001/XMLSchema"
  xmlns:xrds="xri://$xrds">
     
        
     
     
        
           
           
        
     
     
        
           
              
           
           
        
     
  

          


          

            [edit]
          

          
XRD Schema
          
  
  http://www.w3.org/2001/XMLSchema"
  xmlns:xrd="xri://$xrd*($v*2.0)"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
     
        
     
     
        
           
           
        
     
     
        
           
              
           
        
     
     
        
           
              
           
        
     
     
        
           
              
              
              
              
              
              
              
           
           
           
           
        
     
     
     
        
           
              
                 
              
           
        
     
     
     
     
     
        
           
              
              
              
              
              
              
           
           
        
     
     
     
     
     
     
     
     
  

          


          

            [edit]
          

          
Possible Future Schemas
          
We intend to modify the Yadis specification to reference subsequent working drafts and committee drafts of the XRI Resolution 2.0 specification as they are published, and to use the XRDS and XRD schemas from those drafts.
          
Should the XRDS and XRD schemas not be adopted by OASIS, we intend to include a smaller schema in the Yadis specification, limited to a subset of the elements specified in XRI-resolution working draft 9 or a later working or committee draft we have followed.
          

            Retrieved from "https://yadis.org/wiki/Yadis_Resource_Descriptor_Draft_0.8"