2024-05-13 ⇒

The 'iffy' XML namespace

➣  This post was meaningfully revised at 2024-06-20 @ 11:05 AM EDT. The previous revision is here, diff here. (See update history.)
➣  This post is expected to evolve over time. You can subscribe to ongoing updates here.

I want to do a lot of things with RSS that require extensions of RSS (as the RSS spec foresees).

The URL http://tech.interfluidity.com/xml/iffy/ will mark an XML namespace in which some of these extensions will be defined.

The conventional prefix associated with this namespace will be iffy.

The current version of this namespace is v0.0.1-SNAPSHOT.

(-SNAPSHOT signifies that the version preceding that suffix has not yet been finalized. Much more to come!)

Table of Contents

Element — iffy:completeness

Solely a channel level element

Contains one of the following four values:

  1. Ping
  2. Metadata
  3. Content
  4. Media

iffy:completeness describes the completeness that clients should expect of RSS item elements.

  • Ping makes the least commitment. Items need not include a guid element, or any elements at all beyond RSS' requirement that at least one of title or description be present. RSS documents have completion Ping by default. Any or all items may meet the requirement for a higher completeness level, but no promises or commitment is made beyond the base specification.

  • Metadata commits that each item MUST include a guid element, as well as meeting the base requirements for an RSS item.

  • Content commits that each item, either inside its description tag, or via an extension such as content:encoded, includes the full content of the items it includes, suitable for independent rendering by any client capable also of resolving references to linked media externally. No limitation is placed on whether the full content is placed in a description element, in content:encoded, or in some other extension.

  • Media augments Content by embedding attachments to subsidiary media inside the RSS document. Subsidiary media does not include all potential links, just links which share a prefix with the current RSS document, which by default means all links subsidiary to the parent of the RSS document as specified in an atom:link

    More information on this soon when iffy:attachment is defined

The four values represent nested, hierarchical levels of commitment. Ping commits to nothing more than the spec requires. Media makes every commitment promised by the prior three levels, and an additional one.

If not specified, no commitment is made, the feed should be considered Ping.

Example:

<?xml version='1.0' encoding='UTF-8'?>

<rss version="2.0" xmlns:iffy="http://tech.interfluidity.com/xml/iffy/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>tech — interfluidity</title>
    <atom:link type="application/rss+xml" rel="self" href="https://tech.interfluidity.com/feed/index.rss"/>
    <iffy:completeness>Content</iffy:completeness>
    <!-- Other channel elements -->
    <item>
      <!-- Other item elements -->
    </item>
  </channel>
</rss>

Element — iffy:diff

When a subelement of iffy:update

MUST contain a URL, URI, or IRI of a human-reviewable a diff of the current updated and the final minor revision of the update prior (or of the initially published post, if the current update is the first declared update).

Example:

<iffy:diff>https://tech.interfluidity.com/xml/iffy/index-diff-394986cb8d9c57f567d324e691a44d50102101ce-to-13de0232319ceab2f830591c318089d18cbec78d.html</iffy:diff>

See also iffy:update-history example.

Element — iffy:hint-announce

When a subelement of item

Represents a hint to RSS consumers that "push" — announce, rebroadcast, or notify — items whether this item should be so pushed. Consumers are free to ignore this hint or make use of it as they wish.

MUST contain an iffy:policy element, whose values MUST BE one of

  • Always — the item should always be notified
  • Never — the item should never be notified
  • Piggyback — the item should be notified as part of digests or other announcements of multiple items, but should not constitute its own announcement.

MAY contain an iffy:restriction element, which represents an application-specific restriction over the consumers to which it is addressed. No restrictions are placed on the content of the iffy:restriction element. Applications can define restrictions as they see fit.

An iffy:hint-announce element with NO iffy:restriction or an empty iffy:restriction tag should be interpreted as the intended default for ALL applications not addressed by an iffy:hint-announce with a more specific restriction.

Multiple iffy:hint-announce elements may be placed within a single item, provided that only one has an omitted or empty iffy:restriction, and all iffy:hint-announce elements containing an iffy:restriction contain a unique restriction. Each iffy:restriction SHOULD apply to nonoverlapping application-specific contexts. If that is not the case, how applications prioritize or respond to conflicting iffy-hint-announce elements whose restrictions both apply must be determined by the application.

Example:

<iffy:hint-announce>
  <iffy:policy>Piggyback</iffy:policy>
</iffy:hint-announce>

Element — iffy:initial

When a subelement of iffy:update-history

MAY contain a sequence of dc:creator elements, defining the initial authorship of an item, if authorship has changed. Since the containing item should always reflect current authorship (that of the most recent revision), but no iffy:update element is defined for the initially published version, this container is required for completeness.

Example:

<iffy:initial>
  <!-- Perhaps more recent updates, and the current item, include more authors -->
  <dc:creator>First Author, Esq.</dc:creator>
</iffy:initial>

Element — iffy:policy

