Skip to content

Compare

Why not just use what already exists?

Syndication Manifest is one discovery option among several. Here is how it relates to the existing ones, and why a new document is worth the small surface it adds.

HTML <link rel="alternate"> autodiscovery

The classic mechanism: a feed reader fetches the page the user pasted, parses the HTML head, and picks up rel="alternate" links of type application/rss+xml or application/atom+xml.

Works well for one page, one feed. Breaks when a publication advertises different feeds on different pages, when the home page does not list every feed, or when the reader wants to enumerate feeds without scraping HTML. Syndication Manifest gives one publication-level answer that does not depend on which page was fetched.

HTTP Link headers

Servers can advertise feeds with Link: <url>; rel="alternate"; type="application/rss+xml". Same modelling problem as the HTML version: it is tied to the response the reader happened to fetch. Syndication Manifest documents are a single canonical resource, not a header on an unrelated page.

The two are complementary: a publisher MAY advertise the manifest itself with Link: </.well-known/syndication>; rel="syndication".

OPML

OPML is great for moving subscription lists between readers, and some publications expose an OPML catalogue. The trade-offs:

  • OPML is XML, which is heavier to parse from browser-based readers than JSON.
  • OPML has no widely adopted convention for advertising icons, categories, or deferred sub-collections.
  • OPML has no agreed well-known location, so it still needs discovery.

OPML remains the right tool for subscription import and export. Syndication Manifest is the right tool for publisher-declared discovery.

JSON Feed self-reference

JSON Feed includes a feed_url field so a reader that already has a feed can confirm its canonical URL. That is feed-level metadata, not a publication-level catalogue. It does not list a publication's other feeds, collections, or external feeds the publisher wants to advertise.

WebFinger and other well-known URIs

Syndication Manifest follows the RFC 8615 pattern of /.well-known/ URIs, the same approach used by WebFinger, oauth-authorization-server, security.txt, and many others. The convention is well understood by infrastructure operators and CDN configurations.

Why a JSON document at a fixed path?

  • One predictable URL. Readers do not have to fetch and parse HTML or guess paths like /feed, /rss, /atom.xml.
  • Publication-level scope. The document describes a publication's feeds, not one page's feeds.
  • Compact for browsers. JSON is cheap to parse client-side, which matters for web-based readers.
  • Room to grow. Collections, deferred sub-documents, translations, and extensions let large publications express structure without bloating the top-level document.