Network Working Group J. Snell Internet-Draft March 10, 2006 Expires: September 11, 2006 Feed Rank draft-snell-atompub-feed-index-07.txt Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on September 11, 2006. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document defines a mechanism for numerically ranking entries within a syndication feed. Snell Expires September 11, 2006 [Page 1] Internet-Draft Feed Rank March 2006 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 3. Ranking Domains and Schemes . . . . . . . . . . . . . . . . . 3 3.1. The 'r:scheme' element . . . . . . . . . . . . . . . . . . 4 3.2. The 'r:rank' element . . . . . . . . . . . . . . . . . . . 5 4. Ranking Domain Scope . . . . . . . . . . . . . . . . . . . . . 5 4.1. The Document Ranking Domain and xml:base . . . . . . . . . 7 5. Ranking Domain and Scheme Identifiers . . . . . . . . . . . . 8 6. Processing Rankings . . . . . . . . . . . . . . . . . . . . . 8 7. Default Ranking Scheme . . . . . . . . . . . . . . . . . . . . 8 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 Intellectual Property and Copyright Statements . . . . . . . . . . 11 Snell Expires September 11, 2006 [Page 2] Internet-Draft Feed Rank March 2006 1. Introduction In syndication document formats such as Atom [RFC4287] and RSS, the order of entries as presented in the list is typically insignificant. This presents a challenge when the list of entries is intended to represent an ordered or ranked set. This document specifies a mechanism that allows feed publishers to establish numeric rankings for entries within a feed to be used as a means of organizing and sorting those entries. Although this document refers to Atom normatively, the mechanism described herein can be used with similar syndication formats, such as the various flavors of RSS. 2. Notational Conventions 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 BCP 14, [RFC2119]. In this specification, "entry" refers to an atom:entry element or similar construct from other syndication formats (e.g., RSS) that are contained within a feed. In this specification, "feed" refers to a logical collection of entries potentially spanning multiple Atom Feed Documents sharing the same atom:id element value. In this specification, "head section" refers to the children of a feed document's document-wide metadata container; e.g., the child elements of the atom:feed element in an Atom Feed Document or the children of the RSS 'channel' element. This specification uses XML Namespaces [W3C.REC-xml-names-19990114] to uniquely identify XML element names. It uses the following namespace prefix for the indicated namespace URI; "r": "http://purl.org/syndication/index/1.0" This specification uses terms from the XML Infoset [W3C.REC-xml- infoset-20040204]. However, this specification uses a shorthand; the phrase "Information Item" is omitted when naming Element Information Items. Therefore, when this specification uses the term "element," it is referring to an Element Information Item in Infoset terms. 3. Ranking Domains and Schemes A 'Ranking Domain' is a uniquely identifiable logical collection of entries containing numeric ranking values. Snell Expires September 11, 2006 [Page 3] Internet-Draft Feed Rank March 2006 'Ranking Schemes' identify the specific rules for how the numeric ranking values within a 'Ranking Domain' are to be interpreted. 3.1. The 'r:scheme' element Ranking Schemes are defined using the r:scheme element. rankingScheme = element r:scheme { atomCommonAttributes, attribute name { IRI }?, attribute label { text }?, attribute significance { 'ascending' | 'descending' }?, attribute precision { nonNegativeInteger }?, attribute minimum { decimal }?, attribute maximum { decimal }? } o The 'name' attribute provides a universally unique identifier for the scheme in the form of an absolute IRI. o The 'label' attribute specifies a language-sensitive, human readable label for the scheme. o The 'significance' attribute indicates how implementations are to interpret the significance of an entries numeric ranking value. A value of 'descending' indicates that the significance of the rank descends as the numeric ranking value increases. A value of 'ascending' indicates that the significance of the rank increases as the numeric ranking value increases. If not specified, the significance is considered to be 'ascending'. o The 'precision' attribute specifies the level of precision to be applied to the value of the numeric ranking value. The value is expressed as a non-negative integer. If not specified the value is considered to be indeterminate (e.g., the number 2.0 is not distinct from the number 2.00). Ranking schemes that are based on fractional numeric ranking values SHOULD specify a precision. o The 'minumum' attribute specifies the lowest possible numeric ranking value (inclusive). If not specified, the minimum value is considered to be 0. o The 'maximum' attribute specifies the highest possible numeric ranking value (inclusive). If not specified, no maximum value is considered to apply. An Atom feed element MAY contain any number of r:scheme elements. A Feed MUST NOT contain more than one r:scheme element with the same name. Snell Expires September 11, 2006 [Page 4] Internet-Draft Feed Rank March 2006 ... ... 3.2. The 'r:rank' element Entries within a feed MAY contain zero or more r:rank elements specifing a numeric ranking value within a given Ranking Domain. An entry MUST NOT contain more than one r:rank element with the same combination of domain and scheme attribute values. rankingValue = element r:rank { atomCommonAttributes, attribute domain {IRI}?, attribute scheme {IRI}?, attribute label { text }?, (decimal} } The 'domain' attribute identifies the Ranking Domain. See "Ranking Domain Scope" for details. The 'scheme' attribute identifies the Ranking Scheme. If not specified, the scheme is assumed to be the Default Ranking Scheme. The 'label' attribute provides a language-sensitive, human readable label for the ranking value. The value of the r:rank is a decimal value conforming to the XML Schema decimal data type [W3C.REC-xmlschema-2-20041028]. The value MUST NOT contain any leading or trailing whitespace. 3.5 4. Ranking Domain Scope Snell Expires September 11, 2006 [Page 5] Internet-Draft Feed Rank March 2006 Ranking Domain's provide a logical mechanism used to associate a numerically ranked set of resources. Ranking Domains are identified by absolute or relative IRI's. Ranking Domains fall into one of three scopes: o Feed Scope (known as the "Feed Ranking Domain") o Document Scope (known as the "Document Ranking Domain") o Domain Scope Numeric ranking values that do not specify a domain attribute are associated with the Feed Ranking Domain. The IRI identity of the Feed Ranking Domain is the same as the containing feed element's atom:id element. A numeric ranking associated with the Feed Ranking Domain 3.5 The set of entries contained within the Feed Ranking Domain is limited to the set of entries contained within the feed. Numeric rankings that specify a domain equal or equivalent to the Feed Document's Base URI are associated with the Document Ranking Domain. The IRI identity of the Document Ranking Domain is the normalized form of the in scope Base URI. A numeric ranking associated with the Feed Ranking Domain 3.5 The set of entries contained within the Document Ranking Domain is limited to the set entries contained within the Document identified by the Base URI. Numeric ranking values that specify any IRI value other than the Base URI of the containing document are associated with a Domain Scope. A numeric ranking associated with the Feed Ranking Domain 3.5 Snell Expires September 11, 2006 [Page 6] Internet-Draft Feed Rank March 2006 Domain Scoped SHOULD be considered to be open sets consistings of entries from any number of feeds. 4.1. The Document Ranking Domain and xml:base When specifying or processing rankings in the Document Ranking Domain, implementors need to be aware of the possible sides effect of using the xml:base attribute. For instance, in the example, ... tag:example.org,2005:1 3.5 ... tag:example.com,2005:1 3.5 ... tag:example.com,2005:2 3.5 ... The three entries contained by the feed exist in two separate Document Ranking Domains, each respectively identified by the URI's "http://example.org/feed.xml" and "http://example.com/anotherfeed.xml". It is posible for the set of entries within a Document Ranking Domain to span multiple Atom Feed Documents if those documents share the same Base URI as specified by their respective xml:base attributes. Snell Expires September 11, 2006 [Page 7] Internet-Draft Feed Rank March 2006 5. Ranking Domain and Scheme Identifiers The IRI's identifying Ranking Domains and Ranking Schemes are subject to the same construction and comparison rules as the atom:id element. Comparison's of domain and scheme identifiers MUST be performed on a case-sensitive, character-by-character basis solely on the IRI character strings and MUST NOT rely on dereferencing the IRI's or URI's mapped from them. 6. Processing Rankings Processing a Ranking Domain involves the following steps: Select the Ranking Scheme. Identify the Ranking Domain Identify the available set of entries containing numeric ranking values within the identified Ranking Domain using the selected Ranking Scheme. Remove from the set all entries whose rankings fall outside the minimum and maximum values set by the selected Ranking Scheme. Sort the remaining set of ranked entries according to the significance and precision of the numeric ranking as specified by the Ranking Scheme. 7. Default Ranking Scheme Feeds MAY contain ranked entries that have no specified scheme. Software implementations MAY attempt to match such rankings to well- known schemes associated with the specified domain. For instance, an online search engine may choose to define a ranking scheme that is reflective of the relevance of a given result to a search query; rather than require that a r:scheme element be included in every feed where the Ranking Scheme may be used, or declared in every 'r:rank' element, the search engine may separately publish its Ranking Scheme and associated Ranking Domain. A hypothetical search engine ranking using well-known scheme 5 If a Ranking Scheme cannot be resolved (e.g., no 'scheme' attribute on the r:rank element, no r:scheme with a matching 'name' attribute can be found and the domain is not well-known), the Default Ranking Scheme should be applied. Snell Expires September 11, 2006 [Page 8] Internet-Draft Feed Rank March 2006 o label = 'Default Ranking' o significance = 'ascending' o precision = unspecified o minumum = 0 o maximum = unspecified It is possible that a processor may resolve multiple Ranking Schemes for a given Ranking. In such cases, the processor may decide which Scheme to apply. 8. Security Considerations There are no security considerations introduced by this specification. 9. IANA Considerations There are no IANA considerations introduced by this specification. 10. References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication Format", RFC 4287, December 2005. [W3C.REC-xml-infoset-20040204] Tobin, R. and J. Cowan, "XML Information Set (Second Edition)", W3C REC REC-xml-infoset-20040204, February 2004. [W3C.REC-xml-names-19990114] Hollander, D., Bray, T., and A. Layman, "Namespaces in XML", W3C REC REC-xml-names-19990114, January 1999. [W3C.REC-xmlschema-2-20041028] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes Second Edition", W3C REC REC-xmlschema-2-20041028, October 2004. Snell Expires September 11, 2006 [Page 9] Internet-Draft Feed Rank March 2006 Author's Address James M Snell Phone: Email: jasnell@gmail.com URI: http://snellspace.com Snell Expires September 11, 2006 [Page 10] Internet-Draft Feed Rank March 2006 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Snell Expires September 11, 2006 [Page 11]