UserPreferences

PaceLinkConstruct


Abstract

The [WWW]Atom API Specification 0.9 pre-draft describes usage of the 'link tag' defined in the [WWW]Atom Syndication Format 0.3 pre-draft.

This proposal alters the definition of the Link construct, and consolidates that definition in the Atom Syndication Format Specification.

Status

Open

Related and Conflicting Proposals

PaceLinkPurpose

Rationale

Definition

The definition below adds a "rev" (reverse relationship) attribute. This addition allows applications to group comments and updates sensibly while introducing fewer dependencies than nesting entry elements. This addition also preserves the opacity of URIs to the application.

The values of @rel and @rev are limited to one choice from a list enumerated in the spec. The inconsistent semantics of the space-separated relation types in the HTML link relation attributes make that usage inappropriate for Atom. The Atom Link construct would be better extended with namespaced attributes. If none of the relation values in the spec are appropriate, a new namespaced element is a better mechanism for extension (e.g. Dublin Core relations).

The debate around Atom date elements has been confusing and contentious. Part of that debate concerns what constitutes a "modification", and how to identify a "material modification". This Pace posits that the atom:modified element is currently overloaded with meaning, because modified entries are always identical in structure to those unmodified. The definition below describes relation concepts that are new to Atom, which provide publishers two new methods of communicating a change in content, in addition to modifying the child content of a Content element. The first, "update", is intended to capture those instances when an author appends information to an entry. When reading weblogs, one often sees a text appended to an otherwise unedited entry (e.g. "Update//..."). The second concept is "replace". This allows publishers to signal that an entry is obsolete or otherwise no longer relevant, without removing information that other resources on the web may refer to. Note that the atom:modified date would still be changed when a link element signaling an update or replacement is added to an entry.

Consolidation

The list of attribute values belongs in the format specification, because those values are applicable to Atom outside of the API context. Furthermore, the two specifications are already inconsistent. The format specification limits the acceptable values of @rel to those enumerated in the API specification. However, the API specification only refers to those values as "well-known", and implies that other values are acceptable, as in HTML.

Proposal

Remove section 5.4 from the [WWW]Atom API Specification.

Update section 3.4 of the [WWW]Atom Syndication Format as follows:

3.4 Link Constructs

A Link construct is an element that MUST NOT have any child content. The Link Construct has the following attributes:

3.4.1 "href" Attribute

Link constructs must have an href attribute, whose value MUST be a URI [RFC2396].

3.4.2 "rel" Attribute

The "rel" attribute indicates the relationship of the enclosing element to the URI given in the href attribute. Link constructs MUST have a "rel" or "rev" attribute. The "rel" and "rev" attributes are mutually exclusive.

The value of a "rel" attribute MUST be a string, and MUST be one (and only one) of the following values:

alternate
The URI supplied in the href attribute points to an alternate representation of the enclosing element.

start
The URI supplied in the href attribute contains the first feed in a sequence of entries.

next
The URI supplied in the href attribute contains the next N entries in a sequence of entries.

prev
The URI supplied in the href attribute contains the previous N entries in a sequence of entries.

comment
The URI supplied in the href attribute contains commentary on the enclosing element.

updated.by
The URI supplied in the href attribute is an update to the content of the enclosing element.

replaced.by
The URI supplied in the href attribute supercedes the content of the enclosing element.

service.edit
The URI supplied in the href attribute is used to edit a representation of the referred resource using the Atom API.

service.post
The URI supplied in the href attribute is used to create new resources using the Atom API.

service.feed
The URI supplied in the href attribute is a starting point for navigating content and services using the Atom API.

3.4.3 "rev" Attribute

The "rev" attribute indicates the relation of the URI given in the href attribute to the enclosing element. Link constructs MUST have a "rev" or "rel" attribute. The "rev" and "rel" attributes are mutually exclusive.

The value of a "rev" attribute MUST be a string, and MUST be one (and only one) of the following values:

comment
The enclosing element is commentary on the URI supplied in the href attribute.

update
The enclosing element is an update to the URI supplied in the href attribute.

replaces
The enclosing element supercedes the URI supplied in the href attribute.

3.4.4 "type" Attribute

The "type" attribute indicates an advisory media type; it MAY be used as a hint to determine the type of the representation which should be returned when the URI in the href attribute is dereferenced. Note that the type attribute does not override the actual media type returned with the representation.

3.4.5 "title" Attribute

The "title" attribute conveys human readable information about the link. Link constructs MAY have a title attribute, whose value MUST be a string.

Example

