JSON Feed is a new take on the web syndication format, but unlike RSS and Atom it's in JSON, not XML. So what does it try to do better?
Mainly overcome the perils of XML; it's complex, heavyweight, difficult to parse and not in sync with the current trend wanting web data exchange happening almost exclusively in JSON document representation.
Devised by Brent Simmons, the original developer of the popular NetNewsWire and Manton Reece creator of Micro Blogs, both with a great background on publishing with RSS, it's a certainty that JSON Feed will emerge as a strong competitor to both Atom and RSS, being based upon their decade long experience on decentralized formats.
On top of that it also tries to tackle a few other issues plaguing RSS, mainly the lack of realtime client notification when content updates, as well as the feed demanding the presence of title headers for its items, something that renders RSS not compatible with social media services like Twitter or micro blogs.
A JSON Feed is built around a master-detail view, with the detail itself being further expanded.The master view comprises of the Top-level elements that identify the feed by attaching information the likes of where it comes from or who created it to it:
version (required, string) is the URL of the version of the format the feed uses.
title (required, string) is the name of the feed.
home_page_url (optional but strongly recommended, string) is the URL of the resource that the feed describes.
feed_url (optional but strongly recommended, string) is the URL of the feed, and serves as the unique identifier for the feed.
description (optional, string) provides more detail, beyond the title, on what the feed is about.
user_comment (optional, string) is a description of the purpose of the feed.
next_url (optional, string) is the URL of a feed that provides the next n items, where n is determined by the publisher.
icon (optional, string) is the URL of an image for the feed suitable to be used in a timeline, much the way an avatar might be used.
favicon (optional, string) is the URL of an image for the feed suitable to be used in a source list.
author (optional, object) specifies the feed author.
expired (optional, boolean) says whether or not the feed is finished — that is, whether or not it will ever update again.
hubs (very optional, array of objects) describes endpoints that can be used to subscribe to real-time notifications from the publisher of this feed.Those hubs can then send a notification to the application as soon as the feed is updated. It includes a type field which describes the protocol used to talk with the hub, such as “rssCloud” or “WebSub.”
The Detail comes in the shape of the Item, an array of objects comprising of :
url (optional, string) is the URL of the resource described by the item.
external_url (very optional, string) is the URL of a page elsewhere.
title (optional, string) is plain text. Microblog items in particular may omit titles.
content_html and content_text are each optional strings — but one or both must be present.
summary (optional, string) is a plain text sentence or two describing the item.
image (optional, string) is the URL of the main image for the item.
banner_image (optional, string) is the URL of an image to use as a banner.
date_published (optional, string) specifies the date in RFC 3339 format.
date_modified (optional, string) specifies the modification date in RFC 3339 format.
author (optional, object) has the same structure as the top-level author.
tags (optional, array of strings) can have any plain text values you want.
This detail view is further expanded into the Item's Attachments, where an individual item may have one or more attachments.That is to cater for the web syndication's modern needs, such as hosting avatar images, feed icons and favicons, banner and featured images.Podcasts, for instance, would include an attachment that’s an audio or video file while feed readers should not have to search and scrape to guess at these things.
Each attachment has several members such as url, mime_type, title, size_in_bytes, duration_in_seconds.
An example of a podcast:
"user_comment": "This is a podcast feed. You can add this feed to your podcast client using the following URL: http://therecord.co/feed.json",
"title": "The Record",
"title": "Special #1 - Chris Parrish",
"content_text": "Chris has worked at Adobe and as a founder of Rogue Sheep, which won an Apple Design Award for Postage. Chris’s new company is Aged & Distilled with Guy English — which shipped Napkin, a Mac app for visual collaboration. Chris is also the co-host of The Record. He lives on Bainbridge Island, a quick ferry ride from Seattle.",
"content_html": "Chris has worked at Adobe and as a founder of Rogue Sheep, which won an Apple Design Award for Postage. Chris’s new company is Aged & Distilled with Guy English — which shipped Napkin, a Mac app for visual collaboration. Chris is also the co-host of The Record. He lives on Bainbridge Island, a quick ferry ride from Seattle.",
"summary": "Brent interviews Chris Parrish, co-host of The Record and one-half of Aged & Distilled.",
"url": "http://therecord.co/downloads/ The-Record-sp1e1-ChrisParrish.m4a",
Other than that,a feed can also include custom information through the use of custom Extensions.
Despite the new format's versatility it doesn't come free of controversy as client applications are expected to handle it as plain JSON, using the usual MIME type application/json.This means that it doesn't come with any semantics attached, as such the client could very well be not able to distinguish whether it's asked to handle a JSON feed, which relies on a defined schema, or a plain JSON object.
This has been already raised as an issue on the projects GitHub repository, asking for the introduction of a new MIME type that is going to be more specific and denote its purpose.application/feed+json is the proposed one.
Of course adoption of the new format is crucial and despite still being in its very early stages, it's quickly gaining ground as services like Feedbin and NewsBlur add support for it.
Brett Simons is already working on a JSON Feed parser for Swift, to be published on GitHub along his RSXML repository for Objective-C code that reads RSS, Atom, and OPML, while there's already code and templates for popular languages and web frameworks out on the open, including brand new feed readers.The latest addition to that list is a RSS/Atom to JSON Feed converter accessible over at feed2json.