Action Applications Cross Server Networking Specification: APC AA RSS 1.0 module

Next Previous Contents

While searching for the best way to specify the APC AA syndication mechanism, a focus was put onto doing it in a way that conforms to existing standards. There is one obvious standard for content syndication, namely RSS, and it became soon clear that RSS would be the basis for the APC AA inter node networking.

The first version of this document specified a new specific version of RSS which derived from RSS 0.91. RSS 0.91, however, itself does not conform to many standards itself. It was developed by Netscape Corp. and they used RSS 0.9 to develop it but stripped away many of the best features of RSS 0.9, that is in the first row, RDF compliance.

The 1.0 version of RSS now is RDF complaint again.

2.2 RSS 1.0, RDF, XML

RSS means RDF Site Summary.

In contrast to Netscape's RSS 0.91, RSS 1.0 is, as was RSS 0.9, an application of RDF (Resource Description Framework / http://www.w3.org/RDF/). RDF defines an abstract way to describe everything in the world that can possibly have a Uniform Resource Indicator (URI). RDF makes statements about resources. An RDF resource can be almost anything that can have a unique resource identifier (URI). This does not necessarily mean that the resource must be accessible through the Internet; it only means that it must have a unique identifier. The statements define values for properties of the resources. RDF makes an effort to cover a lot of different situations and aspects, most of them are not relevant for our purposes. RDF also defines a way to write down the statements using XML. The XML representation of RDF data can be written in more than one way for different purposes, though.

RSS defines a class of resources called channel. A channel is quite the same as what we call a feed or slice. A channel has, according to RSS, a title, a description and so on, and it has items. The items, in turn, have a title, a description and a link. RSS also defines XML as the obvious transport method for RSS data, and it makes some constraints on RDF regarding possible XML representations of the RSS data. The RSS specification is by far less verbose than RDF; the included examples and de facto usage make it much clearer.

