2009-03/Leap2A elements

Belongs to the 2009-03/Leap2A specification – see also 2010 developments

Table of Atom elements
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.

Table of non-Atom elements
These are mostly sub-elements of atom:entry. The ones with namespace "leap" are defined for this work; the rdf one is adopted.

The feed element
One main function of the containing feed element is to define namespaces. A typical first element might be something like: &lt;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"&gt; 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, http://www.example.ac.uk/interop/atom.aspx/webfolio/57736 Portfolio Items 2008-07-16T11:11:45+00:00 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). Theophilus Thistledown 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.
 * id
 * title
 * updated

The specification also says that there should be a link element with rel="self", such as  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.

Constructing IDs
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.

Unique export
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 domain of the organisation which runs the portfolio system
 * a name associated with the e-portfolio system
 * the date (and possibly time) of export
 * the user id - however if there are security worries about this, it may be better simply to have a serial number of export on that day.
 * an internal system identifier for the root of the information being exported
 * some sequence number, if needed.

Persistent item URIs
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.
 * Advantages
 * This would make it easier for systems that consume such information delivered by web services to keep a track of when information should overwrite what has been consumed before. However there is little point in this for a single once-for-all transfer of information.


 * Disadvantages
 * More care would be needed on security, as the persistent identifiers may allow others to start piecing together a picture of some of the information or its relationships.

Use of CURIEs
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 &lt;rdf:type rdf:resource="leaptype:entry" /&gt; "Safe" CURIEs have square brackets round them, for example &lt;rdf:type rdf:resource="[leaptype:entry]" /&gt;

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.