Tag Archives: json

JSON Feed

Really excited to announce JSON Feed today with Brent Simmons. It’s great to see all the feedback and links to new feeds. Special thanks to everyone who contributed to the spec, debating field names and requirements over the last few months.

The premise was simple: the time is right for a JSON-based approach to feeds. We hope that JSON Feed is straightforward enough to be implemented quickly, and capable enough to push the next decade of blogging software forward. We love RSS too and tried to learn from its success.

Micro.blog already supports JSON Feed nearly everywhere. There are feeds for hosted microblogs and your timeline, and the Micro.blog custom JSON API itself is actually just JSON Feed with Micro.blog-specific extensions.

I’m looking forward to seeing what everyone does with this. If you’ve shared any code or templates for JSON Feed, or if you’re working on apps to support it, let us know.

River5 and twtxt

Two new microblog-related services have launched. This week, Dave Winer announced River5:

“So I decided it was time to do a restart of my JavaScript RSS aggregator, and it’s now ready for Node users — it’s called River5. […] This is a foundation for developers to build on, but it’s also possible for an adventurous user to set up their own rivers.”

River5 is built on a few XML and JSON formats, including River.js. I’m pretty interested in River.js as a format for aggregating multiple feeds together, so I’ve supported it in my new microblog platform. As a next-generation RSS, though, I prefer the proposal I wrote about in a post called RSS for microblogs.

Next up is twtxt, which attempts to recreate Twitter as a distributed, command-line based system with self-hosted text files:

“Instead of signing up at a closed and/or regulated microblogging platform, getting your status updates out with twtxt is as easy as putting them in a publicly accessible text file. The URL pointing to this file is your identity, your account. twtxt then tracks these text files, like a feedreader, and builds your unique timeline out of them, depending on which files you track.”

I’m less sure what to think of twtxt. The simple plaintext format is nice, but we already have a good infrastructure for this with RSS. And as I’ve noted before, having HTML in RSS with inline styles and links is nice for microblogs, and it’s not clear to me whether that would fit well with twtxt.

If you want to start an indie microblog, my suggestion remains to use existing blog software that can generate simple RSS feeds. Short posts, no titles. This is a widely-deployed format that we can continue to work with for years to come.

RSS for microblogs

RSS is solid. It’s lasted a long time with very few changes, and forms the foundation for subscribing to weblogs and delivering podcasts. It’s huge and the open web is a much better place because RSS exists.

But even if RSS doesn’t need to change, some types of apps would be better off if we took a fresh look at the elements in an RSS feed. What is really needed, and when faced with multiple “correct” options, which should we choose? As more writers embrace microblogging, it’s an opportunity to simplify our feeds and tools.

This is my proposal for a bit of housekeeping around microblogging. It’s not a new format. It’s just a guide for producing the best RSS. I’d divided this proposal into 5 sections below.

Minimum viable elements

Look at the average RSS feed and there’s a lot of junk in it that most RSS readers ignore. While there’s nothing wrong with including extra XML elements, we should strive for a feed that is simple enough to be easily read. The fewer redundant and unused elements, the more consistently that different RSS readers will interpret it.

Here’s an example of an RSS feed whittled down to its essential elements. Most feeds should look like this by default, and only add additional elements from the RSS spec or RSS extensions when it’s absolutely required (such as the enclosure element for podcasting).

<rss version="2.0">
    <channel>
        <title>Manton Reece</title>
        <description>Manton's weblog.</description>
        <link>http://www.manton.org/</title>
        <item>
            <title></title>
            <description><![CDATA[
                <p>Hello world.</p>
            ]]></description>
            <pubDate>Fri, 04 Sep 2015 15:32:32 +0000</pubDate>
            <guid isPermalink="true">http://www.manton.org/2015/09/3007.html</guid>
            <link>http://www.manton.org/2015/09/3007.html</link>
            <author>@manton</author>
        </item>
        <item>
            ...
        </item>
    </channel>
</rss>

Title is optional

The existing RSS spec says that title is optional. In fact, in the early days of blogging, tools such as Radio Userland and Blogger didn’t even have titles. We got away from that with the popularity of Movable Type and WordPress, even though some modern apps like Tumblr still look at a title as unnecessary for certain post types.

With microblogging, the title will frequently be empty or missing. Do tweets have titles? No, and neither should short microblog posts published through a traditional blog platform. Skipping the title removes some friction in the writing process, making it easier to write a quick post and send it out.

RSS readers must be prepared for a title-less RSS item. Instead of inserting “Untitled” as the placeholder title, think about how your reading UI can accommodate microblog posts gracefully. Blank titles (where the title exists but is an empty string) are equivalent to a completely missing title element.

HTML post text

The description XML element in RSS wasn’t originally intended to support HTML. It was often a text summary or opening paragraph of an article, rather than full text. With microblogging, you always want the full text inside the RSS feed, including any styled text or inline HTML links.

Some feeds will include the plain text version of a post in the description element, and the HTML version in a content:encoded element, as specified by this RSS namespace extension. This should be avoided in favor of a single description element with the full HTML, using CDATA syntax to avoid escaping characters.

In modern apps, rendering simple HTML is common. If an RSS reader can’t show HTML, it should strip out the HTML tags itself. It’s not up to the feed to provide multiple versions. If both description and content:encoded are present in a feed while parsing, for compatibility it’s acceptable to prefer whichever includes HTML.

JSON

I said this isn’t a new format, but we should have the option of expressing RSS in JSON instead of XML format. Back in 2012, Dave Winer wrote about producing a JSON-based RSS feed, with a very literal mapping of elements. If our goal is to cleanup some of the edge cases of RSS, though, we can further simplify it. I’d suggest collapsing a few of the elements, so that it isn’t overly nested like XML, and to JSON-ify the item elements into a simple items array:

{
    "channel": {
        "title": "Manton Reece",
        "description": "Manton's weblog."
        "link": "http://www.manton.org/"
    },
    "items": [
        {
            "title": "",
            "description": "<p>Hello world.</p>",
            "pubDate": "Fri, 04 Sep 2015 15:32:32 +0000",
            "guid": "http://www.manton.org/2015/09/3007.html",
            "link": "http://www.manton.org/2015/09/3007.html",
            "author": "@manton"
        }
    ]
}

This preserves the element names and overall feel of RSS, while being cleaner and more JSON-like. Note that it’s easy to embed HTML directly in the JSON description field. Because there’s no room for an isPermalink attribute, if the guid is a URL, it is always the permalink.

Authors

A feed for a microblog platform, or a group weblog, might include multiple items each from different authors. The RSS spec says that the XML “author” element is an email address, but that is very rarely used in real feeds.

Instead, the author element value should vary slightly from the original specification to include either a simple full name, or a username prefixed with the @-sign: <author>Manton Reece</author> or <author>@manton</author>.

What do you think? I’d love to hear any feedback via email. If you write on your own blog about this, send me the link.