


Network Working Group                                      M. Nottingham
Internet-Draft                                               Yahoo! Inc.
Expires: February 1, 2007                                  July 31, 2006


                      FQL: The Feed Query Language
                    draft-nottingham-atompub-fql-00

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 February 1, 2007.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   The Feed Query Language is a simple but flexible, URI-friendly syntax
   for expressing filters across the entries in a feed.










Nottingham              Expires February 1, 2007                [Page 1]

Internet-Draft                     FQL                         July 2006


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Notational Conventions . . . . . . . . . . . . . . . . . . . .  3
   3.  FQL Syntax and Processing  . . . . . . . . . . . . . . . . . .  3
     3.1.  Expressions  . . . . . . . . . . . . . . . . . . . . . . .  3
     3.2.  Constraints  . . . . . . . . . . . . . . . . . . . . . . .  4
       3.2.1.  Textual Constraints  . . . . . . . . . . . . . . . . .  5
       3.2.2.  Date Constraints . . . . . . . . . . . . . . . . . . .  6
       3.2.3.  Numeric Constraints  . . . . . . . . . . . . . . . . .  7
   4.  Using FQL in HTTP  . . . . . . . . . . . . . . . . . . . . . .  8
   5.  FQL Feed Extensions  . . . . . . . . . . . . . . . . . . . . .  9
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . .  9
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 10
   8.  Normative References . . . . . . . . . . . . . . . . . . . . . 10
   Appendix A.  Acknowledgements  . . . . . . . . . . . . . . . . . . 10
   Appendix B.  Default Element Types . . . . . . . . . . . . . . . . 10
     B.1.  Atom . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
     B.2.  RSS 1.0  . . . . . . . . . . . . . . . . . . . . . . . . . 11
     B.3.  RSS 2.0  . . . . . . . . . . . . . . . . . . . . . . . . . 11
   Appendix C.  Collected BNF . . . . . . . . . . . . . . . . . . . . 11
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12
   Intellectual Property and Copyright Statements . . . . . . . . . . 13




























Nottingham              Expires February 1, 2007                [Page 2]

Internet-Draft                     FQL                         July 2006


1.  Introduction

   The Feed Query Language is a simple but flexible, URI-friendly syntax
   for expressing filters across the entries in a feed.  For example,

     title==foo*&(lastUpdated=lt=-1day,title==*bar)

   will return all entries in the feed that meet the following criteria;

   o  have a title beginning with "foo", or
   o  have been updated in the last day and have a title ending with
      "bar".

   The output of an FQL query is a feed that has the same head section
   as the input feed, but that only contains entries that match the
   query expression (that is, those that yield True).


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], as
   scoped to those conformance targets.

   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;

   "fql": "http://purl.org/syndication/query/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.

   Although they refer to Atom normatively, the mechanisms described
   herein can be used with similar syndication formats, such as the
   various flavours of RSS.


3.  FQL Syntax and Processing

3.1.  Expressions

   FQL Expressions yield Boolean values: True or False.




Nottingham              Expires February 1, 2007                [Page 3]

Internet-Draft                     FQL                         July 2006


   An FQL expression is composed of one or more constraints, related to
   each other with Boolean operators.

   expression = [ "(" ] ( constraint / expression )
                [ operator ( constraint / expression ) ] [ ")" ]
   operator = "&" / ","

   o  "&" is the Boolean AND operator; it yields True for a particular
      entry if both operands evaluate to True, otherwise False.
   o  "," is the Boolean OR operator; it yields True if either operand
      evaluates to True, otherwise False.

   By default, the AND operator takes precedence (i.e., it is evaluated
   before any OR operators are); however, a parenthesised expression can
   be used to change precedence, yielding whatever the contained
   expression yields.

3.2.  Constraints

   FQL Constraints yield Boolean values: True or False.

   A constraint is composed of a selector, which selects one more child
   elements of the entry, and an optional comparison/argument pair,
   which refines the constraint.

   constraint = selector [ comparison argument ]
   selector = qname *( "." qname )
   comparison = "==" / "!=" / "=lt=" / "=gt="
   argument = text / date / number / qname

   The most common form of a selector is a single XML QName [ref], which
   selects any and all elements in the entry which share that
   identifier.

   Selectors can also contain multiple QNames, separated by periods
   ("."), representing successive child elements.  For example, given
   the entry

   <entry>
     <foo>
       <bar/>
     </foo>
   </entry>

   the selector "foo.bar" will select the innermost element.

   If more than one instance of a selected element is present in an
   entry, the comparison will be evaluated against each, and will yield



Nottingham              Expires February 1, 2007                [Page 4]

Internet-Draft                     FQL                         July 2006


   True if any of the individual element comparisons yield True;
   otherwise False.

   A constraint with no comparison operator will yield True if the
   specified qname is present as a child of the entry element.

   Constraints with comparison operators are compared according to the
   type of the qname.  See "FQL Feed Extensions" for one mechanism for
   determining the type of a qname in an FQL expression.

   This specification defines the following comparison types;

