Belongs to the 2009-03/Leap2A specification
Contents |
These are all the elements given in the specification for the Atom Syndication Format, in the order given there, plus one from the Atom Threading Extensions.
| Atom element | Usage here | Notes |
|---|---|---|
| atom:name | same | The author's name. |
| atom:uri | variant | May also be an internal reference to an entry representing a person. See author as relationship. |
| atom:email | same | The author's e-mail address. |
| atom:feed | variant | The feed element is essentially a wrapper for the entries, which are portfolio items. See below. |
| atom:entry | variant | Entries represent each portfolio item, not just ones like blog entries. Contains sub-elements as in Atom and below. |
| atom:content | variant | Where present, represents the main information content of the item. See content. |
| atom:author | same | See author as literal and author as relationship. |
| atom:category | similar | Specific ways of using category schemes, terms and entries are recommended. See categories. |
| atom:contributor | not specified | May be used later, if the specification extends to group authorship. |
| atom:generator | not specified | Could be used later to indicate the generating system. However this could also be obvious from the feed id. |
| atom:icon | not specified | Not really appropriate, as the feed itself is not envisaged as directly presented. |
| atom:id | similar | Mandatory. Specific ways of constructing ids are recommended. |
| atom:link | similar | A vocabulary is specified for rel attributes. See relationships. |
| atom:logo | not specified | As icon. |
| atom:published | similar | Used for date of creation, not necessarily of publication. See published. |
| atom:rights | not specified | It is not envisaged that portfolio information would have homogeneous rights. |
| atom:source | not specified | This specification is not actually about syndication, so there is unlikely to be a further source. |
| atom:subtitle | not specified | This may be useful, for representing information about the exported "feed". |
| atom:summary | similar | See summary. |
| atom:title | same | Mandatory (and must have actual content) for every entry. |
| atom:updated | same | See updated. |
| thr:in-reply-to | same | See in reply to. |
These are mostly sub-elements of atom:entry. The ones with namespace "leap" are defined for this work; the rdf one is adopted.
| Element | Notes |
|---|---|
| leap:activetime | ISO duration representing time actually spent on an activity. |
| leap:addressline | Used within leap:spatial to represent a line of an address |
| leap:country | Used within leap:spatial to represent the country of an address |
| leap:date | Used for dates associated with items: start, end and target. |
| leap:orgdata | Used for data about an organization, including name and contact details. |
| leap:persondata | Used for data about a person, including names and contact details. |
| leap:postcode | Used within leap:spatial to represent a postcode |
| leap:spatial | Used for a textual representation of place or location. May contain address information. |
| leap:status | Used to indicate the stage of progress of a plan or activity. |
| rdf:type | Used to represent the main type of the item / entry. |
One main function of the containing feed element is to define namespaces. A typical first element might be something like:
<feed xmlns:portfolio="http://www.example.ac.uk/interop/atom.aspx/" xmlns:leap="http://wiki.cetis.ac.uk/2009-03/Leap2A_predicates#" xmlns:leaptype="http://wiki.cetis.ac.uk/2009-03/Leap2A_types#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:categories="http://wiki.cetis.ac.uk/2009-03/Leap2A_categories/" xmlns="http://www.w3.org/2005/Atom">
Of these, portfolio, leaptype and categories are not true namespaces, but abbreviations used as part of CURIEs.
Mandatory sub-elements of feed, according to the Atom spec, are
It makes sense for the id element to be a unique URI which acts also as the base of the URIs of each entry. (See below for more detail.) The title can be anything - but it could be meaningful and help to indicate what kind of output it is. The updated date should relate to the date and time of export - either the date and time at which it was requested, or the date and time at which it was actually carried out, if this is not the same. This gives, for example,
<id>http://www.example.ac.uk/interop/atom.aspx/webfolio/57736</id> <title>Portfolio Items</title> <updated>2008-07-16T11:11:45+00:00</updated>
It makes a great deal of sense to have the author represented at the feed level, so that the element does not have to be placed in each individual entry (unless authored by someone else).
<author> <name>Theophilus Thistledown</name> </author>
E-mail address can also be added if desired, but more importantly an URI for the author (and holder of the portfolio) can be added, pointing to the person entry of the author. See the Author relationship.
The specification also says that there should be a link element with rel="self", such as
<link rel="self" href="http://www.example.ac.uk/interop/atom.aspx/webfolio/57736" />
The sense of this will depend on how the portfolio system is set up. If there is an actual URL which will deliver this portfolio information to those appropriately authorised, then certainly that is the URL which should go in this element. However, there may well not be such a URL. To head off processing problems, it would then be acceptable to duplicate the id in this element, as is done here. Of course, the id may also be set to a URL which renders the same information; but if, for instance, the live URL contains a long query string, it might be easier to read to have a relatively short id URL. The value of link rel="self" does not belong directly with the imported portfolio information, but may be presented to the user in some other way.
That is all that is needed in the feed element, and leaving them out may cause problems for importing systems. There are other sub-elements of feed, but they may be ignored by importing systems.
As mentioned above, it makes sense (though is not essential) to have IDs generated in a systematic way. There are two natural approaches to this.
The simplest approach is to have a unique id for each export, and to use this as the base for contained item IDs. The export ID URL could include in its path components such as
Not all of these are necessary, but just enough to make each export absolutely unique. Then, added to the end, there could be a component that, for example, identifies the (internal) type of record and its sequence number in this export. Exporting systems are free to use extensions that reflect the internal structure of their records. This have the added advantage that the ids can be used as a way of directing items to their proper place when communicating between different instances of the same software.
The other natural approach is to establish a persistent internal identifier for each item recorded in the system, unique for that user, or perhaps unique across the system. The IDs for items would not then be extensions of the ID for the overall feed, but the overall feed can still have similar components as above. This has advantages and disadvantages.
See this W3C page about CURIEs. Using CURIEs looks similar to using namespace abbreviations, but is technically different.
CURIEs are useful for representing URIs within attributes used in types, relationships, and categories.
The use of CURIEs makes the XML much easier for human reading and checking, though it might impose a small extra machine processing overhead. We have now agreed that we will allow the use CURIEs as an alternative to writing out full URLs. If you use CURIEs, appropriate namespaces will have to be declared.
For types, one can use
xmlns:leaptype="http://wiki.cetis.ac.uk/2009-03/Leap2A_types#"
for predicates, one can use
xmlns:leap="http://wiki.cetis.ac.uk/2009-03/Leap2A_predicates#"
which will probably be declared already as a regular namespace for use with leap elements. For common categories, one can use
xmlns:categories="http://wiki.cetis.ac.uk/2009-03/Leap2A_categories/"
Locally defined category schemes need to have a namespace chosen by the system administrators. It is recommended that the schemes namespace URL should give useful information about the scheme, and when concatenated with any term name, should point to useful information about that term.
For further details, see the relevant pages.
This specification requires the "unsafe" form, which causes fewer parsing problems for the moment, as they looks like regular URIs. For example
<rdf:type rdf:resource="leaptype:entry" />
"Safe" CURIEs have square brackets round them, for example
<rdf:type rdf:resource="[leaptype:entry]" />
Any abbreviation can be used that is not able to be confused with others, but it is recommended to use agreed conventional ones.
Another use of CURIEs to improve readability is with the id URIs of each element, reused in href attributes of links. For example, one could define
xmlns:portfolio="http://www.example.ac.uk/portfolio_system/export/user1089/2008-07-17/"
if that was the chosen root of the URI for the ids of all the entries. Every exporting portfolio system needs to devise a URI system which ensures that each entry has a unique URI. This may build on a unique dated URI for the export as a whole, or may be unique for each record of a particular user of a particular system.