One of the main goals that were followed when the RSS 1.0 specification ( http://purl.org/rss/1.0/) was developed was extensibility. RSS 1.0 has a feature that is called RSS modules which allows anyone to extend RSS 1.0 to add new fields for their purposes. The modularization is described in the RSS 1.0 module specification ( http://purl.org/rss/1.0/modules/).

RSS 1.0 modules use an XML feature called name spaces ( http://www.w3.org/TR/REC-xml-names/) to create separate and non conflicting name spaces for modules, so it is possible to "pull in" any RSS 1.0 module into an RSS 1.0 document. The parser will be able to recognize to which name space an element belongs and can thus ignore unknown elements.

There are three standard modules which "ship in the box" with RSS 1.0:

The Dublin Core module ( http://purl.org/rss/1.0/modules/dc/) defines 15 elements to describe basic data of a web resource such as creator, title, creation time, publisher, and so on. Some of the Dublin Core elements may be useful for us.
The syndication module ( http://purl.org/rss/1.0/modules/syndication/) defines three elements to give hints for content syndication. These might also be useful for us if we want to include such hints.
The content module ( http://purl.org/rss/1.0/modules/content/), allows sending the actual text of an item. It has become a standard item on March 8, 2001.

2.3 Requirements

The data model we need must be able to transport all data we want to exchange between nodes. This data describes

feeds or slices itself
and each item which is considered current at the moment the document is generated.

The term feed or slice is used in this section of this document to clarify that the data model is not limited to transport information about what we call slice in the Action Application; it is rather prepared to have information on a feed which, in the first implementation, will indeed come from a single slice of the Action Applications.

In this version of this specification, not all fields of any slice or feed are transported by the mechanism.

The data that describes the feed or slice we need to be able to carry is:

The name of the feed or slice.
The id of the slice or feed.
A description for the feed or slice.
A timestamp of the newest item in this slice.
The categories used in items in this feed.
A list of field names used in items in this feed.
Timestamp of the latest item/s sent.

The data that describes the actual current items need to include:

An item id.
An item title.
An item summary / description.
The item text (if no link is present).
A link to the item (if the item text is not present).
The item category.
The fields for the actual data.

2.4 RSS 1.0 data model evaluation

The RSS 1.0 standard ( http://purl.org/rss/1.0/) which we are about to extend defines a channel entity which consists of

a title (text field),
a description (text field),
a link (text field),
one or more items

and several other optional fields describing the channel which we won't use because those fields are not appropriate for our purposes.

Each item consists of three fields:

A title,
a link
and a description.

The Dublin Core module adds 15 new elements to both channels and items; these are:

title
creator
subject
description
publisher
contributor
date
type
format
identifier
source
language
relation
coverage
rights

The syndication module adds these three fields:

updatePeriod ( 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' )
updateFrequency ( a positive integer )
updateBase

This means that we can use some of the fields of RSS 1.0 and the "out of the box modules", but we need to extend this so we can carry all of our information in it. This is particulary true because we have a requirement to carry formatting information and possibly other information with the individual field data content. For example, the APC AA can use HTML formatted text in every field. The DC module can carry plain text only, so we have to use our own fields to carry formatted versions of these fields.

The RSS content module, http://purl.org/rss/1.0/modules/content/, supports a <content:items> element which allows transportation of the actual content using any format and encoding. This is useful for us to transport the item's text. We narrow this spec by stating which of the features in this module we want to use so the implementation does not get too complex.

2.5 APC AA RSS module definition: General

This section defines the new RSS 1.0 module. It is hereby named "APC AA RSS module" or for short, "AA module".

The AA module must be declared in documents using the XML namespace syntax when using it. The URI to refer to the AA module is http://www.apc.org/rss/aa-module.html.

According to this specification, documents using the AA module can contain data for two different modes:

In feed establishing mode, feeds or slices are described so the receiving node can select from a choice of feeds or slices. In this mode, only dummy items are transported; the goal is to transport feed or slice meta information which can occur multiple times. This means that the element <channel> can appear more than once. This is a violation of RSS 1.0. From an RSS point of view, "feed establishing mode" documents have no significance.
In feeding mode, a feed containing items is transported. This means, only one <channel> element exists which contains at least one <item>. These documents are well formed and can be understood by any RSS 1.0 software.

2.6 APC AA RSS module definition: Element syntax and model

Remarks

Within an RDF document, there are several spots where a resource - such as a channel, a category, a field or a news item - must be refered to using an unique identifier (URI). These URI do not necessarily refer to locations in the WWW. Whenever a URI is needed within this specification, the URI should consist of a valid domain name the sending host uses, followed by a unique number. This number will most likely be the AA internal id number everything has.

This specification specifies the following elements as the APC AA RSS module:

Elements existing in RSS 1.0, modified/extended

<rdf:RDF>
When using the AA module, the XML namespace declaration must be added to the rdf:RDF element. It must also include the namespace declarations for all modules used.
Syntax:
```
         <rdf:RDF 
         xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
         xmlns:aa="http://www.apc.org/rss/aa-module.html"
         xmlns:dc="http://purl.org/dc/elements/1.1/"
         xmlns:content="http://purl.org/rss/1.0/modules/content/"
         xmlns="http://purl.org/rss/1.0/">
                 
```
Requirement:
Exactly as shown, aside from any additional namespace declarations
Model:
(channel+, image?, item+, textinput?)
Note that this is identical to RSS 1.0 with the exception that the channel element can appear multiple times. This is allowed only in feed establishing mode when the document is not RSS 1.0 compatible anyway.)

Elements within the <rdf:RDF> element

The obvious elements within the top level, all-enclosing <rdf:RDF> element are <channel> and <item> which are defined by RSS. The APC AA RSS module defines the following elements at that level:

<aa:category> (used in <rdf:RDF> element)

The element carries a single category description. Each category used in the feed must go into its own <aa:category> element. The URI used in the element ({category_uri}) must be unique within the document. The URIs are refered in the channel's <aa:categories> listing element ( aa:categories in channel ) and in the item's <aa:categories> listing element ( aa:categories in item ). The category element contains three sub elements which indicate the category id, the parent category id (if any) and the literal category name.

Syntax:

        <aa:category rdf:about="{category_uri}">
          <aa:id>{category_id}</aa:id>
          <aa:name>{category name}</aa:name>
          <aa:catparent>{parent category id}</aa:catparent>
        </aa:category>

Requirement:

required, one for each category used in the channel

Model:

          <aa:category>   ('<aa:category rdf:about="' #PCDATA '">'
                                  '<aa:id>' #PCDATA '</aa:id>'
                                  '<aa:name>' #PCDATA '</aa:name>'
                                  catparent_spec?
                                  '</aa:category>')
          catparent_spec        ('<aa:catparent>' #PCDATA 
                                 '</aa:catparent>')

used in:

<rdf:RDF> element

<aa:field> in <rdf:RDF>
The element carries a single field description. Each field used in the feed must go into its own <aa:field> element. The URI used in the element ({field_uri}) must be unique within the document. The URIs are refered in the channel's <aa:fields> listing ( aa:fields ) as well as in the item's various data fields in <aa:field> references. The <aa:field> element contains sub elements which indicate the id and the literal name of the field.
Syntax:
```
        <aa:field rdf:about="{field_uri}">
          <aa:id>{field_id}</aa:id>
          <aa:name>{field name}</aa:name>
        </aa:field>
```
Requirement:
required, one for each field used in the channel
Model:
```
          <aa:field>      ('<aa:field rdf:about="' #PCDATA '">'
                                  '<aa:id>' #PCDATA '</aa:id>'
                                  '<aa:name>' #PCDATA '</aa:name>'
                                  '</aa:field>')
```
used in:
<rdf:RDF> element

Elements within the <channel> element

These elements appear within the <channel> element:

<aa:NewestItemTimestamp>
The element carries the timestamp of the newest item in the channel. The time must be given in UTC.

Syntax
<aa:NewestItemTimestamp> YYYY-MM-DDTHH-MM-SSZ </aa:NewestItemTimestamp>
Requirement:
required
Model:
<aa:NewestItemTimestamp> (#PCDATA) as in W3C note daytime ( http://www.w3.org/TR/NOTE-datetime)
used in:
channel element

<aa:categories>

This element contains references to the categories used in a channel. It contains an RDF bag. Each member of the bag refers to one category. The categories themselves must be defined elsewhere in the document ( aa:category in rdf:RDF ).

Syntax:

        <aa:categories><rdf:Bag>
        <rdf:li rdf:resource="{category_uri}"/>
        <rdf:li rdf:resource="{category_uri}"/>
        ...
        </rdf:Bag></aa:categories>

Requirement:

optional

Model:

        <aa:categories>  ('<rdf:Bag>' category_reference+ '</rdf:Bag>')
        category_reference     ('<rdf:li rdf:resource="' #PCDATA '"/>')

used in:

channel element

Elements within the <item> element

These elements appear within <item> elements. They mainly represent the content of the item while refering to categories and fields outside the item element.

<aa:categories> in item
The element indicates the categories this item belongs to. It refers to one or more of the categories defined in <aa:category> elements (see aa:category in rdf:RDF ).
The element works the same way as in <channel> elements. For the syntax, requirement, and model description see there: aa:categories in channel .

<aa:fielddatacont> element

The element serves as a general purpose field data container. All field data is carried in this element. All field data that can be represented using dublin core elements must appear in a dublin core element, too - which means that some of the field data is duplicated. The container is an RDF bag which means it has no order, it is just a collection of things.

The container contains <aa:fielddata> elements which in turn contain the value of one field for this item each. The field is referenced by a <aa:field> element. An optional <aa:fieldflags> field can contain flags such as FLAG_FREEZE or others as defined elsewhere by the AA.

An optional <aa:format> element specifies the format used by the field content. It works the same way as the content module format element with the exception that is is optional. The empty element with a rdf:resource attribute references the format for the content. Possible formats are the same as for the content ( content:items ). It is possible to extend this in the future. The absence ot this element means that the content is plain text (the same as <aa:format rdf:resource="http://www.isi.edu/in-notes/iana/assignments/media-types/text/plain"/>).

The actual content of the field is stored in the <rdf:value> element. The format of the data must be as indicated by the aa:format element. If it is plain text, it must use the entity escape mechanism for the characters '<', '>', '&' and '"'. In case of non well formed data such as html, the xml CDATA mechanism should be used.

Syntax:

          <aa:fielddatacont><rdf:Bag>
            <rdf:li><aa:fielddata>
              <aa:field rdf:resource="{field_uri}"/>
              <aa:fieldflags>{field flags}</aa:fieldflags>
              <aa:format rdf:resource="{format nature}"/>
              <rdf:value>{field content}</rdf:value>
            </aa:fielddata></rdf:li>
            <rdf:li><aa:fielddata>
              <aa:field rdf:resource="{field_uri}"/>
              <aa:fieldflags>{field flags}</aa:fieldflags>
              <aa:format rdf:resource="{format nature}"/>
              <rdf:value>{field content}</rdf:value>
            </aa:fielddata></rdf:li>
            ...
          </rdf:Bag></aa:fielddatacont>

Requirement:

required for each field

Model:

          <aa:fielddatacont> ('<aa:fielddatacont><rdf:Bag>'
                                    fielddata_item+ 
                                    '</rdf:Bag></aa:fielddatacont>')
          fielddata_item           ('<rdf:li><aa:fielddata>'
                                    field_reference fielddata_flags? 
                                    fielddata_format?
                                    fielddata_value
                                    '</aa:fielddata></rdf:li>')
          field_reference          ('<aa:field rdf:resource="' #PCDATA 
                                    '"/>')
          fielddata_flags          ('<aa:fieldflags>' #PCDATA 
                                    '</aa:fieldflags>')
          fielddata_format         ('<aa:format rdf:resource="' #PCDATA
                                    '"/>')
          fielddata_value          ('<rdf:value>' #PCDATA 
                                    '</rdf:value>')

used in:

item element

2.7 APC AA RSS module definition: Element description

The data that describes the feed or slice contains three RDF containers. One of them is defined in RSS 1.0; it contains the items. The other two are defined by the AA module; they contain the slice's categories and fields, respectively.

For containers, RDF offers two concepts to represent items in the containers: As references items and as inline items. This specification only allows RDF containers containing references items within channels. This means that the containers only contain references to the actual items. The references are made up using rdf:resource attributes, and the actual items must appear elsewhere in the document.

The slice of feed data is carried as follows:

The name of the feed or slice is carried within the existing <title> element.
The description of the feed or slice is carried in the existing <description> element.
The timestamp of the newest item in this feed or slice is carried in an AA module element <aa:NewestItemTimestamp>.
The categories used in items in the feed or slice is carried in an AA module element <aa:categories> ( aa:categories in channel ) which contains an RDF RDF bag which in turn contains the categories. Each category is referred to using a unique URI in a rdf:resource attribute. Each category which appears here must appear again on its own as a <aa:category> element elsewhere in the document.
The slice or feed id is carried in the Dublin core field <dc:identifier>.
The list of fields used in items in the feed or slice is carried in a AA module element <aa:fields> which contains an RDF bag which in turn contains references to the fields. Each field is referred to using a unique URI in a rdf:reference attribute. Each field which appears here must appear again on its own as a <aa:field> element elsewhere in the document.
The RDS <link> element is filled with a link to the original main slice page.

The categories referenced in the aa:categories in channel container must appear in the document data as follows:

The category lives in a AA module <aa:category> element. The element has an rdf:about attribute indicating the URI of the category.
The aa:category contains a <aa:name> element which indicates the category name and a <aa:Id> element indicating the category id. Also, the parent category's id is transported in a <aa:catparent> element if this is not already a parent category. If a parent category is refered to here, the parent category must appear on its own in the categories container.

The fields referenced in the aa:fields container must appear in the document data as follows:

The field lives in a <aa:field> element. The element has an rfc:about attribute indicating the URI of the field.
The aa:field contains a <aa:name> element which indicates the field name and a <aa:id> element indicating the field id.

The data that describes the actual items is carried as follows:

The title of the item is carried in the existing RSS <title> element.
The description of the item is carried in the existing RSS <description> element.
The item id of the item is carried in the Dublin core field <dc:identifier>
The link to the content is carried in the existing RSS <link> element. If there is no link, the link field will be empty.
The item text is carried in the <content:items> element provided by the RSS content module http://purl.org/rss/1.0/modules/content/ with the following constraints:
- The only formats generated and recognized by AA as used with the <content:format> element are:
  - generic HTML. The rdf:resource attribute to the content:format element refers to the URI http://www.isi.edu/in-notes/iana/assignments/media-types/text/html/. The actual html data in the rdf:value element must be quoted useing the <![CDATA[...]]> mechanism;
  - and plain text. The rdf:resource attribute to the content:format element refers to the URI http://www.isi.edu/in-notes/iana/assignments/media-types/text/plain. The actual text data in the rdf:value element must use the entity escape mechanism for the characters '<', '>', '&', ''' and '"' (< and so on).
  Other formats may be added in the future, so the implementation should expect the occurance of other formats (and ignore those).
- Only one version of the text is put into the <content:items> bag. The implementation should expect to receive items with more formats and select one (html if is is there, plain text otherwise).
- The <content:item> element using the rdf:resource attribute is not generated and not expected by the AA.
- The content:encoding element is not used.
The item categories are carried in a AA module element <aa:categories> which contains a rdf:Bag container. The container contains the individual category references indicating the actual categories as described elsewhere in the document. The categories are referenced by using rdf:resource attributes.
All other data fields are carried in the <aa:fielddata> elements. Additionally, all other field data is carried in standard Dublin Core (dc) fields if such a field exists and has not been used for other data. The following mapping list is used to map aa field types to dc fields (dc field - aa field):
- title - Headline
- creator - author
- subject - summary
- description - summary
- publisher - (unused)
- contributor - (unused)
- date - publish date
- type - (unused)
- format - HTML formatted ('text/plain' or 'text/html')
- identifier - aa item id
- source - source
- language - language
  Recommended best practice for the values of the Language element is defined by RFC 1766 [RFC1766] which includes a two-letter Language Code (taken from the ISO 639 standard [ISO639]), followed optionally, by a two-letter Country Code (taken from the ISO 3166 standard [ISO3166]). For example, 'en' for English, 'fr' for French, or 'en-uk' for English used in the United Kingdom.
- relation - source URL
- coverage - location
- rights - (unused)
The DC field data elements only contain the field content as literal text in plain text format. For every aa field an item is added to the aa:fielddatacont container. The added item contains an <aa:fielddata> element. The <aa:fielddata> element contains
- a reference to the actual field definition in a <aa:field> element ( aa:field in item )
- the field content in a <rdf:value> element
- optionally, a <aa:fieldflags> element with aa specific flags. The only flag currently defined is FLAG_FREEZE,
- and, optionally, a <aa:format> element which works the same way as the <content:format> element content:items with the exception that if it is not present, the format is plain text.

2.8 Character encoding

The encoding in use for a slice within apcrss messages will match the encoding of the slice data.

Within the text fields, the characters '<', '>' and '&' must be encoded using the existing XML mechanisms ('<', '>', '&').

Date and time values are encoded using the w3c note http://www.w3.org/TR/NOTE-datetime.

2.9 Examples

Examples of RSS 1.0 / AA module data files are

aamod-feeding-example.xml: An example of an aa module message feeding two items in feeding mode.
aamod-establish-example.xml: An example of an aa module communication at feed establishing time in feed establishing mode.

Next Previous Contents

2. APC AA RSS 1.0 module

2.1 Why RSS

2.2 RSS 1.0, RDF, XML

2.3 Requirements

2.4 RSS 1.0 data model evaluation

2.5 APC AA RSS module definition: General

2.6 APC AA RSS module definition: Element syntax and model

Remarks

Elements existing in RSS 1.0, modified/extended

Elements within the <rdf:RDF> element

Elements within the <channel> element

Elements within the <item> element

2.7 APC AA RSS module definition: Element description

2.8 Character encoding

2.9 Examples