JSON Feed - JSON Feed Version 1.1

JSONfeed.org

by Brent Simmons and Manton Reece

The JSON Feed format is a pragmatic syndication format, like RSS and Atom, but with one big difference: it’s JSON instead of XML.

For most developers, JSON is far easier to read and write than XML. Developers may groan at picking up an XML parser, but decoding JSON is often just a single line of code.

Our hope is that, because of the lightness of JSON and simplicity of the JSON Feed format, developers will be more attracted to developing for the open web.

Here’s a simple example:

"version": "https://jsonfeed.org/version/1.1",<br>"title": "My Example Feed",<br>"home_page_url": "https://example.org/",<br>"feed_url": "https://example.org/feed.json",<br>"items": [<br>"id": "2",<br>"content_text": "This is a second item.",<br>"url": "https://example.org/second-item"<br>},<br>"id": "1",<br>"content_html": "Hello, world!",<br>"url": "https://example.org/initial-post"

It supports more than just the above, of course.

Goals

After making feeds easier to read and write, our second goal is to provide a format that’s self-documenting and difficult to do wrong.

We also want to support:

Microblogs, which are often plain text and without titles. So much web writing today is Twitter-like, which is actually plain text.

Multiple attachments.

Modern needs such as avatar images, feed icons and favicons, and banner and featured images. Feed readers should not have to search and scrape to guess at these things.

A simple way to add extensions.

(Note about plain text: on this page it means “not HTML” — emojis, for instance, are considered plain text.)

The Structure of a Feed

A JSON Feed is a list that may change over time, and the individual items in the list may change.

Think of a blog or microblog, Twitter or Facebook timeline, set of commits to a repository, or even a server log. These are all lists, and each could be described by a feed.

A JSON Feed starts with some info at the top: it says where the feed comes from, and may say who created it and so on.

After that there’s an array of objects — items — that describe each object in the list.

Top-level

version (required, string) is the URL of the version of the format the feed uses. This should appear at the very top, though we recognize that not all JSON generators allow for ordering.

title (required, string) is the name of the feed, which will often correspond to the name of the website (blog, for instance), though not necessarily.

home_page_url (optional but strongly recommended, string) is the URL of the resource that the feed describes. This resource may or may not actually be a “home” page, but it should be an HTML page. If a feed is published on the public web, this should be considered as required. But it may not make sense in the case of a file created on a desktop computer, when that file is not shared or is shared only privately.

feed_url (optional but strongly recommended, string) is the URL of the feed, and serves as the unique identifier for the feed. As with home_page_url, this should be considered required for feeds on the public web.

description (optional, string) provides more detail, beyond the title, on what the feed is about. A feed reader may display this text.

user_comment (optional, string) is a description of the purpose of the feed. This is for the use of people looking at the raw JSON, and should be ignored by feed readers.

next_url (optional, string) is the URL of a feed that provides the next n items, where n is determined by the publisher. This allows for pagination, but with the expectation that reader software is not required to use it and probably won’t use it very often. next_url must not be the same as feed_url, and it must not be the same as a previous next_url (to avoid infinite loops).

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. It should be square and relatively large — such as 512 x 512 pixels — so that it can be scaled-down and so that it can look good on retina displays. It should use transparency where appropriate, since it may be rendered on a non-white background.

favicon (optional, string) is the URL of an image for the feed suitable to be used in a source list. It should be square and relatively small, but not smaller than 64 x 64 pixels (so that it can look good on retina displays). As with icon, this image should use transparency where appropriate, since it may be rendered on a non-white background.

authors (optional, array of objects) specifies one or more feed authors. The author object has several members. These are all optional — but if you provide an author object, then at least one is required:

name (optional, string) is the author’s name.

url (optional, string) is the URL of a site owned by the author. It could be a blog, micro-blog, Twitter account, and so on. Ideally the linked-to page provides a way to contact the author, but that’s not required. The...