JSON Feed Reference

JSON Feed is a syndication format based on JSON that provides a simple, straightforward way to publish feeds. Feedsmith provides full parsing and generation capabilities.

Versions	1.0, 1.1
Specification	JSON Feed 1.1 Specification
Namespaces	None (JSON-based format)

Functions

parseJsonFeed()

Parses JSON Feed content and returns a typed JSON Feed object.

import { parseJsonFeed } from 'feedsmith'

const jsonFeed = parseJsonFeed(jsonContent)
// Returns: object with all fields optional and dates as strings

// Limit number of items parsed
const jsonFeed = parseJsonFeed(jsonContent, { maxItems: 10 })

Parameters

Parameter	Type	Description
content	string	The JSON Feed content to parse
options	object	Optional parsing settings

Options

Option	Type	Default	Description
maxItems	number	-	Limit the number of items parsed. Use 0 to skip items entirely, useful when only feed metadata is needed

Returns

object - Parsed JSON Feed with all fields optional and dates as strings

generateJsonFeed()

Generates JSON Feed from feed data.

import { generateJsonFeed } from 'feedsmith'

const json = generateJsonFeed(feedData)

Parameters

Parameter	Type	Description
data	object	JSON Feed data to generate
options	object	Optional generation settings

Options

Option	Type	Default	Description
strict	boolean	false	Enable strict mode for spec-required field validation, see Strict Mode

Returns

object - Generated JSON Feed

detectJsonFeed()

Detects if the provided content is a JSON Feed.

Parameters

Parameter	Type	Description
content	string	The content to check

Returns

boolean - true if content appears to be JSON Feed format

Example

import { detectJsonFeed } from 'feedsmith'

const isJsonFeed = detectJsonFeed(jsonContent)

Types

All JSON Feed types are available under the Json namespace:

import type { Json } from 'feedsmith'

// Access any type from the definitions below
type Feed = Json.Feed<Date>
type Item = Json.Item<Date>
type Author = Json.Author
type Attachment = Json.Attachment
// … see type definitions below for all available types

See the TypeScript guide for usage examples.

Type Definitions

INFO

For details on type parameters (TDate, TStrict) and Requirable<T> markers, see TypeScript Reference.

export namespace Json {
  export type Author = {
    name?: string
    url?: string
    avatar?: string
  }

  export type Attachment<TStrict extends boolean = false> = Strict<
    {
      url: Requirable<string> // Required in spec.
      mime_type: Requirable<string> // Required in spec.
      title?: string
      size_in_bytes?: number
      duration_in_seconds?: number
    },
    TStrict
  >

  export type Item<TDate extends DateLike, TStrict extends boolean = false> = Strict<
    {
      id: Requirable<string> // Required in spec.
      url?: string
      external_url?: string
      title?: string
      content_html?: string // At least one of content_html or content_text is required in spec.
      content_text?: string // At least one of content_html or content_text is required in spec.
      summary?: string
      image?: string
      banner_image?: string
      date_published?: TDate
      date_modified?: TDate
      tags?: Array<string>
      authors?: Array<Author>
      language?: string
      attachments?: Array<Attachment<TStrict>>
    },
    TStrict
  > &
    (TStrict extends true ? { content_html: string } | { content_text: string } : unknown)

  export type Hub<TStrict extends boolean = false> = Strict<
    {
      type: Requirable<string> // Required in spec.
      url: Requirable<string> // Required in spec.
    },
    TStrict
  >

  export type Feed<TDate extends DateLike, TStrict extends boolean = false> = Strict<
    {
      title: Requirable<string> // Required in spec.
      home_page_url?: string
      feed_url?: string
      description?: string
      user_comment?: string
      next_url?: string
      icon?: string
      favicon?: string
      language?: string
      expired?: boolean
      hubs?: Array<Hub<TStrict>>
      authors?: Array<Author>
      items: Requirable<Array<Item<TDate, TStrict>>> // Required in spec.
    },
    TStrict
  >
}

Related

• Parsing JSON Feeds - How to parse JSON Feed content
• Generating JSON Feeds - How to create JSON feeds
• JSON Feed Detection - Detecting JSON Feed format