(((•)))
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-07-01 @ 02:40 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

- `iffy:completeness`
- `iffy:diff`
- `iffy:hint-announce`
- `iffy:initial`
- `iffy:policy`
- `iffy:provenance`
- `iffy:restriction`
- `iffy:revision`
- `iffy:synthetic`
- `iffy:type`
- `iffy:uid`
- `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: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`

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

- `iffy:synthetic`.

## Element — `iffy:uid`

Used to refer 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

- `iffy:initial`.

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

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

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

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

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` elements, in reverse chronological order, describing a sequence of major revisions to an item.

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

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

### Major revisions:

- 2024-07-01 @ 02:40 PM EDT — Major revision of `iffy:synthetic`, generalize `iffy:initial`, `iffy:update`, `iffy:update-history`, define `iffy:uid`. (diff)
- 2024-06-20 @ 11:05 AM EDT — Document `iffy:type`, update documentation of `iffy:synthetic` as optionally including `iffy:type`. (diff)
- 2024-06-17 @ 11:50 PM EDT — Document `iffy:synthetic`. (diff)
- 2024-06-11 @ 02:10 PM EDT — Document `iffy:hint-announce`, `iffy:policy`, and `iffy:restriction`. (diff)
- 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. The most recent minor modification of this entry occurred 2024-07-01 @ 02:39 PM EDT.