2024-05-13 ⇒

The 'iffy' XML namespace

➣  This post was meaningfully revised at 2024-11-02 @ 05:15 PM 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

In general, describes the initial state of the item referred to by the element that contains it.

MAY contain any or all of

  • an atom:title element, containing the initial title of the item, which may have since been revised.
  • an atom:link element, containing the initial link to the item, which may have since been revised.
  • an iffy:uid element, containing the guid of the item that has been updated.
  • an atom:published element containing the date-time of initial publication
  • a sequence of dc:creator elements, describing the initial authorship of an item, which may since have been revised.

Note: We define an iffy:uid element, rather than rely upon atom:id, because atom:id requires that its contents be an IRI, but we mean to impose no such restriction.

When a subelement of item > iffy:update-history

An iffy:initial MAY BE included under item > iffy:update-history, but is recommended ONLY IF the title, authorship, or link have changed.

Since item > guid and item > pubDate never change, generators SHOULD NOT include these items under item > iffy:update-history. They are available directly in the containing item.

Example:

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

When a subelement of item > iffy:synthetic > iffy:update AND iffy:type of the synthetic element is UpdateAnnouncement

An iffy:initial MUST BE provided containing all of the analogous values defined in the item whose update the announcement describes.

This information would not be otherwise available, because values in the parent item describe the synthetic update announcement post, rather than the post whose update is announced.

  • If an item > title is defined in the post that was updated, that MUST BE recorded as atom:title
  • If an item > link is defined in the post that was updated, that MUST BE recorded as atom:link
  • If an item > guid is defined in the post that was updated, that MUST BE recorded as iffy:uid
  • If an item > pubDate is defined in the post that was updated, that MUST BE recorded as atom:published
  • If an item > dc:creator is defined in the post that was updated, that MUST BE recorded as dc:creator If, in the post that was updated, authorship was defined using item > author or item > atom:author those items should be converted into a form appropriate for dc:creator elements.

Example:

<item>
  <pubDate>Thu, 20 Jun 2024 13:10:00 -0400</pubDate>
  <guid isPermalink="true">
    https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index-updated-2024-06-20-13-10-00.html
  </guid>
  <link>https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index-updated-2024-06-20-13-10-00.html</link>
  <title>Updated: Feedletter tutorial</title>
  <!-- other item elements -->
  <iffy:synthetic>
    <iffy:type>UpdateAnnouncement</iffy:type>
    <iffy:update>
      <atom:updated>2024-06-20T17:10:00Z</atom:updated>
      <!-- other iffy:updated elements -->
      <iffy:initial>
        <atom:title><![CDATA[Feedletter tutorial]]></atom:title>
        <atom:link href="https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index.html"/>
        <iffy:uid>https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index.html</iffy:uid>
        <atom:published>2024-01-29T15:30:00Z</atom:published>
        <dc:creator><![CDATA[Steve Randy Waldman]]></dc:creator>
      </iffy:initial>
    </iffy:update>
  </iffy:synthetic>
  <dc:creator><![CDATA[Update-o-Bot]]></dc:creator>
</item>

When a subelement of item > iffy:synthetic > iffy:update-history AND iffy:type of the synthetic element is UpdateCumulation

An iffy:initial MUST BE provided containing all of the analogous values defined in the item whose update the announcement describes.

This information would not be otherwise available, because values in the parent item describe the synthetic update cumulation (summary) post, rather than the post whose update history is documented.

  • If an item > title is defined in the post that was updated, that MUST BE recorded as atom:title
  • If an item > link is defined in the post that was updated, that MUST BE recorded as atom:link
  • If an item > guid is defined in the post that was updated, that MUST BE recorded as iffy:uid
  • If an item > pubDate is defined in the post that was updated, that MUST BE recorded as atom:published
  • If an item > dc:creator is defined in the post that was updated, that MUST BE recorded as dc:creator If, in the post that was updated, authorship was defined using item > author or item > atom:author those items should be converted into a form appropriate for dc:creator elements.

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

In general, this element tracks the provenance of a feed or item. It can be at the channel-level or at the item-level. Also, iffy:provenance elements can be nested within iffy:provenance elements (see below).

When no shape attribute is set, or shape="sequence"

iffy:provenance elements of shape sequence (the default) contain

  • 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
  • optionally, a terminating iffy:provenance whose shape attribute is set to merge

If the item or channel from which the current item or channel 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:

  • If the contained iffy:provenance has no shape attribute set, or if shape is set to sequence, then the current feed SHOULD include all items of that element, with the URL of the feed from which the item was sourced PREPENDED as an atom:link. 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 or iffy:provenance subelement.

  • If the contained iffy:provenance has a shape attribute set to merge, then the full element should be included as a subelement, after an atom:link to its source.

If one is present, processors SHOULD use a channel level atom:link element with rel="self" and type="application/rss+xml" to as the basis for provenance in source documents. See RSS Best Practices. However, if no such atom:link is available at the channel level, processes may default to the URL by which they accessed the source.

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>

When the shape attribute is set to merge

iffy:provenance elements of shape merge describe an item or channel that has derived from multiple sources. When shape="merge", the ordering of items within iffy:provenance is not significant.

Any iffy:provenance element of shape merge can contain any number of atom:link and iffy:provenance of shape sequence, or with no shape attribute set.

When merging items or feeds whose provenance is itself the result of a merge, processors SHOULD bring what would become elements of a nested iffy:provenance with shape="merge" into the top-level merge.

