(((•)))
tech.interfluidity.com
a notebook by steve randy waldman
→ See also top, archive, subscribe, drafts blog, interfluidity main
2024-05-13 ⇒

# The 'iffy' XML namespace

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

- `iffy:completeness`
- `iffy:original-guid`
- `iffy:provenance`
- `iffy:when-updated`

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:original-guid`

Solely an item level element

IF AND ONLY IF an item contains an `atom:updated` element AND the `guid` of this item has been modified from the original, pre-update item in order to encourage feed consumers to surface the update, THEN the `guid` of the original post MUST be included in an `iffy:original-guid` element so that aware consumers can tie the update back to the original.

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>
        <iffy:when-updated>Resurface</iffy:when-updated>
        <!-- other channel-level elements -->
        <item>
          <title>Names too on the nose</title>
          <guid isPermalink="false">
            https://tech.interfluidity.com/2024/04/09/names-too-on-the-nose/index.html#updated-2024-04-14T05:55:00Z
          </guid>
          <link>https://tech.interfluidity.com/2024/04/09/names-too-on-the-nose/index.html</link>
          <iffy:original-guid>https://tech.interfluidity.com/2024/04/09/names-too-on-the-nose/index.html</iffy:original-guid>
          <atom:updated>2024-04-14T05:55:00Z</atom:updated>
          <!-- other item-level elements -->
        </item>
      </channel>
    </rss>

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:when-updated`

May be both a channel and item level element. Item-level specification overrides channel-level specification.

Contains one of the following three values:

1. `Ignore`
2. `Resurface`
3. `Reannounce`

`iffy:when-updated` suggests how feed consumers should handle items containing `atom:updated` elements.

- `Ignore` suggests that feed consumers simply ignore the notification. Feed consumers should update any cache of the item contents (as they should do in the absence of an `atom:updated` tag.
- `Resurface` suggests that consumers that present multiple items in reverse-chronological order should present the new item, sorted at its update time rather than its initial publication date. Consumers that "announce" items one at a time (such a e-mail newsletter gateways, Mastodon / Twitter / SMS notifiers) should not re-notify the item.
- `Reannounce`, like `Resurface`, suggests that consumers that present multiple items in reverse-chronological order should present the new item, sorted at its update time rather than its initial publication date. However, `Reannounce` suggests consumers that "announce" items one at a time (such as e-mail newsletter gateways, Mastodon / Twitter / SMS) notifiers SHOULD re-notify the item.

Implementation Notes:

- Currently, very few feed consumers handle `iffy:when-updated`.
- To give effect to these values, it is recommended that, at levels `Resurface` and `Reannounce`, items be given updated `guid` values, so that existing consumers perceive them as distinct items.
- Naive announcement consumers, however, will then treat all `atom:updated` events as `Reannounce`, until they are explicitly modified to support this tag.
- Announcing consumers are much rarer and fewer than multiple-item-presenting consumers, so hopefully this will not be too great a burden. Ideally, eventually, feed consumers will widely support this tag and there will be no need for the "hack" of switching `guid` values.
- Implementations that modify `guid` values when updated MUST also provide the `iffy:original-guid` element!
  - See `iffy:original-guid`

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>
        <iffy:completeness>Content</iffy:completeness>
        <iffy:when-updated>Resurface</iffy:when-updated>
        <!-- other channel-level elements -->
        <item>
          <title>Ceci n'est pas un post</title>
          <guid isPermalink="true">https://tech.interfluidity.com/2024/04/09/ceci/index.html</guid>
          <link>https://tech.interfluidity.com/2024/04/09/ceci/index.html</link>
          <atom:updated>2024-04-14T05:55:00Z</atom:updated>
          <iffy:when-updated>Ignore</iffy:when-updated>
        </item>
      </channel>
    </rss>

← Names too on the nose
↑↑↑