JSON Feed Specification

The JSON Feed ecosystem includes various implementations across multiple programming languages and content management systems. You can find libraries for parsing and generating feeds, as well as plugins for static site generators and CMS platforms.

Key categories include:

• CMS Plugins: WordPress, Drupal, Craft CMS, Movable Type, Pelican, Eleventy, and Metalsmith.
• Static Site Generators: Jekyll, Hugo, Pelican, and MkDocs.
• Language Libraries:
  • Go: st3fan/jsonfeed, kr/jsonfeed, gopherlibs/jsonfeed.
  • Rust: jsonfeed, feed-rs, json-feed-model.
  • PHP: php-json-feed, jdecool/jsonfeed, feed-io.
  • Ruby: feedparser gem, feedjira gem.
  • Swift: totocaster/JSONFeed, wesbillman/JSONFeed.
  • C#: gramgibson/jsonfeed, DanRigby/JsonFeed.NET.
  • Python: jsonfeedvalidator.
  • Scala: chobeat/scala-json-feed.
  • Perl5: JSON::Feed.
• Converters: Tools to convert RSS/Atom to JSON Feed (e.g., feed2json.org) or JSON Feed to Atom/RSS.

When developing a feed reader, follow these pragmatic rules for handling data:

• Invalid JSON: Do not attempt to parse or use partial data from invalid JSON.
• Missing IDs: Mandatory. Any item without an id must be discarded. Without a unique identifier, it is impossible to track changes or prevent duplicate entries.
• Missing MIME types: If an attachment is missing a mime_type, you can attempt to infer it from the file suffix or the browser's download response.
• Malformed Dates: If date_published cannot be parsed, you may substitute the date the reader parsed the item.
• URL Selection: Use the url field as the default link (as it is a permalink). If an external_url is present, you may offer the user a choice or prioritize it in the UI.
• Efficiency: Use Conditional GET to minimize bandwidth and CPU usage.

Publishers can include custom data in a JSON Feed using extension objects. To ensure compatibility, follow these rules:

• Naming: The extension name must start with an underscore (_) followed by a letter (e.g., _blue_shed).
• Constraints: The extension name and its member keys must not contain any . (period) characters. Member keys should be alphanumeric.
• Location: Extensions can appear anywhere in the feed (top-level or within items).
• Documentation: It is recommended to include an about string within the extension object to explain its purpose to humans. This is optional but helpful.
• Compatibility: Feed readers that do not recognize an extension must ignore it.

Example extension:

"_blue_shed": {
	"about": "https://blueshed-podcasts.com/json-feed-extension-docs",
	"explicit": false,
	"copyright": "1948 by George Orwell",
	"owner": "Big Brother and the Holding Company",
	"subtitle": "All shouting, all the time. Double. Plus. Good."
}

RSS item objects map to JSON Feed items. Follow these specific transformations:

• title $\rightarrow$ title (Must be plain text in JSON Feed)
• link $\rightarrow$ url (the permalink to the content) AND external_url (if the item is a link to another page, e.g., a linkblog)
• description $\rightarrow$ content_html OR content_text (choose based on content type)
• guid $\rightarrow$ id
• author (single value) $\rightarrow$ author (object with name, url, and avatar)
• pubDate $\rightarrow$ date_published (Convert to RFC 3339 format, e.g., 2010-02-07T14:04:00-05:00)
• enclosure $\rightarrow$ attachments array. Map attributes as follows:
  • url $\rightarrow$ url
  • length $\rightarrow$ size_in_bytes
  • type $\rightarrow$ mime_type
  • (JSON Feed also allows adding title and duration_in_seconds)
• category $\rightarrow$ tags (Note: RSS domain attributes have no equivalent in JSON Feed)

Atom entry objects map to JSON Feed items. Use the following mappings:

• title $\rightarrow$ title (Must be plain text)
• id $\rightarrow$ id
• summary $\rightarrow$ summary (Must be plain text)
• Content mapping based on Atom type attribute:
  • type="html" or type="xhtml" $\rightarrow$ content_html
  • type="text" $\rightarrow$ content_text
• link (with rel="alternate") $\rightarrow$ url
• link (with rel="related") $\rightarrow$ external_url
• author (containing name, uri, email) $\rightarrow$ author (object with name, url, and avatar)
• published $\rightarrow$ date_published (Both use RFC 3339)
• updated $\rightarrow$ date_modified (Both use RFC 3339)
• link (with rel="enclosure") $\rightarrow$ attachments array. Map attributes as follows:
  • href $\rightarrow$ url
  • length $\rightarrow$ size_in_bytes
  • type $\rightarrow$ mime_type
  • (JSON Feed also allows adding title and duration_in_seconds)