RSSFeeds.com

JSON Feed 1.1 Explained

JSON Feed is a feed format written in JSON instead of XML. Created by Brent Simmons and Manton Reece in 2017 and updated to version 1.1 in 2020, it is easy to read, easy to generate and supported by most modern readers.

Updated

Illustration of a JSON document representing a JSON Feed

JSON Feed at a Glance

Current version1.1 (August 2020), version string https://jsonfeed.org/version/1.1
Specificationjsonfeed.org/version/1.1
MIME typeapplication/feed+json (1.0 used application/json)
Date formatRFC 3339, e.g. 2026-11-11T09:00:00+01:00
ExtensionsAny key starting with an underscore, such as _myapp

A Minimal JSON Feed

feed.json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Example Blog",
  "home_page_url": "https://example.com/",
  "feed_url": "https://example.com/feed.json",
  "items": [
    {
      "id": "https://example.com/why-feeds-matter",
      "url": "https://example.com/why-feeds-matter",
      "title": "Why feeds still matter",
      "content_html": "<p>The full article.</p>",
      "date_published": "2026-11-11T09:00:00Z"
    }
  ]
}

Top-Level Fields

FieldDescription
versionrequiredThe URL of the version of the spec: https://jsonfeed.org/version/1.1.
titlerequiredThe name of the feed.
itemsrequiredAn array of items. May be empty.
home_page_urlrecommendedThe website the feed belongs to.
feed_urlrecommendedThe URL of the feed itself, so readers can find it again if it moves.
descriptionoptionalMore detail about the feed.
user_commentoptionalA note for people who open the file, e.g. "This is a feed. Use a feed reader."
next_urloptionalURL of the next page, for paginated feeds.
iconoptionalA large square image, at least 512×512, for use in timelines.
faviconoptionalA small square image, for use in source lists.
authorsoptionalArray of author objects with name, url and avatar. New in 1.1.
languageoptionalLanguage tag, e.g. en-US. New in 1.1.
expiredoptionaltrue if the feed will never be updated again.
hubsoptionalArray of {"type": "WebSub", "url": "…"} objects for real-time notifications.

Item Fields

FieldDescription
idrequiredUnique, permanent ID. A string; the URL is a fine choice.
content_html / content_textone requiredThe content as HTML, as plain text, or both.
urlrecommendedThe permalink of the item.
external_urloptionalFor link posts: the page the item is about.
titleoptionalLeave out for microblog posts without titles.
summaryoptionalA plain-text summary.
imageoptionalThe main image of the item.
banner_imageoptionalAn image to show at the top of the item.
date_published, date_modifiedrecommendedRFC 3339 dates.
authorsoptionalSame structure as the top-level authors.
tagsoptionalArray of strings.
languageoptionalLanguage of this item, if it differs from the feed.
attachmentsoptionalArray of files, see below.

Attachments and Podcasts

"attachments": [
  {
    "url": "https://example.com/audio/episode-42.mp3",
    "mime_type": "audio/mpeg",
    "title": "Episode 42",
    "size_in_bytes": 48211968,
    "duration_in_seconds": 3012
  }
]

url and mime_type are required. Unlike RSS, an item can have several attachments, for example the same episode in MP3 and AAC. Note that Apple Podcasts and most podcast directories only accept RSS, so podcasters should publish RSS (and may add JSON Feed alongside).

What Changed in Version 1.1

  • authors (an array) replaces author, so items can have several authors. Keep author as well if you want to support old readers.
  • New language field on the feed and on items.
  • The MIME type application/feed+json was introduced.
  • Clarifications throughout the spec, for example that item IDs must be strings.
Comparison chart of RSS 2.0, Atom 1.0 and JSON Feed 1.1: syntax, required fields, dates, IDs and podcast support
RSS 2.0, Atom and JSON Feed compared.

Generating JSON Feed in PHP

feed.json.php
<?php
$posts = $pdo->query('SELECT slug, title, body, published_at FROM posts ORDER BY published_at DESC LIMIT 20')->fetchAll(PDO::FETCH_ASSOC);
header('Content-Type: application/feed+json; charset=utf-8');
echo json_encode([
    'version' => 'https://jsonfeed.org/version/1.1',
    'title' => 'Example Blog',
    'home_page_url' => 'https://example.com/',
    'feed_url' => 'https://example.com/feed.json',
    'items' => array_map(fn($p) => [
        'id' => 'https://example.com/posts/' . $p['slug'],
        'url' => 'https://example.com/posts/' . $p['slug'],
        'title' => $p['title'],
        'content_html' => $p['body'],
        'date_published' => date(DATE_ATOM, strtotime($p['published_at'])),
    ], $posts),
], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

No escaping or CDATA: json_encode takes care of everything. Compare that with the RSS version in How to Create an RSS Feed.

Who Supports JSON Feed?

Many modern readers, including NetNewsWire and Feedbin, read JSON Feed natively, and Micro.blog publishes it. Support in older readers, aggregators, email tools and automation platforms is less complete than for RSS, which is why most publishers offer JSON Feed next to RSS. Our Feed Converter and API read JSON Feed everywhere.

Publishing a JSON Feed

Serve the file with Content-Type: application/feed+json and announce it in the page head:

<link rel="alternate" type="application/feed+json" title="Example Blog" href="https://example.com/feed.json">

Generating JSON Feed is trivial in any language: build an array and encode it. You never need to escape XML or wrap HTML in CDATA. Many publishers offer JSON Feed next to RSS rather than instead of it. Convert an existing feed with the Feed Converter and check the result with the Feed Validator.

Sources and Further Reading