<?xml version="1.0" encoding="UTF-8"?>
<feed version="0.3" xmlns="http://purl.org/atom/ns#" 
          xml:base="http://example.com/feed1/"
          xml:lang="en">
  <title>dive into foo</title>
  <link rel="alternate" type="text/html" 
   href="main" />
  <modified>2003-12-15T09:30:02Z</modified>
  <author>
    <name>Bar Bazrum</name>
  </author>
  <entry xml:base="http://example.com/feed1/2003/12/13/">
    <title>Opinion on Foo</title>
    <link rel="alternate" type="text/html" href="foo.html"/>
    <id>tag:example.com,2003:3.2397</id>
    <issued>2003-12-13T08:29:29-04:00</issued>
    <modified>2003-12-13T18:30:02Z</modified>
    <content type="application/xhtml+xml">I don't like <a href="thing">this</a>!</content>
  </entry>
  <entry xml:base="http://example.com/feed1/2003/12/14/">
    <title>Foo Format Specification</title>
    <link rel="alternate" type="text/html" href="foo_spec.html"/>
    <id>tag:example.com,2003:3.2398</id>
    <issued>2003-12-14T08:29:29-04:00</issued>
    <modified>2003-12-14T08:29:02Z</modified>
    <content type="application/xhtml+xml">Foo elements MUST NOT contain that.</content>
  </entry>
  <entry xml:base="http://example.com/feed1/2003/12/15/">
    <link rev="comment" type="application/atom+xml" href="tag:example.com,2003:3.2397">
    <link rel="alternate" type="text/html" href="foo.html#comment1"/>
    <author>
      <name>John Doe</name>
    </author>
    <id>tag:example.com,2003:3.2399</id>
    <issued>2003-12-15T09:29:29-04:00</issued>
    <modified>2003-12-15T09:30:02Z</modified>
    <content type="application/xhtml+xml">But what if X? I think that should be allowed.</content>
  </entry>
</feed>

later, after our author has reconsidered...

<?xml version="1.0" encoding="UTF-8"?>
<feed version="0.3" xmlns="http://purl.org/atom/ns#" 
          xml:base="http://example.com/feed1/"
          xml:lang="en">
  <title>dive into foo</title>
  <link rel="alternate" type="text/html" 
   href="main" />
  <modified>2003-12-16T09:29:02Z</modified>
  <author>
    <name>Bar Bazrum</name>
  </author>
  <entry xml:base="http://example.com/feed1/2003/12/13/">
    <title>Opinion on Foo</title>
    <link rel="alternate" type="text/html" href="foo.html"/>
    <link rel="updated.by" type="application/atom+xml" href="tag:example.com,2003:3.2400" />
    <id>tag:example.com,2003:3.2397</id>
    <issued>2003-12-13T08:29:29-04:00</issued>
    <modified>2003-12-16T08:29:02Z</modified>
    <content type="application/xhtml+xml">I don't like <a href="thing">this</a>!</content>
  </entry>
  <entry xml:base="http://example.com/feed1/2003/12/14/">
    <title>Foo Format Specification</title>
    <link rel="replaced.by" type="application/atom+xml" href="tag:example.com,2003:3.2401" />
    <link rel="alternate" type="text/html" href="foo_spec_old.html"/>
    <id>tag:example.com,2003:3.2398</id>
    <issued>2003-12-14T08:29:29-04:00</issued>
    <modified>2003-12-16T09:29:02Z</modified>
    <content type="application/xhtml+xml">Foo elements MUST NOT contain that.</content>
  </entry>
  <entry xml:base="http://example.com/feed1/2003/12/15/">
    <link rev="comment" type="application/atom+xml" href="tag:example.com,2003:3.2397">
    <link rel="alternate" type="text/html" href="foo.html#comment1"/>
    <author>
      <name>John Doe</name>
    </author>
    <id>tag:example.com,2003:3.2399</id>
    <issued>2003-12-15T09:29:29-04:00</issued>
    <modified>2003-12-15T09:30:02Z</modified>
    <content type="application/xhtml+xml">But what if X? I think that should be allowed.</content>
  </entry>
  <entry xml:base="http://example.com/feed1/2003/12/16/">
    <title>Opinion on Foo Update</title>
    <link rev="update" type="application/atom+xml" href="tag:example.com,2003:3.2397">
    <link rel="alternate" type="text/html" href="foo.html#update1"/>
    <id>tag:example.com,2003:3.2400</id>
    <issued>2003-12-16T08:29:29-04:00</issued>
    <modified>2003-12-16T08:29:02Z</modified>
    <content type="application/xhtml+xml">John Doe points out situation X. I've reconsidered.</content>
  </entry>
  <entry xml:base="http://example.com/feed1/2003/12/16/">
    <title>Foo Format Specification, Version 2</title>
    <link rev="replaces" type="application/atom+xml" href="tag:example.com,2003:3.2398" />
    <link rel="alternate" type="text/html" href="foo_spec.html"/>
    <id>tag:example.com,2003:3.2401</id>
    <issued>2003-12-16T09:29:29-04:00</issued>
    <modified>2003-12-16T09:29:02Z</modified>
    <content type="application/xhtml+xml">Foo elements SHOULD NOT contain that.</content>
  </entry>
</feed>

Impacts

...

Notes

* The URIs in this proposal and the accompanying example assume acceptance of PaceXmlBaseEverywhere.


CategoryProposals