Comment API Namespace for RSS

Editor's Note: This is version 1.0 of this document, published August 10, 2023.

1. Introduction

The Comment API namespace enables an Atom, RSS 1.0 or RSS 2.0 feed to support comments in two useful ways -- publicizing the URL of feeds that contain an item's comments and providing a REST interface that enables an RSS reader to take comments on a form presented along with feed items and send that comment to the publisher of that feed.

Introduced in 2003 as the Well-Formed Web Comment API, it has been widely adopted as the most popular namespace for supporting comments in RSS.

2. Conventions

In this documentation, the key words may, must, must not, optional, recommended, required, shall, shall not, should and should not are to be interpreted as described in RFC 2119.

3. Declaration

The Comment API namespace requires a declaration with "http://wellformedweb.org/CommentAPI/" as the URI in the top-level rss element.

A sample feed demonstrates how to incorporate elements from this namespace in an RSS 2.0 feed.

Feeds that make use of the namespace often choose the identifier "wfw", which stands for "well-formed web", but this is not a requirement. There are no restrictions on namespace identifiers.

4. wfw:commentRss

The commentRss element, when present in an item, identifies the URL of an RSS feed that contains user comments submitted in response to that item (optional).

<wfw:commentRss>https://ekzemplo.com/news/130/comments.xml</wfw:comment>

The value of the element must be a URL.

An item must not contain more than one commentRss element.

Some documentation for this namespace incorrectly referred to wfw:commentRSS as the name. Though wfw:commentRss is correct, the developers of software that read feeds should accept both spellings, since both have been used in feeds.

5. wfw:comment

The comment element, when present in an item, identifies a URL endpoint that can receive a comment to the item as a HTTP POST request and save the comment (optional).

<wfw:comment>https://ekzemplo.com/comment?post=130<wfw:comment>

The value of the element must be a URL. It is intended for use by RSS readers and other aggregators so they can offer a form to users within the software where a comment can be entered and upon completion submit that data to the URL identified in wfw:comment.

The POST request should have a "Content-Type" header indicating that the format is "text/xml" and a body that contains XML resembling an RSS 2.0 feed item that contains up to six elements: title, author, link, description, source and the creator element from Dublin Core. All of these elements are optional but there must be either a title or a description.

POST /comment?post=130 HTTP/1.1
Content-Type: text/xml

<?xml version="1.0" encoding='iso-8859-1'?>
<item>
  <title>Joining Mastodon</title>
  <author>ernie@example.com</author>
  <link>https://example.social/@ernie</link>
  <description>I just joined Mastodon. Find me at the link!</description>
</item>

The server that receives the POST responds with the appropriate HTTP status code, which will be "200 OK" if the comment was received successfully. Otherwise it could be "400 Bad Request" if the request was not formatted correctly, "503 Service Unavailable" if the server is temporarily not taking requests or another code.

6. Autodiscovery

The primary means of discovering that a site is equipped to receive comments through the Comment API is the existence of wfw:comment elements within the items in an RSS feed.

Another way to make this known is to use autodiscovery by putting a link element in the head of an HTML page, setting the rel attribute to "service.comment", the type to "text/xml", the href attribute to the URL that takes HTTP POST requests and the title to "Comment API" or some other explanatory text.

7. Credits

The Comment API Namespace for RSS was created by Chris Sells and Joe Gregorio. Comments and corrections regarding this document are encouraged on the RSS-Public mailing list.

8. License

Copyright 2024 RSS Advisory Board. This document titled Comment API Namespace for RSS is authored by the RSS Advisory Board, published at the URL https://www.rssboard.org/comment-api and shared under the terms of the Creative Commons Attribution/Share Alike license.