commentmeta.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="exp" docName="atomcommentmeta-00" ipr="none">
  <front>
    <title abbrev="AtomCommentMeta">Atom Comment Metadata Extensions
    (Draft)</title>

    <author fullname="Martin Atkins" initials="M." surname="Atkins">
      <organization>Six Apart Ltd</organization>
    </author>

    <date />

    <abstract>
      <t>This document presents an extension to the Atom Threading Extensions
      which allows entries that represent replies to include some metadata
      about what is being replied to.</t>
    </abstract>

    <note title="Requirements Language">
      <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">RFC 2119</xref>.</t>
    </note>
  </front>

  <middle>
    <section title="Introduction">
      <t><xref target="RFC4685"></xref> describes an extension to <xref
      target="RFC4287">the Atom Syndication Format</xref> that allows
      publishers to express that a particular entry is in reply to another
      entry. However, the mechanism provided by this extension does not
      provide sufficient metadata to describe the parent resource to a human
      user.</t>

      <t>While consumers can in theory fetch the original feed and locate the
      entry, this requires an additional fetch for each comment that is too
      expensive for many consumer use-cases. This specification follows the
      principles of the atom:source element from the Atom specification to
      provide additional, non-authoritative metadata as a hint to such
      consumers.</t>
    </section>

    <section title="Notational Conventions">
      <t>In this document, the the XML namespace prefix "atom:" is used for
      the namespace URI <spanx style="verb">http://www.w3.org/2005/Atom</spanx>,
      and the XML namespace prefix "thr:" is used for the namespace URI <spanx
      style="verb">http://purl.org/syndication/thread/1.0</spanx>. This choice
 			of namespace prefix is arbitrary and not semantically significant.</t>

      <t>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.</t>

      <t>This specification allows the use of IRIs [RFC3987]. Every URI
      [RFC3986] is also an IRI, so a URI may be used wherever an IRI is named.
      When an IRI that is not also a URI is given for dereferencing, it MUST
      be mapped to a URI using the steps in Section 3.1 of [RFC3987]. When an
      IRI is serving as an identifier, it MUST NOT be so mapped.</t>

      <t>This specification uses "the Atom specification" to refer to <xref
      target="RFC4287"></xref>, and "the threading extensions specification"
      to refer to <xref target="RFC4685"></xref>.</t>

      <t>Where this specification describes the heirarchy of replies, it uses
      the term "the parent element" to refer to the target of an "in reply to"
      relationship as described in the threading extensions specification, and
      "the child element" to refer to the source of that relationship.</t>
    </section>

    <section title="Extensions to thr:in-reply-to">
      <t>The extensions described by this specification are in the form of
      child elements of the thr:in-reply-to element as defined by the
      threading extensions specification.</t>

      <t>Publishers MAY include the atom:title, atom:summary, atom:content,
      atom:published, atom:updated, atom:author and atom:link elements as
      children of thr:in-reply-to. When used in this way, these elements have
      equivalent meaning and content model as the same elements appearing as
      children of the parent entry. If a publisher includes any of these
      elements, the publisher SHOULD ensure that they have the same values as
      those in the parent entry as far as possible with the information
      available.</t>

      <t>Publishers MUST NOT include an atom:link element of relationship
      "alternate" that has href and type attributes identical to those on the
      thr:in-reply-to element, as those attributes on in-reply-to imply such a
      link. If there is more than one "alternate" hyperlink, and if one of the
      hyperlinks is of type text/html, the text/html hyperlink SHOULD be
      represented via attributes on the thr:in-reply-to element.</t>

      <t>Note also that in particular atom:id MUST NOT be included as a child
      of thr:in-reply-to. The "ref" attribute of thr:in-reply-to has
      equivalent meaning.</t>

      <t>Consumers MUST NOT assume that the absense of an element as a child
      of thr:in-reply-to implies the absense of that element in the parent
      entry.</t>
    </section>

    <section anchor="authoritative" title="Authoritative Metadata">
      <t>In most cases, the additional metadata included using this extension
      are non-authoritative, and are provided only as a hint to consumers so
      that they may, when appropriate, avoid dereferencing the source feed of
      the parent entry.</t>

      <t>However, there are three occasions where a consumer MAY consider the
      parent entry metadata to be authoritative:</t>

      <t><list style="symbols">
          <t>When the parent entry appears within the same feed as the child
          entry.</t>

          <t>When the child entry is appears within a feed that is known to be
          referenced by a "replies" hyperlink in the source entry.</t>

          <t>When the consumer has external information about the
          authoritative nature of the metadata. For example, a particular
          consumer might have recieved some form of guarantee that the comment
          feeds provided by a particular publisher will always contain
          up-to-date metadata about parent resources in other feeds provided
          by that same publisher.</t>
        </list></t>

      <t>Publishers MUST ensure that in the above situations any parent entry
      metadata is suitably accurate for use in place of the equivalent on the
      parent entry, or omit any elements which they are unable to produce
      accurately.</t>
    </section>

    <section title="Security Considerations">
      <t>As this specification defines an extension to the Atom Syndication
      Format, it is subject to the same security considerations defined in
      <xref target="RFC4287"></xref>.</t>

      <t>The additional elements defined in this specification contain
      non-authoritative metadata except as described in <xref
      target="authoritative"></xref> and must therefore not be presented to
      the end-user as authoritative.</t>

      <t>[TODO: Write some more here.]</t>
    </section>

    <section title="IANA Considerations">
      <t>None.</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <reference anchor="RFC4287">
        <front>
          <title>The Atom Syndication Format</title>

          <author>
            <organization></organization>
          </author>

          <date />
        </front>
      </reference>

      <reference anchor="RFC2119">
        <front>
          <title>RFC 2119</title>

          <author>
            <organization></organization>
          </author>

          <date />
        </front>
      </reference>

      <reference anchor="RFC3987">
        <front>
          <title>Internationalized Resource Identifiers (IRIs)</title>

          <author>
            <organization></organization>
          </author>

          <date />
        </front>
      </reference>

      <reference anchor="RFC4685">
        <front>
          <title>Atom Threading Extensions</title>

          <author fullname="James Snell" initials="J." surname="Snell">
            <organization></organization>
          </author>

          <date month="September" year="2006" />
        </front>
      </reference>
    </references>

    <section title="Acknowledgements">
      <t>...</t>
    </section>

    <section title="Examples">
      <t>This appendix is non-normative. Where these examples include
      fragments of XML documents, assume the namespace declarations <spanx
      style="verb">xmlns="http://www.w3.org/2005/Atom" xmlns:thr="http://purl.org/syndication/thread/1.0"</spanx>
      are in scope.</t>

      <section anchor="parententryexample" title="Parent Entry Example">
        <figure>
          <preamble>An example top-level entry</preamble>

          <artwork><![CDATA[<entry>
   <id>tag:blogpad.example.com,2008:entry01</id>
   <title>Pictures of my Cat</title>
   <published>2008-11-02T15:29:00Z</published>
   <updated>2008-11-02T15:29:00Z</updated>
   <link rel="alternate" type="text/html"
         href="/geraldine/entries/1" />
   <link rel="replies" type="application/atom+xml"
         href="/geraldine/entries/1/comments.atom" />
   <content type="html">
       (content elided)
   </content>
   <author>
      <name>Geraldine</name>
      <uri>http://blogpad.example.com/geraldine/</uri>
   </author>
</entry>]]></artwork>

          <postamble>This example shows a typical Atom entry with a "replies"
          hyperlink as described in the threading extensions
          specification.</postamble>
        </figure>
      </section>

      <section anchor="childentryexample" title="Child Entry Example">
        <figure>
          <preamble>An example "comment" entry</preamble>

          <artwork><![CDATA[<entry>
   <id>tag:blogpad.example.com,2008:comment01</id>
   <title>Re: Pictures of my Cat</title>
   <published>2008-11-02T15:34:02Z</published>
   <link rel="alternate" type="text/html"
         href="/geraldine/entres/1#comment1" />
   <content type="text">
       So cute!
   </content>
   <author>
      <name>Tim</name>
      <uri>http://blogpad.example.com/tim/</uri>
   </author>
   <thr:in-reply-to ref="tag:blogpad.example.com,2008:entry01"
                    type="text/html" href="/geraldine/entries/1">
      <title>Pictures of my Cat</title>
      <published>2008-11-02T15:29:00Z</published>
      <updated>2008-11-02T15:29:00Z</updated>
   </thr:in-reply-to>
</entry>]]></artwork>

          <postamble>This example shows an Atom entry that represents a
          text-based comment on the entry shown in <xref
          target="parententryexample"></xref>. In this case, the comment entry
          includes the title, publication and last-updated dates of the parent
          entry.</postamble>
        </figure>
      </section>
    </section>
  </back>
</rfc>