Atom Feed Reference

Atom is a syndication format based on XML that provides a robust framework for web feeds. Feedsmith provides comprehensive parsing and generation capabilities.

Versions	0.3, 1.0
Namespaces	Dublin Core, Syndication, Slash, iTunes, Podlove Simple Chapters, Google Play Podcast, Media RSS, W3C Basic Geo, GeoRSS Simple, Atom Threading, Atom Publishing Protocol, Dublin Core Terms, Comment API, Administrative, Pingback, Trackback, ccREL, Creative Commons, OpenSearch, arXiv, YouTube

Functions

parseAtomFeed()

Parses Atom feed content and returns a typed Atom object.

import { parseAtomFeed } from 'feedsmith'

const atomFeed = parseAtomFeed(xmlContent)
// Returns: object with all fields optional and dates as strings

// Limit number of entries parsed
const atomFeed = parseAtomFeed(xmlContent, { maxItems: 10 })

Parameters

Parameter	Type	Description
content	string	The Atom XML content to parse
options	object	Optional parsing settings

Options

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

Returns

object - Parsed Atom feed with all fields optional and dates as strings

generateAtomFeed()

Generates Atom XML from feed data.

import { generateAtomFeed } from 'feedsmith'

const xml = generateAtomFeed(feedData, {
  lenient: true,
  stylesheets: [{ type: 'text/xsl', href: '/feed.xsl' }]
})

Parameters

Parameter	Type	Description
data	object	Atom 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
stylesheets	Stylesheet[]	-	Add stylesheets for visual formatting, see Feed Styling

Returns

string - Generated Atom XML

detectAtomFeed()

Detects if the provided content is an Atom feed.

Parameters

Parameter	Type	Description
content	string	The content to check

Returns

boolean - true if content appears to be Atom format

Example

import { detectAtomFeed } from 'feedsmith'

const isAtom = detectAtomFeed(xmlContent)

Types

All Atom types are available under the Atom namespace:

import type { Atom } from 'feedsmith/types'

// Access any type from the definitions below
type Feed = Atom.Feed<Date>
type Entry = Atom.Entry<Date>
type Link = Atom.Link
type Person = Atom.Person
// … 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 Atom {
  // For simplicity's sake, a string is used for now, but this may be reconsidered in the future.
  export type Text = string

  export type Link<TDate extends DateLike> = {
    href: string
    rel?: string
    type?: string
    hreflang?: string
    title?: string
    length?: number
    thr?: ThrNs.Link<TDate>
  }

  export type Person = {
    name: string
    uri?: string
    email?: string
    arxiv?: ArxivNs.Author
  }

  export type Category = {
    term: string
    scheme?: string
    label?: string
  }

  export type Generator = {
    text: string
    uri?: string
    version?: string
  }

  export type Source<TDate extends DateLike> = {
    authors?: Array<Person>
    categories?: Array<Category>
    contributors?: Array<Person>
    generator?: Generator
    icon?: string
    id?: string
    links?: Array<Link<TDate>>
    logo?: string
    rights?: Text
    subtitle?: Text
    title?: Text
    updated?: TDate
  }

  export type Entry<TDate extends DateLike> = {
    authors?: Array<Person>
    categories?: Array<Category>
    content?: Text
    contributors?: Array<Person>
    id: string
    links?: Array<Link<TDate>>
    published?: TDate
    rights?: Text
    source?: Source<TDate>
    summary?: Text
    title: Text
    updated: TDate
    app?: AppNs.Entry<TDate>
    arxiv?: ArxivNs.Entry
    cc?: CcNs.ItemOrFeed
    dc?: DcNs.ItemOrFeed<TDate>
    slash?: SlashNs.Item
    itunes?: ItunesNs.Item
    googleplay?: GooglePlayNs.Item
    psc?: PscNs.Item
    media?: MediaNs.ItemOrFeed
    georss?: GeoRssNs.ItemOrFeed
    geo?: GeoNs.ItemOrFeed
    thr?: ThrNs.Item
    dcterms?: DcTermsNs.ItemOrFeed<TDate>
    creativeCommons?: CreativeCommonsNs.ItemOrFeed
    wfw?: WfwNs.Item
    yt?: YtNs.Item
    pingback?: PingbackNs.Item
    trackback?: TrackbackNs.Item
  }

  export type Feed<TDate extends DateLike> = {
    authors?: Array<Person>
    categories?: Array<Category>
    contributors?: Array<Person>
    generator?: Generator
    icon?: string
    id: string
    links?: Array<Link<TDate>>
    logo?: string
    rights?: Text
    subtitle?: Text
    title: Text
    updated: TDate
    entries?: Array<Entry<TDate>>
    cc?: CcNs.ItemOrFeed
    dc?: DcNs.ItemOrFeed<TDate>
    sy?: SyNs.Feed<TDate>
    itunes?: ItunesNs.Feed
    googleplay?: GooglePlayNs.Feed
    media?: MediaNs.ItemOrFeed
    georss?: GeoRssNs.ItemOrFeed
    geo?: GeoNs.ItemOrFeed
    dcterms?: DcTermsNs.ItemOrFeed<TDate>
    creativeCommons?: CreativeCommonsNs.ItemOrFeed
    opensearch?: OpenSearchNs.Feed
    yt?: YtNs.Feed
    admin?: AdminNs.Feed
    pingback?: PingbackNs.Feed
  }
}

Related

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