3.2.1.  Textual Constraints

   Text constraints allow free-text searching of the descendant text
   content of the selected element.

   text = [ "*" ] *( l_char | pct-encoded ) [ "*" ]
   l_char = unreserved / gen_delims / "!" / "$" / "'" / "+" / ";" / "="

   Two comparison operators are applicable to text constraints;

   o  "==" yields True if the descendant text of the selected element
      matches the argument to the constraint; otherwise False.
   o  "!=" yields True if the descendant text of the selected element
      does not match the argument to the constraint; otherwise False.

   If the argument begins and/or ends with an asterisk character, it
   should be treated as a globbing operator; that is, any and all
   characters preceding or following it (respectively) MUST be ignored.

   If the selected element contains markup, it MUST be ignored.  Text
   content therein MUST NOT be ignored.

   White space in the selected element's content MUST be collapsed to
   single space characters.

   Any characters not explicitly allowed in the argument MUST be
   percent-encoded [ref].

   Text searches are case-insensitive.

   For example, given the entry:








Nottingham              Expires February 1, 2007                [Page 5]

Internet-Draft                     FQL                         July 2006


   <entry>
     <title>Hello world</title>
     <description>Just    starting.</description>
     <author>
        <name>Mark Nottingham</name>
     </author>
     <!-- other stuff -->
   </entry>

      "title==hello%20world" yields True
      "title!=hello" yields True
      "title==hello*" yields True
      "author.name==mark*" yields True
      "description==*START*" yields True
      "description==*just*" yields True
      "description==just%20starting" yields True
      "description=="*just" yields False

   [ URI ]

3.2.2.  Date Constraints

   Date constraints allow both relative and absolute comparison of date-
   related elements.

   date = dateTime / duration

   Four comparison operators are relevant to date constraints;

   o  "==" yields True if the point in time specified in the argument to
      the constraint matches that indicated by the selected element;
      otherwise False.
   o  "!=" yields True if the point in time specified in the argument to
      the constraint does not match that indicated by the selected
      element; otherwise False.
   o  "=lt=" yields True if the point in time specified in the argument
      to the constraint follows that indicated by the selected element;
      otherwise False.
   o  "=gt=" yields True if the point in time specified in the argument
      to the constraint precedes that indicated by the selected element;
      otherwise False.

   A point in time can be specified in two ways;

   o  Absolutely, expressed as an XML Schema dateTime [ref].
   o  Relatively, expressed as an XML Schema duration [ref].  By
      default, such arguments are relative to the time that the query is
      processed.



Nottingham              Expires February 1, 2007                [Page 6]

Internet-Draft                     FQL                         July 2006


   White space and markup in the selected element's content MUST be
   ignored.

   For example, given an entry

   <entry>
     <title>Hello World</title>
     <updated>2003-12-13T18:30:02Z</updated>
     <!-- other stuff -->
   </entry>

   o  "updated==2003-12-13T18:30:02Z" yields True
   o  "updated=gt=2003-12-13T00:00:00Z" yields True
   o  "updated=lt=2005-01-01T00:00:00Z yields True
   o  "updated=gt=-P1D12H" yields False
   o  "updated=gt=-P5Y" yields True

   (assuming processing on July 1st, 2006)

   [ URI ]

3.2.3.  Numeric Constraints

   Numeric constraints allow comparison of decimals.

   number = [ "+" / "-" ] 1*DIGIT [ "." 1*DIGIT ]

   Four comparison operators are relevant to numeric constraints;

   o  "==" yields True if the content of the selected element is
      numerically equal to the specified argument; otherwise False.
   o  "!=" yields True if the content of the selected element is not
      numerically equal to the specified argument; otherwise False.
   o  "=lt=" yields True if the content of the selected element
      evaluates as numerically less than the specified argument;
      otherwise, False.
   o  "=gt=" yields True if the content of the selected element
      evaluates as numerically greater than the specified argument;
      otherwise, False.

   White space and markup in the selected element's content MUST be
   ignored.

   For example, given an entry

   <entry>
     <title>Hello World</title>
     <x:foo>123</x:foo>



Nottingham              Expires February 1, 2007                [Page 7]

Internet-Draft                     FQL                         July 2006


     <x:bar>  456</x:foo>

   o  "x:foo==123" yields True
   o  "x:foo==123.00" yields True
   o  "x:foo!=123.1" yields True
   o  "x:foo=lt=200" yields True
   o  "x:bar==456" yields True
   o  "x:foo=gt=500" yields False

   [ URI ]