In general, represents a statement of some kind of policy with respect to its containing element, suggested to feed consumers for handling a feed or item.

When a subelement of iffy:hint-announce

Please see iffy:hint-announce.

Element — iffy:provenance

When an item level element

If present in an item, the item contains a sequence of one or more atom:link elements, each of whose

  • rel attribute is MUST BE via
  • href attribute MUST BE the URL of an RSS feed from which the base contents of this item were drawn
  • type attribute SHOULD BE application/rss+xml

If the item from which the current item was sourced does not contain an iffy:provenance, then the current item should include just one atom:link.

If the item from which the current item was sourced does contains an iffy:provenance, then the current feed SHOULD include all items of that element, with the URL of the feed from which the item was sourced PREPENDED.

This will ensure the most immediate source will be the first atom:link element. The origin — or at least the source for which no further provenance is known — will be the last atom:link element.

Processors may expect a channel level atom:link element with rel="self" and type="application/rss+xml" to use as the basis for provenance in source documents. See RSS Best Practices.

Example (from here):

<?xml version='1.0' encoding='UTF-8'?>

<rss version="2.0" xmlns:iffy="http://tech.interfluidity.com/xml/iffy/" xmlns:sy="http://purl.org/rss/1.0/modules/syndication/" xmlns:slash="http://purl.org/rss/1.0/modules/slash/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:wfw="http://wellformedweb.org/CommentAPI/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>interfluidity, all blogs</title>
    <!-- Other channel elements -->
    <atom:link type="application/rss+xml" rel="self" href="https://www.interfluidity.com/unify-rss/all-blogs.rss"/>
    <item>
      <title>Industrial policy and ecosystems</title>
      <guid isPermalink="true">https://drafts.interfluidity.com/2024/05/11/industrial-policy-and-ecosystems/index.html</guid>
      <author>nospam@dev.null (Steve Randy Waldman)</author>
      <link>https://drafts.interfluidity.com/2024/05/11/industrial-policy-and-ecosystems/index.html</link>
      <!-- Other item elements -->
      <iffy:provenance>
        <atom:link type="application/rss+xml" rel="via" href="https://drafts.interfluidity.com/feed/index.rss"/>
      </iffy:provenance>
    </item>
  </channel>
</rss>

Element — iffy:restriction

In general, represents an expressin of some kind of restriction over the application of its containing element.

When a subelement of iffy:hint-announce

Please see iffy:hint-announce.

Element — iffy:revision

MUST contain a URL, URI, or IRI of a either a fixed past revision or the current (potentially evolving) revision of an item.

Example:

<iffy:revision>https://tech.interfluidity.com/xml/iffy/index-oldcommit-13de0232319ceab2f830591c318089d18cbec78d.html</iffy:revision>

See also iffy:update-history example.

Element — iffy:synthetic

This element is intended to mark channels or items that are in some sense "synthetic", rather than, um, hand-made?

Can optionally contain an iffy-type, and other type-specific subelements.

When a subelement of channel

If all the items in a feed are automatically rather than human generated (however you want to define that), iffy:synthetic can mark an entire channel as synthetic, bot-produced.

Applications that include iffy:synthetic as a direct child of channel SHOULD NOT also mark individual items as iffy:synthetic, unless there is some meaningful sense in which some items are more synthetic than others. It serves no purpose to mark every item of a feed iffy:synthetic when the channel is already so marked.

Known types:

  • ItemUpdateFeed — A synthetic feed announcing updates of a particular logical item from another feed.

    Elements SHOULD also include an atom:link with rel attribute set to related, pointing to the same resource as the link element of the item whose updates are being announced.

When a subelement of item

Marks items as "synthetic", that is more synthetic than other, unmarked items in the feed.

Exactly what that means is not defined, but it should be relative to the other items in the feed. If every item in a feed is automatically generated — suppose a weather feed, announcing conditions on the hour — then those items should NOT be marked iffy:synthetic, because they are the usual for the feed. The channel as a whole might be marked iffy:synthetic.

When iffy:synthetic is a subelement of item, it is intended to distinguish more automatic from less automatically produced items. It serves no purpose if it is used to mark all items.

Known types:

  • UpdateAnnouncement — A synethetic item marking an update of an older item in the feed (or that once would have been in the feed)

Example — channel > iffy:synthetic > iffy:type (ItemUpdateFeed):

  <channel>
    <!-- other channel elements -->
    <iffy:synthetic>
      <iffy:type>ItemUpdateFeed</iffy:type>
      <atom:link rel="related" href="https://tech.interfluidity.com/xml/iffy/index.html"/>
    </iffy:synthetic>
  </channel>

Example — item > iffy:synthetic > iffy:type (UpdateAnnouncement):

  <item>
    <!-- other item elements -->
    <iffy:synthetic>
      <iffy:type>UpdateAnnouncement</iffy:type>
    </iffy:synthetic>
  </item>

Element — iffy:type

In general, marks the "type" of its containing element.

When a subelement of channel > iffy:synthetic

