Concepts

If you know Atom, then a good introduction to Leap2A concepts is to first consider how Atom elements are used in Leap2A.

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.

Atom element	Usage here	Notes
atom:name	same	The author's name.
atom:uri	variant	As well as the Atom usage as a global URI for the person (or their main blog feed), this may also be an internal reference to an entry representing a person. See author as relationship.
atom:email	not specified	The author's e-mail address may be included here, as specified in Atom. But preferred is to put author's e-mail address in a separate entry element of type person: e-mail is one of the many data fields.
atom:feed	variant	The feed element is essentially a wrapper for the entries, which are portfolio items. See the feed section in the introductory page.
atom:entry	variant	Entries represent each portfolio item, not just ones like blog entries. Contains sub-elements as in Atom, but also with extra elements added for Leap2A.
atom:content	variant	Where present, represents the main information content of the item, which may be a description. See content or description.
atom:author	same	See author as literal and author as relationship. Note that this is the author of the entry, not the author of any attached or referenced resource.
atom:category	similar	Specific ways of using category schemes, terms and entries are recommended. See categories.
atom:contributor	similar	May be used to list anyone who has contributed entries to the Leap2A feed. Not for use in identifying contributors to attached resources or publications.
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: see id. Specific ways of constructing ids are recommended below.
atom:link	similar	A vocabulary is specified for rel attributes. See relationships including ones from Atom.
atom:logo	not specified	As icon.
atom:published	similar	Used for date of creation, not necessarily of publication. See published.
atom:rights	same	Used for human-readable information only: for machine-processable information, use link rel="license"
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 not be empty) for every entry.
atom:updated	same	See updated.
thr:in-reply-to	same	See in reply to.

Non-Atom elements

For non-Atom elements, please see the core specification document and/or the terms page.

Constructing IDs

See also the literal id section.

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, but whatever approach is taken, it is essential that the same form is used in id elements and in links.

{slide=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

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.

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.

{/slide} {slide=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. It also is in keeping with the Atom spec.
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.

{/slide}

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.

One can use

    xmlns:leap2="http://terms.leapspecs.org/"

For common categories, one can use

    xmlns:categories="http://wiki.leapspecs.org/2A/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="leap2:entry" />

"Safe" CURIEs have square brackets round them, for example

<rdf:type rdf:resource="[leap2: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.