4.  Using FQL in HTTP

   Although FQL can be used in many contexts, it is optimised and
   intended for use in HTTP requests.

   Expressions can be embedded in different components of the Request-
   URI; e.g.,

     http://example.com/feed.atom?title==*new*,author.name==bob*
     http://example.org/feed.rss;title==*great*&ex:rating=gt=4

   FQL expressions are also suitable for POSTing to resources as
   application/x-www-form-urlencoded body content.

   Resources SHOULD return a 400 Bad Request status code if an FQL
   expression includes an unsupported or unknown selector.

   When used in this manner, bindings for namespace prefixes SHOULD be
   inferred from the document retrieved from the same URI.  For example,
   given the following document;

   <feed xmlns="http://www.w3.org/2005/Atom"
         xmlns:ex="http://other.example.net/">
     <!-- ... -->
   </feed>

   and the expression

     title==foo,ex:bar==baz

   the first comparison's selector should be considered to be in the
   namespace "http://www.w3.org/2005/Atom", and the second should be
   considered in the namespace "http://other.example.net".

   To facilitate discovery of namespace bindings using HEAD, responses
   MAY include Link HTTP headers [ref] that declare them;



Nottingham              Expires February 1, 2007                [Page 8]

Internet-Draft                     FQL                         July 2006


   HTTP/1.1 200 OK
   Content-Type: application/atom+xml
   Link: <http://www.w3.org/2005/Atom>; rel="xmlns"; prefix=""
   Link: <http://other.example.net>; rel="xmlns"; prefix="ex"

   <feed xmlns="http://www.w3.org/2005/Atom"
         xmlns:ex="http://other.example.net/">
     <!-- ... -->
   </feed>


5.  FQL Feed Extensions

   Although FQL is usable with feeds as-is, it is often desireable to
   associate types with extension elements, and to advertise what
   elements are searchable.

   This can be accomplished using a top-level feed extension, fql:
   indices.  For example,

   <feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:ex="http://other.example.net/">
     <title>example</title>
     <link href="http://www.example.org/"/>
     <id>http://example.org/</id>
     <fql:indices xmlns:fql="http://tbd">
       <fql:element name="title"/>
       <fql:element name="ex:foo" type="http://tbd/date"/>
       <fql:element name="ex:bar" type="http://tbd/numeric"/>
     </fql:indices>
     <entry>
       <title>test entry</title>
       <description>something...</description>
       <id>http://example.org/1124</id>
       <ex:foo>2003-12-13T18:30:02Z</ex:foo>
       <ex:bar>15.4</ex:bar>
   </feed>

   Here, the fql:indices element indicates that of the standard Atom
   elements, the title element has been indexed for queries, as well as
   the ex:foo and ex:bar extensions, which are a date and number,
   respectively.

   {formally define fql:indices, fql:element]


6.  Security Considerations




Nottingham              Expires February 1, 2007                [Page 9]

Internet-Draft                     FQL                         July 2006


   [ query canonicalisation? ]


7.  IANA Considerations

8.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, January 2005.

   [RFC4287]  Nottingham, M. and R. Sayre, "The Atom Syndication
              Format", RFC 4287, December 2005.

   [W3C.REC-xml-infoset-20040204]
              Cowan, J. and R. Tobin, "XML Information Set (Second
              Edition)", W3C REC REC-xml-infoset-20040204,
              February 2004.

   [W3C.REC-xml-names-19990114]
              Bray, T., Hollander, D., and A. Layman, "Namespaces in
              XML", W3C REC REC-xml-names-19990114, January 1999.


Appendix A.  Acknowledgements


Appendix B.  Default Element Types

B.1.  Atom

   o  atom:author - text
   o  atom:category - text
   o  atom:content - text
   o  atom:contributor - text
   o  atom:id - text
   o  atom:link - text
   o  atom:published - date
   o  atom:rights - text
   o  atom:source - text
   o  atom:summary - text
   o  atom:title - text
   o  atom:updated - date





Nottingham              Expires February 1, 2007               [Page 10]

Internet-Draft                     FQL                         July 2006


B.2.  RSS 1.0

   o

B.3.  RSS 2.0

   o


Appendix C.  Collected BNF

   expression = [ "(" ] ( constraint / expression )
                [ operator ( constraint / expression ) ] [ ")" ]
   operator = "&" / ","
   constraint = selector [ comparison argument ]
   selector = qname *( "." qname )
   comparison = "==" / "!=" / "=lt=" / "=gt="
   argument = text / date / number / qname
   text = [ "*" ] *( l_char | pct-encoded ) [ "*" ]
   l_char = unreserved / gen_delims / "!" / "$" / "'" / "+" / ";" / "="
   number = [ "+" / "-" ] 1*DIGIT [ "." 1*DIGIT ]
   date = dateTime / duration





























Nottingham              Expires February 1, 2007               [Page 11]

Internet-Draft                     FQL                         July 2006


Author's Address

   Mark Nottingham
   Yahoo! Inc.

   Email: mnot@yahoo-inc.com
   URI:   http://www.mnot.net/












































Nottingham              Expires February 1, 2007               [Page 12]

Internet-Draft                     FQL                         July 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.




Nottingham              Expires February 1, 2007               [Page 13]

