6. Document Structure
The Resource Description Document is an XML-formatted document providing machine-readable descriptions of one or more Resources. Grouping descriptions together is usually done to indicate some common purpose, for example, a collection of services offered by a company or an individual’s online assets and identifiers. XRDS-Simple defines only the most fundamental properties needed for requesting specific representations of the Resource (e.g., specific media types), or for interacting directly with the Resource.
In its simplest form, the Resource Description Document is a list of Resources and their Endpoints grouped together. The document structure consists of three primary elements (listed in reverse hierarchical order): (単純化するため、RDDはResourceとEndpointを一緒にしている)
- Describes a Resource by assigning it a type and media-type, declaring its Endpoints, and provides any additional information relevant to the utilization of the Resource. For example, it describes a photo album, identity provider, or social network account. (タイプ、メディアタイプ、エンドポイントなどでResourceを説明)
- Container element used to group together any number of Service elements, usually with some commonality. For example, a group of identity Resources or a list of sites holding someone’s photos. (Serviceのコンテナ。)
- Container element used to group together any number of XRD elements with elements from other namespaces, usually with some common context. For example, documenting multiple groups of an individual’s social networking accounts, grouped together based on persona (work, home, etc.). (XRDのコンテナ。)
6.1. Declarations and Requirements
The Resource Description Document MUST be a valid XRDS document, contain a single XRDS root element, and define the xri://$xrds namespace. While a valid XRDS-Simple document MAY include any number of XRD elements as well as elements from other namespaces, only XRDS-Simple compliant XRD elements are used in the discovery process. (RDDはXRDSであること。<XRDS/>はひとつだけ。xri://$xrds namespaceを定義すること。ディスカバリプロセスで使われる<XRD/>のみ１RDDに複数存在する。)
XRDS-Simple compliant XRD elements MUST define the xri://$XRD*($v*2.0) namespace as well as include the version attribute with value 2.0. They MUST include a Type child with value xri://$xrds*simple. For the remainder of this specification, XRD elements refer only to XRDS-Simple compliant XRD elements. (<XRD/>は xri://$XRD*($v*2.0)名前空間を定義すること。あと、version = 2.0 。<Type/>を含んでいて、xri://$xrds*simpleであること。)
For example:<XRDS xmlns="xri://$xrds"> <XRD xmlns="xri://$XRD*($v*2.0)" version="2.0"> <Type>xri://$xrds*simple</Type> </XRD> </XRDS>
If an XRDS-Simple document contains more than one XRDS-Simple compliant XRD element, they SHOULD all be assigned unique identifiers using the xml:id attribute. XRDS-Simple only provides a limited selection method of choosing between XRD elements, in which case, if a document contains more than one XRD element, the unique XRD identifier is used to point to a specific element as described in Section 7.1 (XRD Identification). (複数の<XRD/>をもっているんだたったら、xml:idで識別すること。)
The Consumer MAY ignore any other child element of the root XRDS element, including non-compliant XRD elements or elements from other namespaces. The presence of such element MUST NOT alter the way in which the document is processed as defined in this specification. (Consumerは関係ないエレメントを無視してよい。)
6.2. XRD Element
The XRD element is a container used to group together any number of Resources. (<XRD/>は関連するリソースのコンテナです)
The XRD element supports the following attributes:
OPTIONAL with type xs:ID, used to uniquely identify this element within the containing XRDS root element. The attribute is RECOMMENDED if the document contains more than one XRD element and its usage is defined in Section 7.1 (XRD Identification). Note that this attribute is an implicit XML attribute defined in [xml:id] (Marsh, J., Veillard, D., and N. Walsh, “xml:id Version 1.0, World Wide Web Consortium,” .). (xml:idはオプショナル。<XRD/>が複数あったら使ってください。) version REQUIRED with type xs:string and a value of 2.0. (必須。2.0)
The XRD element supports the following child elements:
- 1 or more per XRD element with type xs:anyURI. The Type element describes the nature of the XRD element, how it should be processed, and the context in which it is used. Each XRD element MUST include one and only one Type element with the value xri://$xrds*simple, and MAY include any number of other Type elements. The element MAY also be used to describe the group of Resources included within. (1個以上。<Type/>を使ってXRDを解釈する。xri://$xrds*simpleがきたらXRDS-Simpleということ)
- 0 or 1 per XRD element with type xs:dateTime. The date and time without fractional seconds in UTC "Z" time zone, after which the XRD element MUST NOT be used. If the Resource Description Document was obtained via HTTP, and the HTTP headers specified an expiry time per section 13.2 of [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol — HTTP/1.1,” .), the XRD element MUST NOT be used after the earlier of the two times passes. (最大1個。xs:dataTime 。ミリ秒とか無視したdatetime。 UTC"Z"タイムゾーン。これを過ぎたらそのXRDは期限切れ。)
- 0 or more per XRD element as defined in Section 6.3 (Service Element). (複数。)
6.3. Service Element
The Service element describes a Resource and provides elements to declare its Endpoints and other attributes. The Service element supports the following attributes:
- OPTIONAL with type xs:nonNegativeInteger as defined by Section 6.4 (priority Attribute). Used to set the order of preference between Resources that would otherwise be considered of equal purpose. RECOMMENDED when an XRD element contains multiple Service elements with identical types or media-types association.
The Service element supports the following child elements:
- 0 or more per Service element with type xs:anyURI. The Type element describes the nature of the Resource, how it should be accessed, and the context in which it is selected. The value of the Type element MUST be an absolute URI. Each Service element MUST include at least one of either Type element or MediaType element, but MAY include any number of both.
- 0 or more per Service element with type xs:string. Describes the media-type of the content available at this Resource. The value MUST be a valid media-type as defined in [RFC2046] (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types,” .). Each Service element MUST include at least one of either Type element or MediaType element, but MAY include any number of both.
- 0 or more per Service element with type xs:anyURI. Provides the Endpoint where the Resource can be found and used or retrieved. If no URI element is defined, it is assumed the URI can be obtained by other means not specified in this specification. Supports the OPTIONAL priority attribute as defined by Section 6.4 (priority Attribute), and the OPTIONAL extension attribute simple:httpMethod as defined by Section 6.5.1 (simple:httpMethod Attribute)
- 0 or more per Service element with type xs:anyURI. Provides a standard way to indicate the identifier associated with the Resource at the Endpoint where it is located. The value and meaning of the element is specific to the Resource and its type, and is beyond the scope of this specification. Supports the OPTIONAL priority attribute as defined by Section 6.4 (priority Attribute). For example, this element is useful when the local identifier such as username, is not part of the Endpoint, but is provided as a parameter.
- 0 or more per Service element with type xs:anyURI as defined by Section 6.5.2 (simple:MustSupport Element). Defines requirements the Consumer MUST meet in order to utilize the Resource described.
When selecting between multiple Service elements, the types and media-types of each Resource are used together with the relative priorities, to find the most appropriate Resource.
6.4. priority Attribute
XRDS-Simple allows the Service, URI, and LocalID elements to appear multiple times within the same parent element to provide redundancy, flexibility, or other purposes. When these elements appear more than once within the same parent, Service Providers SHOULD use the priority attribute to prioritize selection of these element instances.
The priority attribute type is xs:nonNegativeInteger – its value MUST be a non-negative integer value. The attribute works in a similar manner to DNS records priority, where the lowest value has the highest priority. This means zero has the highest priority and infinity – represented as the value null – carries the lowest priority. If omitted, the element’s priority value defaults to null, however, instead of omitting the attribute, it is RECOMMENDED to set the priority value to 10. When a Service Provider wishes to indicate a very low priority, it is RECOMMENDED to use a large finite value (100 or higher) rather than explicitly use the value null.
Consumers SHOULD select the element with the highest priority – the lowest numeric value of the priority attribute. In the following example, the URIs decreasing order of priority is 0, 10, 11, 25, and last null and the element with the omitted attribute (equally low).
<Service> <URI priority="10">http://example.com/second</URI> <URI priority="null">http://example.com/lowest</URI> <URI priority="25">http://example.com/fourth</URI> <URI priority="11">http://example.com/third</URI> <URI priority="0">http://example.com/highest</URI> <URI>http://example.com/lowest</URI> </Service>
If two or more instances of the same element type have identical priority attribute values (including the null value), the Consumer SHOULD select one of the instances at random. The Consumer SHOULD NOT choose the first instance that appears in XML document order. This is needed to support the Service Provider’s redundancy or load balancing intentions.
The element selected according to these rules is referred to as the highest priority element. If this element is subsequently disqualified from the set of qualified elements, the Consumer SHOULD attempt to select the next highest priority element. This process SHOULD be continued for all other instances of the qualified elements until success is achieved or all instances are exhausted.
6.5. Non-XRDS Elements and Attributes
XRDS-Simple introduces a few new elements and attributes not defined in XRDS which are needed for an easier adoption of the format with HTTP Resources. In order to maintain full compatibility, these are defined under a separate namespace, and do not change the discovery workflow.
To use the extensions the http://xrds-simple.net/core/1.0 namespace MUST be defined. The namespace alias simple is shown as an example, and can be set to any valid XML namespace alias. For example:
<XRDS xmlns="xri://$xrds"> <XRD xmlns:simple="http://xrds-simple.net/core/1.0" xmlns="xri://$XRD*($v*2.0)" version="2.0"> <Type>xri://$xrds*simple</Type> <Service> <Type>http://example.net/some_type</Type> <URI simple:httpMethod="POST">http://example.com/resource</URI> </Service> </XRD> </XRDS>
6.5.1. simple:httpMethod Attribute
The simple:httpMethod attribute provides the HTTP method needed to request the Resource provided at the Endpoint specified by the URI element. The attribute value type is xs:string, is case-sensitive, and is any accepted HTTP verb by the provider of the Resource (for example, the HTTP methods defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol — HTTP/1.1,” .) section 9). If omitted, the method is assumed to be specified by other means, such as implicitly defined by the type or media-type of the Resource.
6.5.2. simple:MustSupport Element
The simple:MustSupport element indicates that a Resource has certain requirements that MUST be supported by the Consumer in order to be utilized. Similar to the Type element, the simple:MustSupport element uses namespace URIs to describe the Resource. It instructs Consumer that the Resource requires some additional understanding beyond matching some of the types or media-types. Consumers SHOULD always check for unknown simple:MustSupport element values before selecting or utilizing the Resource description.
The element can be considered a sub-type, but carries the additional functionality of instructing the Consumer of a hard requirement. Generally, Resources can have many types and media-types, and are selected by ensuring the desired types and media-types are present, while ignoring others of no value or unknown. simple:MustSupport provides a way in which parsers can check to see if they are at all capable of interacting with a Resource, even if they are familiar with some of its types and media-types.
In some cases, an overlap exists between the Type and simple:MustSupport elements. In those cases, both elements SHOULD be included to maintain consistency with existing practices. For example, OpenID uses Type elements to document both the type of the Endpoint, as well as the OpenID extensions it supports. If one of these extensions is REQUIRED, its namespace identifier SHOULD appear in both a Type and simple:MustSupport elements, within the same Service element.
While this element can be defined in a seperate specification, it is included as part of XRDS-Simple to establish a mechanism for Consumers to detect when they are unable to utilize a discovered Resource.
6.6. Extension and Deviation
XRDS-Simple inherits the extendibility of XRDS but places strict limitations on the ability to extend the format. Any extension used MUST NOT define or cause any deviation from the meaning and workflow defined in this specification with regard to the discovery process. Extensions MUST be restricted to add only Resource-specific descriptions.
This is particularly true to XRDS elements and attributes not explicitly listed and allowed in this specification, as they might significantly alter the way in which a document is parsed and Endpoints selected. For a document to legally declare itself as XRDS-Simple, it must be fully compatible with any compliant XRDS-Simple parser, as well as any compliant XRDS parser.
XRDS-Simple parsers SHOULD look for the existence of a valid XRDS-Simple declaration before parsing any XRDS documents, as they MAY otherwise produce incorrect results. It is also RECOMMENDED that XRDS-Simple parsers attempting to parse XRDS documents, include logic to check for elements excluded from XRDS-Simple which are known to significantly alter the discovery process. This includes but not limited to the Redirect and Ref elements, and the match and select attributes, defined in [XRI Resolution 2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0,” .).