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
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, {
  lenient: true
})

Parameters

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

Options

Option	Type	Default	Description
lenient	boolean	false	Enable lenient mode for relaxed validation, see Lenient 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/types'

// 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

TDate represents date fields in the type definitions. When parsing, dates are returned as strings in their original format (see Parsing › Handling Dates for more details). When generating, dates should be provided as JavaScript Date objects.

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

  export type Attachment = {
    url: string
    mime_type: string
    title?: string
    size_in_bytes?: number
    duration_in_seconds?: number
  }

  export type Item<TDate extends DateLike> = {
    id: string
    url?: string
    external_url?: string
    title?: string
    content_html?: string
    content_text?: string
    summary?: string
    image?: string
    banner_image?: string
    date_published?: TDate
    date_modified?: TDate
    tags?: Array<string>
    authors?: Array<Author>
    language?: string
    attachments?: Array<Attachment>
  } & ({ content_html: string } | { content_text: string })

  export type Hub = {
    type: string
    url: string
  }

  export type Feed<TDate extends DateLike> = {
    title: string
    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>
    authors?: Array<Author>
    items: Array<Item<TDate>>
  }
}

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