Marks what kind of synthetic channel its parent is. Currently known values include

  • ItemUpdateFeed — A synthetic feed announcing updates of a particular logical item from another feed.

When a subelement of item > iffy:synthetic

Marks what kind of synthetic item its parent is. Currently known values include

  • UpdateAnnouncement — A synethetic item marking an update of an older item in the feed (or that once would have been in the feed)

Please see known containing elements, including

Element — iffy:update

When a sub-element of iffy:update-history

MUST contain one atom:updated element.

MAY also contain one each of

MAY, but usually will not, contain any number of dc:creator elements, reflecting authorship specific to this revision. By default, an update's authors are the same as the authorship of the containing item, which always reflects the curren revisions authors. If authorship is evolving over time, it SHOULD be specified for every update except the most recent one. Initial authorship may be specified in an iffy:initial element.

Typo fixes, small rephrasings, and other tweaks are not expected to be recorded as distinct updates. That is, within a "single update" there may be a sequence of smaller revisions that go unrecorded. Applications that want a more forensic history might consider including and exposing every published change in version control.

See iffy:update-history example.

Element — iffy:update-history

When an item level element

SHOULD contain a sequence of iffy:update elements, in reverse chronological order, describing the histories of major revisions to an item.

MAY contain one iffy:initial element.

Items containing an iffy:update-history SHOULD also include an atom:updated tag corresponding to the most recent update.

Typo fixes, small rephrasings, and other minor tweaks are not expected to be recorded as distinct updates. That is, within a "single update" there may be a sequence of smaller revisions that go unrecorded. Applications that want a more forensic history might consider including and exposing every published change in version control.

Example:

<item>
  <!-- Other item elements -->
  <iffy:update-history>
    <iffy:update>
      <atom:updated>2024-06-02T04:20:00Z</atom:updated>
      <atom:summary>
        <![CDATA[Drop <code>iffy:timestamp</code>. We can just reuse <code>atom:updated</code> for the same work.]]>
      </atom:summary>
      <iffy:revision>
        https://tech.interfluidity.com/xml/iffy/index-oldcommit-199e44561de3fd9e731a335d8b2a655f42d9bc04.html
      </iffy:revision>
      <iffy:diff>
        https://tech.interfluidity.com/xml/iffy/index-diff-199e44561de3fd9e731a335d8b2a655f42d9bc04-to-current.html
      </iffy:diff>
    </iffy:update>
    <iffy:update>
      <atom:updated>2024-06-02T01:35:00Z</atom:updated>
      <atom:summary><![CDATA[Add initial take on tags related to updates and revisions.]]></atom:summary>
      <iffy:revision>
        https://tech.interfluidity.com/xml/iffy/index-oldcommit-72eaf9fdfebc9e627bff33bbe1102d4d250ad1d0.html
      </iffy:revision>
      <iffy:diff>
        https://tech.interfluidity.com/xml/iffy/index-diff-72eaf9fdfebc9e627bff33bbe1102d4d250ad1d0-to-199e44561de3fd9e731a335d8b2a655f42d9bc04.html
      </iffy:diff>
    </iffy:update>
    <iffy:update>
      <atom:updated>2024-05-26T03:00:00Z</atom:updated>
      <atom:summary><![CDATA[Add JS/CSS so that prior revisions are visually distinct from current.]]></atom:summary>
      <iffy:revision>
        https://tech.interfluidity.com/xml/iffy/index-oldcommit-13de0232319ceab2f830591c318089d18cbec78d.html
      </iffy:revision>
      <iffy:diff>
        https://tech.interfluidity.com/xml/iffy/index-diff-13de0232319ceab2f830591c318089d18cbec78d-to-72eaf9fdfebc9e627bff33bbe1102d4d250ad1d0.html
      </iffy:diff>
    </iffy:update>
    <iffy:update>
      <atom:updated>2024-05-24T04:25:00Z</atom:updated>
      <atom:summary>
        <![CDATA[Drop tags <code>iffy:when-updated</code> and <code>iffy:original-guid</code>, bad appraoch to updates.]]>
      </atom:summary>
      <iffy:revision>
        https://tech.interfluidity.com/xml/iffy/index-oldcommit-394986cb8d9c57f567d324e691a44d50102101ce.html
      </iffy:revision>
      <iffy:diff>
        https://tech.interfluidity.com/xml/iffy/index-diff-394986cb8d9c57f567d324e691a44d50102101ce-to-13de0232319ceab2f830591c318089d18cbec78d.html
      </iffy:diff>
    </iffy:update>
  </iffy:update-history>
</item>
Last major update at 2024-06-20 @ 11:05 AM EDT
↑↑↑

Major revisions:

Timestamps represent "major", substantative revisions. There may have been subsequent typo fixes and language reworkings within a major revision, after the time displayed. For a more complete and fine-grained update history, you can view the git repository commit history. The most recent minor modification of this entry occurred 2024-06-20 @ 11:04 AM EDT.