Skip to content

Latest commit

 

History

History
131 lines (92 loc) · 3.69 KB

parsing-version-data.md

File metadata and controls

131 lines (92 loc) · 3.69 KB
Raw

Parsing Version History from RSS, Atom & JSON Feeds

When version histories are supplied using structured formats like RSS, Atom, or JSON Feed, implementors will need to parse that data and render it into a web page. This document suggests how that should be done, with a focus on key fields for each history item.

Page Title

This identifies the purpose of the version history page. Alternatively, this could be the name of the app (taken from the Manifest) plus the text "Version History".

Markup Recommendation

  • h1

Extraction Path

RSS
rss > channel > title
Atom
feed > title
JSON Feed
object["title"]

Page Content (optional)

Valid RSS feeds will have descriptions, but neither Atom nor JSON Feed require it. Exposing this information should be considered optional.

Markup Suggestion(s)

  • p,
  • div, or
  • documentFragment (if the description contains flow-level elements).

Extraction Path

RSS
rss > channel > description
Atom
feed > description (if present)
JSON Feed
object["description"] (if present)

History Item

Each item in a version history should exist as a flow-level sectioning HTML element.

Markup Suggestion(s)

  • article,
  • section, or
  • details

Extraction Path

RSS
rss > channel > item (each item is a history item)
Atom
feed > entry (each entry is a history item)
JSON Feed
object["items"] (each object in this array is a history item)

History Item Version

This is a string that names the given version. In some apps it may be numeric, in others it may be a string, but for the purposes of the parser, it should be considered to be a string and would likely be rendered into a heading element.

Markup Suggestion(s)

  • h2,
  • summary (if details is used for an item),
  • etc.

Extraction Path

RSS
rss > channel > item > title
Atom
feed > entry > title
JSON Feed
object["items"][0].title falling back to object["items"][0].id

History Item Content

This is a string that describes significant changes in this version.

Markup Suggestion(s)

  • p,
  • div, or
  • documentFragment (if the description contains flow-level elements).

Extraction Path

RSS
rss > channel > item > description
Atom
feed > entry > content falling back to feed > entry > summary
JSON Feed
object["items"][0].content_html or object["items"][0].content_text (one of these must be present to be valid)

History Item Date

This is a representation of when the version was released and is optional.

Notes

  • Feed readers are instructed to ignore items with publish dates in the future.
  • Date formats will include the W3C’s scoped-down ISO 8601 (RSS & Atom) or follow RFC 3339 (JSON Feed).
  • JSON Feed does not require a date.

Markup Suggestion

  • time

Extraction Path

RSS
rss > channel > item > pubDate
Atom
feed > entry > published
JSON Feed
object["items"][0].date_published