In other words, iffy:provenance elements with shape merge should not be directly nested, one inside the other. Elements of the inner iffy:provenance with shape="merge" should be flattened into the outer iffy:provenance with shape="merge".

iffy:provenance elements with shape merge CAN and SHOULD be indirectly nested, when a merge brings in an iffy:provenance element of shape sequence (or no shape set), which then includes a nested iffy:provenance elements with shape merge.

Element — iffy:restriction

In general, represents an expression 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 iffy:update-history example.

Element — iffy:synthetic

This element marks channels or items that are in some sense automated or "synthetic".

SHOULD contain an iffy-type, and then other type-specific subelements.

When a subelement of channel

channel > iffy:synthetic implies that ALL of the items in the channel are synthetic or automatically produced. An aggregation or curation of human-authored items SHOULD NOT be marked iffy:synthetic.

Known types:

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

When a subelement of channel AND iffy:type is ItemUpdateFeed

SHOULD 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.

Example:

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

When a subelement of item

The iffy:synthetic element of an item SHOULD contain — in some form of parsable XML — all the data from which the item content (as reflected in item > content:encoded or item > atom:content) has been generated.

Consumers may opt to ignore these content items, and use the data from iffy:synthetic for custom renderings or further processing.

Known types:

  • UpdateAnnouncement — A synthetic item marking an update of an older item in the feed (or that once would have been in the feed)
  • UpdateCumulation — A synthetic item describing an aggregation of updates, which may include updates of multiple items, and multiple updates for each item.

When a subelement of item AND iffy:type is UpdateAnnouncement

In addition to iffy:type, MUST contain an iffy:update element, which in turn MUST contain an iffy:initial element describing the initial state of the updated post.

Example:

<item>
  <pubDate>Thu, 20 Jun 2024 13:10:00 -0400</pubDate>
  <guid isPermalink="true">
    https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index-updated-2024-06-20-13-10-00.html
  </guid>
  <link>https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index-updated-2024-06-20-13-10-00.html</link>
  <title>Updated: Feedletter tutorial</title>
  <!-- other item elements -->
  <iffy:synthetic>
    <iffy:type>UpdateAnnouncement</iffy:type>
    <iffy:update>
      <atom:updated>2024-06-20T17:10:00Z</atom:updated>
      <atom:summary>
        <![CDATA[Add note to Section 16, "Advanced: Customize the content" documenting <i>feedletter</i> API changes that slightly modify this section of the tutorial.]]>
      </atom:summary>
      <iffy:revision>
        https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index-oldcommit-acb84c08c1bbcc83036b9cad70f6a3c5d60865c4.html
      </iffy:revision>
      <iffy:diff>
        https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index-diff-acb84c08c1bbcc83036b9cad70f6a3c5d60865c4-to-current.html
      </iffy:diff>
      <iffy:initial>
        <atom:title><![CDATA[Feedletter tutorial]]></atom:title>
        <atom:link href="https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index.html"/>
        <iffy:uid>https://tech.interfluidity.com/2024/01/29/feedletter-tutorial/index.html</iffy:uid>
        <atom:published>2024-01-29T15:30:00Z</atom:published>
        <dc:creator><![CDATA[Steve Randy Waldman]]></dc:creator>
      </iffy:initial>
    </iffy:update>
  </iffy:synthetic>
  <dc:creator><![CDATA[Update-o-Bot]]></dc:creator>
  <content:encoded><!-- generated HTML content --></content:encoded>
</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 synthetic item marking an update of an older item in the feed (or that once would have been in the feed)

  • UpdateCumulation — A synthetic item describing an aggregation of updates, which may include updates of multiple items, and multiple updates for each item.

Please see known containing elements, including

Element — iffy:uid

Refers to the guid of an item from a different item or construct.

Note: We define an iffy:uid element, rather than rely upon atom:id, because atom:id requires that its contents be an IRI, but we mean to impose no such restriction.

Please see known containing elements, including

Element — iffy:update

In general, describes or announces updates to previously published items.

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.

When a sub-element of item > iffy:update-history

MUST contain one atom:updated element.

MAY also contain one each of

MAY contain an atom:title element, if the title has been revised since a previous version

MAY contain any number of dc:creator elements, reflecting authorship specific to this revision.

By default, an update's title and authors are the same the containing item, which always reflects the current revisions authors.

If the title changes, or authorship is evolving over time, these items should be specified in every update that alters them.

The initial title and authorship SHOULD BE specified in an iffy:initial element if either have been revised.

See iffy:update-history example.

When a sub-element of item > iffy:synthetic with iffy:type UpdateAnnouncement

MUST contain one atom:updated element.

MUST contain an iffy:initial describing the initial state of the item updated.

(Information in the containing item refers to the update announcement rather than the post whose update is announced, so an iffy:initial element is necessary.

MAY also contain one each of

MAY contain an atom:title element, if the title has been revised since a previous version.

MAY contain any number of dc:creator elements, if authorship has been revised since a previous version..

Element — iffy:update-history

When an item level element

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

When a sub-element of iffy:synthetic with iffy:type UpdateCumulation

MUST contain a sequence of iffy:update-history elements, each of which contains iffy:update elements in reverse chronological order, describing a sequence of major revisions to an item, and MUST ALSO contain one iffy:initial element, which MUST include an iffy:uid element identifying and describing the item whose updates are documented. See discussion under iffy:initial

Last major update at 2024-11-02 @ 05:15 PM 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-11-10 @ 08:30 PM EST.