(((•)))
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

➣ This post was meaningfully revised at 2024-06-02 @ 12:25 AM EDT. The previous revision is 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

- `iffy:completeness`
- `iffy:diff`
- `iffy:initial`
- `iffy:provenance`
- `iffy:revision`
- `iffy:update`
- `iffy:update-history`

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: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: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: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:update`

When a sub-element of `iffy:update-history`

MUST contain one `atom:updated` element.

MAY also contain one each of

- `atom:summary`
- `iffy:diff`
- `iffy:revision`

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>

← Names too on the nose
↑↑↑
Green shoots of sprouts →

### Major revisions:

- 2024-06-02 @ 12:25 AM EDT — Drop `iffy:timestamp`. We can just reuse `atom:updated` for the same work. (diff)
- 2024-06-01 @ 09:35 PM EDT — Add initial take on tags related to updates and revisions. (diff)
- 2024-05-25 @ 11:00 PM EDT — Add JS/CSS so that prior revisions are visually distinct from current. (diff)
- 2024-05-24 @ 12:25 AM EDT — Drop tags `iffy:when-updated` and `iffy:original-guid`, bad appraoch to updates. (diff)
- 2024-05-13 @ 04:10 AM EDT — Initial publication.

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.