Network Working Group J. Snell
Internet-Draft A. Sewe
Expires: October 3, 2006 April 2006
Atom Ranking Extensions
draft-snell-atompub-feed-index-09.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 October 3, 2006.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This document defines an extension for numerically ranking entries
within a syndication feed.
Snell & Sewe Expires October 3, 2006 [Page 1]
Internet-Draft Atom Rank April 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.1.1. The 'r:value' and 'r:range' Elements . . . . . . . . . 5
3.2. The 'r:rank' Element . . . . . . . . . . . . . . . . . . . 7
4. Ranking Domain Scope . . . . . . . . . . . . . . . . . . . . . 9
4.1. Base URIs and the Document Ranking Domain . . . . . . . . 10
5. Ranking Domain and Scheme Identifiers . . . . . . . . . . . . 11
6. Processing Rankings . . . . . . . . . . . . . . . . . . . . . 11
7. Default Ranking Scheme . . . . . . . . . . . . . . . . . . . . 11
8. Well-Known Ranking Schemes . . . . . . . . . . . . . . . . . . 12
9. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
10. Security Considerations . . . . . . . . . . . . . . . . . . . 14
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15
Intellectual Property and Copyright Statements . . . . . . . . . . 16
Snell & Sewe Expires October 3, 2006 [Page 2]
Internet-Draft Atom Rank April 2006
1. Introduction
In the Atom Syndication Format [RFC4287], the order of entries as
presented in a feed is typically considered to be insignificant.
This presents a challenge when the set of entries is intended to
represent an ordered or ranked list. This document specifies an
extension 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.
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].
The XML Namespaces URI [W3C.REC-xml-names-19990114] for the XML
elements and attributes described in this specification is:
http://purl.org/syndication/rank/1.0
In this document, the namespace prefix "r:" is used for the above
Namespace URI.
This specification uses a shorthand form of terms from the XML
Infoset [W3C.REC-xml-infoset-20040204]. The phrase "Information
Item" is omitted when naming Element and Attribute Information Items.
Therefore, when this specification uses the term "element," it is
referring to an Element Information Item in Infoset terms. Likewise,
when this specification uses the term "attribute," it is referring to
an Attribute Information Item.
Some sections of this specification are illustrated with a non-
normative RELAX NG Compact schema [RFC4287]. In those sections this
specification uses the atomCommonAttributes and atomURI patterns
defined in [RFC4287].
However, the text of this specification provides the sole definition
of conformance.
3. Ranking Domains and Schemes
A "Ranking Domain" is a uniquely identifiable logical set of entries
with associated numeric ranking values.
A "Ranking Scheme" identifies specific rules on how to interpret the
numeric ranking values within one or more "Ranking Domains".
Snell & Sewe Expires October 3, 2006 [Page 3]
Internet-Draft Atom Rank April 2006
3.1. The 'r:scheme' Element
Ranking Schemes are defined using the r:scheme element. A scheme
includes zero or more r:value and r:range elements that define the
set of possible values for the Ranking Scheme.
rankingScheme = element r:scheme {
atomCommonAttributes,
attribute name { IRI }?,
attribute label { text }?,
attribute significance { 'ascending' | 'descending' }?,
( value | range )*
}
The "name" attribute provides a universally unique identifier for the
scheme in the form of an absolute IRI.
The "label" attribute specifies a Language-Sensitive, human-readable
label for the scheme.
The "significance" attribute indicates how implementations are to
interpret the significance of a numeric ranking value. A value of
"descending" indicates that the significance of the rank decreases 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".
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.
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:r="http://purl.org/syndication/rank/1.0">
...
<r:scheme
name="tag:example.org,2006:movie_reviews"
xml:lang="en-us"
label="Five Star Reviews"
significance="ascending">
<r:range scale="1"
step="0.5"
minimum="0.0"
maximum="5.0" />
</r:scheme>
...
</feed>
Snell & Sewe Expires October 3, 2006 [Page 4]
Internet-Draft Atom Rank April 2006
3.1.1. The 'r:value' and 'r:range' Elements
A Ranking Scheme is defined by a collection of zero or more r:value
and r:range elements that constrain the set of values considered
significant by the Scheme.
The value element defines a discreet decimal value. The element's
content value MUST NOT contain and leading or trailing whitespace.
value = element r:value {
atomCommonAttributes,
attribute label { text }?,
attribute scale { decimal }?,
( decimal )
}
The value element is useful for defining Ranking Schemes consisting
of a set of absolute values as in the example below,
<r:scheme name="tag:example.org,2006:grades"
label="Grading System"
significance="descending">
<r:value label="1" scale="1">1.0</r:value>
<r:value label="1-" scale="1">1.3</r:value>
<r:value label="2+" scale="1">1.7</r:value>
<r:value label="2" scale="1">2.0</r:value>
<r:value label="2-" scale="1">2.3</r:value>
<r:value label="3+" scale="1">2.7</r:value>
<r:value label="3" scale="1">3.0</r:value>
<r:value label="3-" scale="1">3.3</r:value>
<r:value label="4+" scale="1">3.7</r:value>
<r:value label="4" scale="1">4.0</r:value>
<r:value label="4-" scale="1">4.3</r:value>
<r:value label="5+" scale="1">4.7</r:value>
<r:value label="5" scale="1">5.0</r:value>
<r:value label="5-" scale="1">5.3</r:value>
<r:value label="6+" scale="1">5.7</r:value>
<r:value label="6" scale="1">6.0</r:value>
</r:scheme>
The range element defines a range of decimal values that MAY be
bounded by minimum and maximum values.
Snell & Sewe Expires October 3, 2006 [Page 5]
Internet-Draft Atom Rank April 2006
range = element r:range {
atomCommonAttributes,
attribute label { text }?,
attribute scale { decimal }?,
attribute step { decimal }?,
attribute origin { decimal }?,
attribute minimum { decimal }?,
attribute maximum { decimal }?,
( undefinedContent )
}
For example,
<r:scheme name="tag:example.org,2006:grades"
label="Percentage Grading System"
significance="ascending">
<r:range label="F"
minimum="0.00"
maximum="0.59"
scale="2"
step="0.01" />
<r:range label="D"
minimum="0.60"
maximum="0.69"
scale="2"
step="0.01" />
<r:range label="C"
minimum="0.70"
maximum="0.79"
scale="2"
step="0.01" />
<r:range label="B"
minimum="0.80"
maximum="0.89"
scale="2"
step="0.01" />
<r:range label="A"
minimum="0.90"
maximum="0.99"
scale="2"
step="0.01" />
<r:value label="A+"
scale="2">1.00</r:value>
</r:scheme>
The "scale" attribute on both the value and range elements specifies
the total number of decimal digits to the right of the decimal
indicator in the value of the numeric ranking value. The scale is
Snell & Sewe Expires October 3, 2006 [Page 6]
Internet-Draft Atom Rank April 2006
expressed as a non-negative integer. If not specified, the value is
considered to be zero. Ranking Schemes that are based on fractional
numeric ranking values SHOULD specify a scale. Numeric ranking
values that use a larger scale than defined for the scheme MUST be
rounded to the nearest in-scale value (e.g. with scale=2, the rank
0.123 is rounded down to 0.12, the rank 0.125 is rounded up to 0.13.)
The "step" attribute specifies the minimum significant increment for
numeric ranking values within a given range. For instance, if a
range is based on full and half values (e.g. 0.0, 0.5, 1.0, 1.5,
etc), the step attribute value would be 0.5. If not specified, no
significant increment is considered to apply. When compared with
other numeric rankings, values that do not precisely match the
pattern specified by the step attribute MUST be rounded to the
nearest least-significant increment. For example, if the Scheme's
significance is ascending and step equals 0.50, the value 1.45 is
equivalent to 1.00; if significance is descending, the value is
equivalent to 1.50.
The "origin" attribute specifies the base from which steps in a range
are to be calculated. For instance, given a fractional Ranking
Scheme where step=0.5 and no minimum or maximum value, the Scheme may
specify 0.0 as the step origin, resulting in a set of rankings
calculated relative to the value 0.0 (e.g. ..., -1.0, -0.5, 0.0, 0.5,
1.0, ...). The origin MUST be specified if step is specified and
either a) significance is ascending and no minimum is defined, or b)
significance is descending and no maximum is defined.
The "minumum" attribute specifies the lowest possible value for a
range (inclusive). If not specified, no minimum value is considered
to apply.
The "maximum" attribute specifies the highest possible value for a
range (inclusive). If not specified, no maximum value is considered
to apply.
Ranges and values defined within a Scheme MUST NOT overlap one
another.
3.2. The 'r:rank' Element
Numeric rankings are specified using the "r:rank" element.
Snell & Sewe Expires October 3, 2006 [Page 7]
Internet-Draft Atom Rank April 2006
rankingValue = element r:rank {
atomCommonAttributes,
attribute domain { IRI }?,
attribute scheme { IRI }?,
attribute label { text }?,
{ decimal }
}
The "domain" attribute identifies the Ranking Domain containing the
entry. 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.
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:r="http://purl.org/syndication/rank/1.0">
...
<entry>
...
<r:rank
domain="http://example.org/movie_reviews"
scheme="tag:example.com,2006:movie_reviews"
label="Good">3.5</r:rank>
</entry>
</feed>
Entries MAY contain zero or more r:rank elements. An entry MUST NOT
contain more than one r:rank element with the same combination of
domain and scheme IRI identities.
The following, for example, is invalid because both rankings exist in
the same Ranking Domain and use the same Ranking Scheme.
<r:rank xml:base="http://example.com/feed/base"
domain=""
scheme="tag:example.org,2006:movie_reviews"
label="Good" >3.5</r:rank>
<r:rank
domain="http://example.com/feed/base"
scheme="tag:example.org,2006:movie_reviews"
Snell & Sewe Expires October 3, 2006 [Page 8]
Internet-Draft Atom Rank April 2006
label="Bad" >1.5</r:rank>
4. Ranking Domain Scope
Ranking Domains group entries with attached numeric ranking values to
logical sets. Ranking Domains are uniquely identified by IRIs.
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
<r:rank
scheme="tag:example.org,2006:movie_reviews"
label="Good" >3.5</r:rank>
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 in-
scope Base URI are associated with a Document Ranking Domain
identified by the in-scope Base URI.
A numeric ranking associated with the Document Ranking Domain
<r:rank
domain=""
scheme="tag:example.org,2006:movie_reviews"
label="Good">3.5</r:rank>
The set of entries contained within the Document Ranking Domain is
limited to the set of 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 and the atom:id of the containing feed
are associated with a Domain Scope.
Snell & Sewe Expires October 3, 2006 [Page 9]
Internet-Draft Atom Rank April 2006
A numeric ranking associated with the Feed Ranking Domain
<r:rank
domain="http://www.example.org/movie_reviews"
scheme="tag:example.org,2006:movie_reviews"
label="Good">3.5</r:rank>
Domain Scopes SHOULD be considered open sets consistings of entries
from any number of feeds.
4.1. Base URIs and the Document Ranking Domain
When specifying or processing rankings in the Document Ranking
Domain, implementors need to be aware of the the impact the
document's Base URI has on the Domain's set of entries.
For instance, in the example,
<feed xmlns="http://www.w3.org/2005/Atom"
xml:base="http://example.org/feed.xml" ...>
...
<entry>
<id>tag:example.org,2005:1</id>
<r:rank
domain=""
scheme="tag:example.org,2006:movie_reviews"
label="Good">3.5</r:rank>
...
</enry>
<entry xml:base="http://example.com/anotherfeed.xml">
<id>tag:example.com,2005:1</id>
<r:rank
domain=""
scheme="tag:example.org,2006:movie_reviews"
label="Good">3.5</r:rank>
...
</enry>
<entry>
<id>tag:example.com,2005:2</id>
<r:rank
domain="http://example.org/anotherfeed.xml"
scheme="tag:example.org,2006:movie_reviews"
label="Good">3.5</r:rank>
...
</enry>
</feed>
The three entries contained by the feed exist in two separate
Snell & Sewe Expires October 3, 2006 [Page 10]
Internet-Draft Atom Rank April 2006
Document Ranking Domains, each respectively identified by the URIs
"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 mechanisms such as xml:base or the
Content-Location HTTP header.
5. Ranking Domain and Scheme Identifiers
The IRIs 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 IRIs or URIs
mapped from them.
6. Processing Rankings
Processing a Ranking Domain to produce an ordered set involves the
following steps:
o Select the Ranking Scheme.
o Identify the Ranking Domain
o Identify the available set of entries containing numeric ranking
values within the identified Ranking Domain using the selected
Ranking Scheme.
o Remove from the set all entries whose rankings fall outside the
minimum and maximum values set by the selected Ranking Scheme.
o Sort the remaining set of ranked entries according to the
significance and step of the numeric ranking as defined by the
Ranking Scheme.
7. Default Ranking Scheme
Feeds MAY contain ranked entries that have no specified scheme. In
such cases the Default Ranking Scheme should be applied.
The Default Ranking Scheme assumes ascending significance and a
single range with no minimum or maximum value, no significant step,
unspecified scale, and an origin of 0.
Snell & Sewe Expires October 3, 2006 [Page 11]
Internet-Draft Atom Rank April 2006
8. Well-Known Ranking Schemes
Feeds MAY contain ranked entries whose ranking scheme cannot be
resolved (i.e., no r:scheme with a "name" attribute matching the
rankings "scheme" attribute can be found). In such cases software
implementations MAY attempt to match such rankings to well-known
schemes. 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, the
search engine may separately publish its Ranking Scheme and
associated Ranking Domain. (The format of such a publication is
beyond the scope of this specification.)
A hypothetical search engine ranking using a well-known scheme
<r:rank scheme="http://search.example.org/relevance">5</r:rank>
If a Ranking Scheme cannot be resolved this way (e.g., no r:scheme
with a matching "name" attribute can be found and the scheme is not
well-known), the Default Ranking Scheme should be applied.
Further, it is possible that a processor may resolve multiple Ranking
Schemes for a given Ranking. For instance, a feed may contain an
"r:scheme" that redefines a scheme well-known to the processor. In
such cases, processors should issue a warning to the user.
9. Example
In the following example, numeric rankings are used to establish a
simple ordering for entries within a feed and to specify an average
customer review rating for each of the movies listed. The former are
scoped to the document in which the entries appear, while the latter
are scoped to a specific domain.
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:r="http://purl.org/syndication/rank/1.0">
<id>tag:example.org,2006:my_movie_queue</id>
<title type="text">My Movie Queue</title>
<updated>2006-05-01T12:00:00Z</updated>
<author><name>James</name></author>
<link rel="self" href="queue.xml" />
<link href="queue.html" />
<r:scheme name="tag:example.org,2006:my_movie_queue"
label="Queue Position"
significance="descending">
<r:range minimum="0" step="1" />
Snell & Sewe Expires October 3, 2006 [Page 12]
Internet-Draft Atom Rank April 2006
</r:scheme>
<r:scheme name="tag:example.org,2006:movie_reviews"
label="Customer Reviews"
signifiance="ascending">
<r:range minimum="0.0" maximum="5.0"
step="0.5" scale="1" />
</r:scheme>
<entry>
<id>tag:example.org,2006:movies/chaplin/citylights</id>
<title type="text">City Lights</title>
<updated>2006-05-01T12:00:00Z</updated>
<link href="/movies/chaplin/citylights.html" />
<summary>Charlie Chaplin's cassic film</summary>
<r:rank domain=""
scheme="tag:example.org,2006:my_movie_queue">1</r:rank>
<r:rank
domain="tag:example.org,2006:movie_reviews"
scheme="tag:example.org,2006:movie_reviews">4.5</r:rank>
</entry>
<entry>
<id>tag:example.org,2006:movies/chaplin/moderntimes</id>
<title type="text">Modern Times</title>
<updated>2006-05-01T12:00:00Z</updated>
<link href="/movies/chaplin/moderntimes.html" />
<summary>Another Chaplin classic</summary>
<r:rank domain=""
scheme="tag:example.org,2006:my_movie_queue">3</r:rank>
<r:rank
domain="tag:example.org,2006:movie_reviews"
scheme="tag:example.org,2006:movie_reviews">3.5</r:rank>
</entry>
<entry>
<id>tag:example.org,2006:movies/chaplin/thegoldrush</id>
<title type="text">The Gold Rush</title>
<updated>2006-05-01T12:00:00Z</updated>
<link href="/movies/chaplin/thegoldrush.html" />
<summary>Chaplin in a frozen wilderness</summary>
<r:rank domain=""
scheme="tag:example.org,2006:my_movie_queue">2</r:rank>
<r:rank
domain="tag:example.org,2006:movie_reviews"
scheme="tag:example.org,2006:movie_reviews">5.0</r:rank>
</entry>
</feed>
Snell & Sewe Expires October 3, 2006 [Page 13]
Internet-Draft Atom Rank April 2006
10. Security Considerations
Because this specification defines an extension to the Atom
Syndication Format [RFC4287], it is subject to the same security
consideration as defined in section 8 of that specification.
11. IANA Considerations
There are no IANA considerations introduced by this specification.
12. 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.
Appendix A. Acknowledgements
The authors gratefully acknowledge the feedback from the Atom
Publishing working group during the development of this
specification.
Snell & Sewe Expires October 3, 2006 [Page 14]
Internet-Draft Atom Rank April 2006
Authors' Addresses
James M Snell
Phone:
Email: jasnell@gmail.com
URI: http://www.snellspace.com
Andreas Sewe
Phone:
Email: sewe@rbg.informatik.tu-darmstadt.de
URI:
Snell & Sewe Expires October 3, 2006 [Page 15]
Internet-Draft Atom Rank April 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 & Sewe Expires October 3, 2006 [Page 16]