In respose to the discussion recently about modularizing the discovery
part of OpenID Authentication 2.0, I've put together a possible first
draft of a specification for doing service discovery using XRDS.
This document is really just the XRDS-related parts of Yadis but
refactored slightly.
In particular:
* XRI Resolution 2.0 is no longer required reading for implementors.
Instead, it defines its own proper subset of XRDS/XRD which is
completely defined within this document.
* The various sentences referring to "authentication services" and
specifically to OpenID, LID, etc. have been rewritten or removed.
My intention here is that the remaining parts of Yadis that are not
included in this new specification will become "XRDS Discovery for HTTP
and HTTPS URLs".
It'd be cool if it could be restructured in such a way that XRI
Resolution 2.0 becomes only an informative rather than a normative
reference, but as it currently stands it's used in conjunction with a
couple of MUST clauses and therefore needs to be normative.
(I was going to put a more readable version of this on the wiki as well,
but sadly it seems that OpenID login isn't working today... for me, at
least.)
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- ?xml-stylesheet type='text/css' href='style.css' ? -->
<!-- ***** File Inclusion ***** -->
<!-- The parameter value is the name of the file to be included which can also be a URI.
In the case of local files the XML_LIBRARY environment variable provides a search
path of directories in which the file may be located. See section 4.1.2 of README -->
<!-- include="n/a" -->
<!-- ***** Rigor Control ***** -->
<!-- Try to enforce the ID-nits conventions and DTD validity -->
<?rfc strict="yes" ?>
<!-- ***** Rendering Control ***** -->
<!-- Put the famous header block on the first page -->
<?rfc topblock="yes" ?>
<!-- Include boilerplate from Section 10.4(d) of [1] (Bradner, S., "The Internet Standards
Process - Revision 3," October 1996.) -->
<?rfc iprnotified="no" ?>
<!-- Use anchors as symbolic tags rather than numbers for references -->
<?rfc symrefs="yes" ?>
<!-- Sort references according to symbolic tags - irrelevant if symrefs="no" -->
<?rfc sortrefs="yes" ?>
<!-- Items useful for reviewing document -->
<!-- Render <cref> information -->
<?rfc comments="no" ?>
<!-- If comments is "yes", then render comments inline; otherwise render them in an
"Editorial Comments" section -->
<?rfc inline="no" ?>
<!-- Insert editing marks for ease of discussing draft versions.
Editing marks are strings such as <29> printed at the beginning of the blank line before
each paragrpah of text. -->
<?rfc editing="no" ?>
<!-- Items useful when using xml2rfc to produce technical documents other than RFCs and I-Ds -->
<!-- Produce a private memo rather than an RFC or Internet-Draft.
The value of the PI is used as the title of the document.
Omits the topblock and standard boiler plate when . -->
<?rfc private="Draft" ?>
<!-- Override the center footer string -->
<?rfc footer="" ?>
<!-- Override the leftmost header string -->
<?rfc header="" ?>
<!-- ***** Table of Contents Control ***** -->
<!-- Generate a table-of-contents -->
<?rfc toc="yes" ?>
<!-- Control whether the word "Appendix" appears in the table of contents. -->
<?rfc tocappendix="yes" ?>
<!-- If toc is "yes", then this determines the depth of the table of contents. -->
<?rfc tocdepth="3" ?>
<!-- If toc is "yes", then setting this to "yes" will indent subsections in
the table-of-contents. -->
<?rfc tocindent="yes" ?>
<!-- If toc is "yes", then setting this to "no" will make it a little less compact. -->
<?rfc tocompact="yes" ?>
<!-- Affects horizontal spacing in the table-of-content. -->
<?rfc tocnarrow="yes" ?>
<!-- ***** Format Control ***** -->
<!-- Automatically force page breaks to avoid widows and orphans (not perfect). -->
<?rfc autobreaks="yes" ?>
<!-- Put two spaces instead of one after each colon (":") in txt or nroff files. -->
<?rfc colonspace="no" ?>
<!-- When producing a txt/nroff file, try to conserve vertical whitespace
(the default value was "no" up to v1.30; from v1.31 the default is the current value
of the rfcedstyle PI).
Will default to (rfcedstyle) in future. -->
<?rfc compact="no" ?>
<!-- If compact is "yes", then you can make things a little less compact by setting this
to "no" (the default value is the current value of the compact PI). -->
<?rfc subcompact="no" ?>
<!-- An integer hint indicating how many contiguous lines are needed at this point in
the output.
Can appear as many times as necessary in the source. -->
<!-- needLines="0" -->
<!-- ***** HTML Specials ***** -->
<!-- When producing a html file, use the image in this file. -->
<?rfc background="" ?>
<!-- Automatically replaces input sequences such as |*text| by,
e.g., <strong>text</strong> in html output. -->
<?rfc emoticonic="no" ?>
<!-- Generate mailto: URL, as appropriate. -->
<?rfc linkmailto="yes" ?>
<!-- When producing a html file, produce multiple files for a slide show. -->
<?rfc slides="no" ?>
<!-- When producing a html file, use the <object> html element with inner replacement content
instead of the <img> html element, when a source xml element includes an src attribute. -->
<?rfc useobject="no" ?>
<!-- ***** Debugging ***** -->
<!-- Value is a string like "35:file.xml" or just "35" (file name then defaults to the
containing file's real name or to the latest linefile specification that changed it) that
will be used to override xml2rfc's reckoning of the current input position
(right after this PI) for warning and error reporting purposes
(line numbers are 1-based)" -->
<!-- linefile="n/a" -->
<!-- During processing pass 2, print the value to standard output at that point
in processing" -->
<!-- typeout="n/a" -->
<rfc category="std" ipr="none" docName="discovery.xml">
<front>
<title>XRD-based Service Discovery - Draft 1</title>
<author fullname="OpenID Community">
<address>
<email>specs@openid.net</email>
</address>
</author>
<author initials="J." surname="Miller" fullname="Joaquin Miller" />
<date month="March" year="2007"/>
<abstract>
<t>
XRD-based Service Discovery describes the use of an XRDS document
to describe and discover services.
</t>
</abstract>
</front>
<middle>
<section title="Terminology">
<t>
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 <xref target="RFC2119"/>.
</t>
<section title="Definitions and Conventions">
<list style="hanging">
<t hangText="User:">
(AKA "End User" or "Subject".) An entity
using a URI as an identifier.
</t>
<t hangText="Identifier:">
A URI for which services can be discovered via this protocol.
</t>
<t hangText="Resource:">
A computer software process (or system of processes) that provides one or more services located using this Protocol.
</t>
<t hangText="Service:">
A particular protocol or operation supported for a given URI, and the information needed to access it.
</t>
<t hangText="XRDS Document:">
An XML document using the XRDS format which describes services.
</t>
<t hangText="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.
</t>
<t hangText="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.
</t>
</list>
</section>
</section>
<section title="Overview">
<t>
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 <xref target="XRI_Resolution_2.0" />, though only
the subset described in this document is required for compliance with this specification.
</t>
<section title="The XRDS Document">
<t>
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 <xref target="xrds_schema" />.
</t>
</section>
<section title="Discovered Services">
<t>
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.
</t>
<t>
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.
</t>
</section>
</section>
<section title="The XRDS document">
<section title="Fundamentals">
<t>
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.
</t>
<t>The Resource Descriptor also enables preferences for certain services to be expressed through the priority mechanism.</t>
</section>
<section title="A simple XRDS document">
<t>Here is an example of a small XRDS document:</t>
<artwork><![CDATA[
<?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>
]]></artwork>
<t>This document specifies two services.</t>
<t>
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.
</t>
</section>
<section title="Element Definitions">
<t>
These definitions of the elements of a XRDS document
are constraints on the XRDS and XRD schemas specified in <xref target="xrds_schema" /> and
specify how the elements specified in those schemas are to be interpreted
when used with this specification.
</t>
<t>All documents to be used with this specification MUST be valid according to the schemas defined in <xref target="xrds_schema" />.</t>
<section title="XRDS">
<t>
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.
</t>
</section>
<section title="XRD">
<t>
A Resource Descriptor is an XRD element containing a sequence of Service elements.
The order of the Service elements is not significant.
</t>
</section>
<section title="Service">
<t>A Resource Descriptor MAY contain Service elements, each describing a service.</t>
<t>Note: When an XRDS document contains no Service elements, this indicates that the URL is not intended for use with any service.</t>
</section>
<section title="Type">
<t>Each Service element MAY contain one or more Type elements. A Service element without Type elements is ignored.</t>
<t>Each Type element MUST contain an identifier of some version of some service. This service identifier MUST be a URI.</t>
<t>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.</t>
<t>It is RECOMMENDED that each service identifier include an explicit version identifier, in order to assist the evolution of the service in the future.</t>
</section>
<section title="URI">
<t>A Service element MAY contain one or more URI elements.</t>
<t>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.</t>
<t>That URI MUST be a fully-qualified, absolute URI. Relative URLs are not permitted.</t>
<t>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.</t>
<t>If one or more URI elements has a priority attribute, a Relying Party Agent MAY use the priority values as specified in <xref target="element_priorities" />. The order of URI elements is not significant.</t>
<t>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.</t>
</section>
<section title="Other elements in a Service element">
<t>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.</t>
<t>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. <xref target="XRI_Resolution_2.0" />. Such elements are not meaningful in the context of this specification.</t>
</section>
</section>
<section title="Element Priorities" anchor="element_priorities">
<t>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.</t>
<t>A Relying Party Agent MAY ignore priority attributes.</t>
<t>The priority attribute contains a non-negative integer value.</t>
<t>The following processing rules SHOULD be used by a Relying Party Agent that makes use of the priority attribute:</t>
<list style="numbers">
<t>
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.
</t>
<t>If no priority attribute is present, the priority of the associated element is Null.</t>
<t>If two or more elements share the same priority value, one SHOULD be selected at random.</t>
</list>
<t>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:</t>
<artwork><![CDATA[
<?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>
]]></artwork>
<t>When considering Service and URI priority as per the rules above, the following
would be the order of preference for the URI values:</t>
<list style="symbols">
<t>http://example.com/example2</t>
<t>http://example.com/example1</t>
<t>http://example.com/example3</t>
<t>http://example.com/example4</t>
</list>
<t>Note that priority values for URI elements are relevant only within a single Service element, not globally.</t>
</section>
</section>
</middle>
<back>
<appendix title="XRDS Document Schema" anchor="xrds_schema">
<t>The schemas for the subset of XRDS and XRD used by this specification are defined here.</t>
<t>These schemas are adapted from the full schemas specified in <xref target="XRI_Resolution_2.0" />.</t>
<section title="XRDS Schema">
<artwork><![CDATA[<?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>]]></artwork>
</section>
<section title="XRD Schema">
<artwork><![CDATA[<?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>
]]></artwork>
</section>
</appendix>
<references title="Normative References">
<reference anchor='RFC2119'>
<front>
<title abbrev='RFC Key Words'>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='Scott Bradner'>
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street>
</postal>
<phone>- +1 617 495 3864</phone>
<email>[EMAIL PROTECTED]</email></address></author>
<date year='1997' month='March' />
<area>General</area>
<keyword>keyword</keyword>
<abstract>
<t>
In many standards track documents several words are used
to signify the requirements in the specification. These
words are often capitalized. This document defines
these words as they should be interpreted in IETF
documents. Authors who follow these guidelines should
incorporate this phrase near the beginning of their
document:
<list>
<t>
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 RFC
2119.
</t></list></t>
<t>
Note that the force of these words is modified by the
requirement level of the document in which they are
used.
</t>
</abstract></front>
<seriesInfo name='BCP' value='14' />
<seriesInfo name='RFC' value='2119' />
<format type='TXT' octets='4723' target='ftp://ftp.isi.edu/in-notes/rfc2119.txt' />
<format type='HTML' octets='16553' target='http://xml.resource.org/public/rfc/html/rfc2119.html' />
<format type='XML' octets='5703' target='http://xml.resource.org/public/rfc/xml/rfc2119.xml' />
</reference>
<reference anchor="XRI_Resolution_2.0"
target="http://www.oasis-open.org/committees/download.php/17293"; >
<front>
<title>Extensible Resource Identifier (XRI) Resolution V2.0
- Working Draft 10</title>
<author initials='G.W' surname='Wachob' fullname="Gabe Wachob">
<organization>Visa International</organization>
</author>
<author initials='D.R' surname='Reed' fullname="Drummond Reed">
<organization>Cordance</organization>
</author>
<author initials='L.C' surname='Chasen' fullname="Les Chasen">
<organization>NeuStar</organization>
</author>
<author initials='W.T' surname='Tan' fullname="William Tan">
<organization>NeuStar</organization>
</author>
<author initials='S.C' surname='Churchill' fullname="Steve Churchill">
<organization>XDI.ORG</organization>
</author>
</front>
<format type="PDF" target=
"http://www.oasis-open.org/committees/download.php/17293"; />
</reference>
</references>
</back>
</rfc>
_______________________________________________
specs mailing list
specs@openid.net
http://openid.net/mailman/listinfo/specs
