Literals

This page specifies those sub-elements and attributes of the feed, or of item entries, adopted or defined for this specification, where literal values are required.

Atom literals

author

<author>    <name>John Doe</name>  </author>  

(Example taken from the Atom documentation.)
Atom requires every entry to have an author. If the author is not defined for a particular entry, it is inherited from the feed author, where it must be defined if any entries do not have authors defined within them. The atom:author element is an atom person construct that must have a name, and can have an e-mail address and can have a URI. The name only version, as illustrated here, could be seen as similar to other literals, though unlike other literals, it has structure.

For the fuller, relationship version, see Author as a relationship to a separate person entry defined for that person (which can contain persondata).

For a definition of what authorship entails, see [1].

See also the relevant section of the core specification

 

content or description

This is usually thought of as content, but often represents a description.

<content>This is some really simple content, implicitly of type text.</content>  

The element is taken directly from atom:content. For items of type other than entry, the content can be thought of as a description, in the sense of dc:description.

In Atom, content has a type, (see atom:type) which defaults to text, but can also be html or xhtml. For Leap2A, we strongly prefer xhtml over html. Please do not use html content unless you cannot use xhtml, and if this is the case, ask for help with changing to xhtml as soon as possible. You may find HTML Tidy to be a useful resource, for example to clean up user-entered html.

Care is needed in following the Atom specification.

<content type="xhtml">
<div xmlns="http://www.w3.org/1999/xhtml">
<p>The actual xhtml content goes here, with &lt; and &gt; brackets 
<em>unescaped</em> in their normal places: 
xhtml elements do not need namespace prefixes, as the namespace is
declared in the containing div element.</p>
</div>  </content>  

The Atom spec has more useful detail in their documentation about how to do xhtml text elements: the above is not the only method.

Content of Leap2A/resource items should be descriptions of the resource, not the resource itself. An attached digital resource should be linked with an atom:link rel="enclosure". See the Leap2A/resource page for further details.

See also the documentation on files, which further reinforces this point.

Deprecated for export: content src attribute, atomOutOfLineContent

Though Atom provides for content of an entry to be represented by a URI given in the src attribute of the content, (atomOutOfLineContent, documented in section Section 4.1.3) this should not be done when exporting Leap2A.

However, systems importing Leap2A are advised to process atomOutOfLineContent, and treat it as if the src URI were instead given as the href URI of a link rel="enclosure".

Section 4.1.3.2 of the Atom spec specifies that the value of the src attribute "MUST be an IRI reference RFC3987". Also implied by this is that src values must be URL encoded following RFC1738 and RFC3986. '%20' for URL encoding spaces must be used, not '+'. Note also that section 4.1.2 of the Atom spec specifies that in cases where the content is empty, a "summary" element must be provided.

Attributes href and src within xhtml content

Added 2009-12-02.

Item content in general could have elements such as "a" and "img" with src or href attributes. Where these attribute values are absolute URIs, universally readable, and not part of the exporting portfolio system, there is no issue: the links need no special processing, simply being exported and imported as is. However, there are two cases where processing must happen on export and import.

  1. Where the src or href attributes point to files that are included in the exported zip archive, exporting systems must give the attribute values as relative URLs pointing to the files in question in the zip archive. Importing systems will have to change these relative URLs so that they point to the files wherever they are eventually stored by the importing system.
  2. Where an href attribute effectively points to another item within the portfolio information exported, the URL will have to be changed to point to that item. In the export, this will be using a CURIE such as "portfolio:item_352", and this href will need to be changed on import so that it points to the portfolio item in the importing system.

On the other hand, when exporting "snippets" of Leap2A, it could be that the files concerned are left on the original server, and not included with the export. In this case, there is no relative URL that could be used, and they have to be exported as absolute URLs. It is up to the importing system, in negotiation with the exporting system, to ensure that adequate arrangements are in place to allow reading of any needed files on the original server.

See also the relevant section of the core specification

contributor

<contributor>     <name>Sam Ruby</name>  </contributor>  

(Example taken from the Atom documentation.)
The atom:contributor element is an atom person construct that must have a name, and can have an e-mail address and can have a URI. The name only version, as illustrated here, could be seen as similar to other literals, though unlike other literals, it has structure.

For the fuller, relationship version, see contributor as a relationship to a separate person entry defined for that person (which can contain persondata).

A contributor is essentially anyone who has contributed to something who does not qualify as an #author.

See also the relevant section of the core specification

id

Atom requires the containing feed element, and each item entry element, to have an ID. The feed element ID, and suggested rules for constructing them, are discussed in the elements page. This section relates to id elements for entry items.

For IDs to function effectively, they must be

In addition to that, the Atom link spec points out that the href attribute of link elements, which is used to refer to IDs, must be an IRI (internationalised version of URI). Hence having IDs as plain strings only works when there are no links, and the option of having IDs as plain strings has therefore been removed.

There are two approaches to constructing IDs as URIs:

  1. using full URIs
  2. using CURIEs

Whichever approach is used, it must be used consistently within a single Leap2A feed. It is not allowed to mix full URIs and CURIEs, as this may make import implementation more difficult. Thus, the string used for any ID must be exactly the same throughout the feed.

See also the relevant section of the core specification

published

<published>2003-12-13T08:29:29-04:00</published>  

(example taken from the Atom documentation). These date-times must conform to rfc3339. This corresponds to dc:created, (URI) If known, this should be the initial date of creation of the record itself. It is not to be used for any times or events referred to by, or relevant to the subject of the entry.

The text node must conform to rfc3339 (complete with date-time zone indicator, either numeric or "Z" for UTC (=GMT)).

See also the relevant section of the core specification

rights

<rights>Copyright (c) 2003, Mark Pilgrim</rights>  

Example taken from atom:rights documentation. This is optional, and can be applied to individual entries or to the feed as a whole. Atom clearly specifies that this is for human-readable information only. For machine-processable information, use atom:licence for Leap2A, also documented at rfc4946.

See also the relevant section of the core specification

summary

This field from Atom, atom:summary, may be used to give a short text summary of the content, as envisaged in the Atom specification. It is particularly useful, and specified here, for giving a short (summary-like) description of an attached file, for resources.

In Atom, a summary is a text construct, but for Leap2A, it is recommended to keep its type as plain text, not html or xhtml. However, systems importing Atom feeds must note these other possibilities.

For Leap2A/publications, if an abstract is published, that should be placed in the summary element.

See also the relevant section of the core specification

title

<title>A self-explanatory portfolio item</title>  

This is mandatory in Atom for every entry, and described in the Atom documentation.

In Leap2A, it is not expected that the atom:type of the title is anything other than text. However, importers should note that in Atom, title is a text construct, and Atom also allows title to have a type of html or xhtml.

See also the relevant section of the core specification

updated

<updated>2005-07-31T12:29:29Z</updated>  

(example taken from the Atom documentation).

<updated> corresponds to dc:modified, (URI). Because records can be transferred, the date of creation of the record may be earlier than the date of its creation on its present system. If this can be represented in a portfolio system, it is recommended that it should be. The text node must conform to rfc3339 (complete with date-time zone indicator, either numeric or "Z" for UTC (=GMT)).

This is to be used in the same sense as Atom, to indicate the latest update of the record itself, not to any times or events referred to by, or relevant to the subject of the entry.

See also the relevant section of the core specification

Leap2A literals

For leap2:date fields, W3C date time formats should be used, which is a broader superset of rfc3339 - everything that is valid rfc3339 is also valid W3C. It would be useful if import procedures could handle all of these, including year alone and year and month, because dates that are remembered and recorded often do not have times attached, and sometimes even the date is forgotten. Your system must handle rfc3339 dates; if your system cannot handle all the other W3C formats properly, this should be documented.

activetime

This is the time actually spent on an activity, for assessment, credit, time accounting or just personal record purposes.

<leap2:activetime>PT8H30M</leap2:activetime>  

represents eight and a half hours actually spent engaged with that activity. The text node (i.e. the part between the start and end tags) is formatted according to the duration part of the ISO 8601 standard, with designators. In education, most time spent is accounted in hours, and in business, hours and often minutes as well. Years, months and days would not normally be expected. Periods of employment will normally not be represented in this form, but with start and end dates: there is no need to use activetime, as it can be calculated from the start and end dates.

See also this page by the late Claude Ostyn.

See also the relevant section of the core specification

addressline

This is only used in Leap2A as a sub-element of spatial. Each addressline holds one line of an address. The order of the lines in the address, as properly formulated for postal delivery, should be the same as the order in which they are given in the Leap2A XML.

Addressline takes an optional attribute, label, which may be used to specify what kind of entity is represented on that address line, or indeed the label of that line in the exporting system, if any.

Separating the address lines, rather than merging them into one block, maintains the non-significance of carriage return characters, as well as enabling labels.

See also the relevant section of the core specification

country

This is used as a sub-element of spatial. The value is a text string representing the name of a country, in a plain text form suitable for use in an address. Any language or recognisable abbreviation may be used. Having the country as normal text means that ignoring the markup within leap2:spatial, and putting each field on its own line, should result in a viable postal address label.

Country takes one optional attribute, countrycode.

Country information is also represented as a field in persondata and orgdata elements. However, the semantics are different.

Potential future development of spatial

One clear possibility for the future, not currently specified, but flagged as a future possibility, is that the whole of the spatial element would be given as xhtml, and the structured elements would be identified through RDFa within the xhtml, rather than separately.

See also the relevant section of the core specification

         

date

Time information connected with the subject matter of the records, as opposed to temporal metadata about the records themselves, is represented with a leap2:date element, and if not empty (see below), must use one of the W3C date time formats (which includes rfc3339).

The leap2:date element takes one mandatory attribute, point, and one optional attribute, label.

point

The leap2:point attribute of the date element has three possible values:

end

represents the envisaged, planned, or actual finish date. While in the future, this may be changed freely, following the user's planning process. Example:

<leap2:date leap2:point="end" leap2:label="Christmas 2009">2009-12-25</leap2:date>  
start

represents the envisaged, planned, or actual starting date. Example:

<leap2:date leap2:point="start">2009-03-19</leap2:date>  
target

if present, may represent a firmer end point, whether determined by the user or set externally. Example:

<leap2:date leap2:point="target">2010-01-07T17:00:00+00:00</leap2:date>  

Notes on dates

The text of the optional label attribute, if present, may indicate the user's preferred representation of the date or time, and may be formal or informal in nature.

There is a closely related term temporal coverage in Dublin Core.

Clarification 2009-07-14

If any chronological display and management is to be supported, or to enable effective planning and scheduling, these leap2:date fields need to be represented machine-processably, containing dates, in a W3C-DTF format conformant to the ISO standard, as the element content. However, some systems may represent dates only as text fields. These systems may export empty leap2:date elements, but if the element content is absent, the label attribute is mandatory. Systems importing information with blank dates may e.g. set a date field to be unknown, or may downgrade the imported item to an entry. Either way, importing systems may append the content of the date label attribute to the item content.

<leap2:date leap2:point="start" leap2:label="Summer 1999"></leap2:date>  
<leap2:date leap2:point="end" leap2:label="Summer 1999"></leap2:date>  

could be given for something that happened some time over the summer of 1999.

See also the relevant section of the core specification

myrole

<leap2:myrole>Apprentice</leap2:myrole>  

This element gives human readable information about the role that the portfolio holder plays or has played in the context of the item in which it appears.

If an importing system has no place for an explicit role, the information might be appended to the content (description) as "My role: ..."

leap2:myrole elements should not be used inside organization elements, as this would risk having two ways of recording roles and related IDs. Instead, if no affiliation (or other suitable) element to represent the relationship exists, create one specially for the purpose of holding the role details, even if that relationship is not one normally thought of as affiliation (e.g. client).

See also the relevant section of the core specification

 

official publication date or date issued

Only for items of type publication, use dcterms:issued for the official publication date. Again, as with leap2:date, use a W3C date time format.

See also the relevant section of the core specification

 

Personal and organisational data

Due to limitations of specifications existing at the time, it was decided to specify personal and organisational data within Leap2A, because they are so widely used, for example in CVs and other presentations.

The use of these is fully specified in the relevant section of the core specification.

postcode

This is only used in Leap2A as a sub-element of spatial. This can be in any recognised format that is appropriate to the country.
For further information, see Wikipedia "Postal code".

See also the relevant section of the core specification

roleid

<leap2:roleid>B61034</leap2:roleid>  

In the context of an affiliation, the roleid gives, e.g., the membership number.

In the context of an activity or something else, it could also give a staff number, or student number, or any ID limited to a particular context. Essentially, it gives an ID for the portfolio holder in the context of the item in which it occurs. The expectation is that, normally, if leap2:roleid is present, it will be represented alongside leap2:myrole within the same item, to make it explicit what role the id is for.

Lifelong IDs, or service IDs not limited by context or affiliation should rather be given as persondata id elements within a person entry.

As with myrole, for the same reasons, leap2:roleid elements should not appear inside organization elements.

See also the relevant section of the core specification

spatial

Where there is an unstructured description of the location, it must be surrounded, in just the same way for content of type xhtml, with a div element.

<leap2:spatial>
<div xmlns="http://www.w3.org/1999/xhtml">      
<p>In the headteacher's <a href="http://www.example.sch.uk/siteplan.html">office</a></p>
</div> </leap2:spatial>

Dublin Core's dc:spatial (URI), defines a location class as the range of the spatial property, but does not specify any data type for the location class.

As well as unstructured description, a leap2:spatial element may contain one structured address as follows. For example:

<leap2:spatial>
<leap2:addressline>University of Bolton</leap2:addressline>
<leap2:addressline>Deane Road</leap2:addressline>
<leap2:addressline leap2:label="Town">Bolton</leap2:addressline>
<leap2:postcode>BL3 5AB</leap2:postcode>
<leap2:country leap2:countrycode="GBR">UK</leap2:country>
</leap2:spatial>

The spatial element may contain:

There can be any number of spatial elements within any item entry, particularly as needed to represent multiple addresses. A single leap2:spatial element may contain both xhtml (formatted but not otherwise recognisably structured) and structured address elements. However, not more than one structured address may appear in one spatial element. That is, there must be at most one postcode and at most one country, and the set of addresslines must sequentially represent just one address.

Where more than one address is given, they must be in separate spatial elements, and the unstructured parts may be used to indicate in a human-readable way what each address differently signifies.

Using these elements within leap2:spatial allows varying degrees of precision when specifying the location of, e.g., meetings or other activities. For instance, just the leap2:country could be specified, which would enable software to group activities or meetings by country. If addresslines are used, it is recommended that the result of stripping out the markup within the structured address elements, putting each sub-element on its own line, should result in a usable postal address.

See also the relevant section of the core specification

         

status

<leap2:status leap2:stage="planned" leap2:label="Desired" />  

gives an example. Status could also be called "progress".

Some kind of status or progress indicator is essential to the interpretation of activities and plans. One single set of values serve for activities, plans, and anything else that can use these.

A value given to the stage other than "completed" will not necessarily continue to be correct as time passes. The stage value should be correct as at the last revision date of the entry, and should be interpreted as such, rather than as reflecting the situation at the time of reading.

The status element takes one mandatory attribute, stage (below, exclusively for this element), and one optional attribute, label, which may be used to give the corresponding term as used in the interface of the exporting system. Systems may have different labels for the same stage, applied to different item types.

stage

The stage attribute value must be one of the four principle names only, as here below.

planned

This means that the item has not started and has not been done. It does not distinguish whether something is tentatively or firmly planned, on the grounds that there is no clear-cut dividing line. Other plausible labels include "desired", "intended", "tentative".

progressing

This means that the activity or plan has started, and is still active, but has not finished. Other plausible labels include "in progress", "current".

completed

This means that the item has been completed or achieved. Other plausible labels include "achieved", "succeeded".

suspended

This means that the item is not currently active, having been started, and then stopped, but not properly completed. It is ambivalent about whether it may or may not resume, on the grounds that this can rarely be known for certain. Other plausible labels include "withdrawn", "dismissed", "abandoned", "interrupted", "stopped".

See also the relevant section of the core specification

Structured content

The above point can be generalised and extended. There are certain uses of content that are designed both to be read by other people and to refer to other items in the same portfolio information. In particular, these may include CVs, views or "webfolios". In these cases, it is useful to be able to indicate from within the content what the relationship are of that item to other items, either just to link to them, or to embed something within a viewed page.

The specification for how to do this is given in a separate page on structured content.

version

Version applies only to the feed, not to item entries. The version should be consistent throughout the feed. The string for the 2010-07 version is

<leap2:version>http://www.leapspecs.org/2010-07/2A/</leap2:version>  

This is only mandatory where Leap2A elements or attributes are actually used, not for plain Atom feeds used to carry portfolio information. The 2009-03 version could be represented as

<leap2:version>http://wiki.cetis.ac.uk/2009-03/Leap2A_specification</leap2:version>  

Because the version element was not specified for the 2009-03 version, any feed with Leap2A constructs in it, but without a leap2:version element, should be processed in a way that is able to deal with any of the 2009-03 constructs. You should NOT now use

<leap2:version>http://wiki.leapspecs.org/2A/</leap2:version>  

unless or until the spec is further developed, and you want to include those developments that are not included in the 2010-07 version.

See also the relevant section of the core specification

Common attributes

These attributes below are shared between two or more elements. Attributes that belong only to one element are described under that element.

countrycode

This is an optional attribute of country, which could be used for automatic validation of the postcode. Is is also allowed alongside the country field of persondata and orgdata.

The attribute value must be a 3-letter codes from ISO 3166-1.

It is relatively straightforward to translate between 2-letter and 3-letter codes. There are useful articles on Wikipedia about ISO 3166. The following perl one-liner (split over two lines to fit) gives you a list of two and three letter codes for each country:

perl -MLocale::Country -le 'print join("\n", map { country2code($_) . "\t" . 
country2code($_, LOCALE_CODE_ALPHA_3) . "\t" . $_ } all_country_names())'

See also the relevant section of the core specification

display order

This is an optional attribute for parts. It represents the intended order of display in an ordered list.

The attribute value should be an integer, but they need not necessarily be successive integers. An item with a lower display order should be displayed before or above an item with a higher display order.

See also the relevant section of the core specification

field

This is the mandatory attribute of persondata and orgdata that identifies the nature of the data.

The attribute value must either be taken from the list of fields for persondata or the list of fields for orgdata or be a URI.

See also the relevant section of the core specification

label

This is an optional attribute for the Leap2A elements

The attribute value should normally be a system-generated string representing the label for a particular field as given in the user's interface. In this way, it adds useful context, and can be used by systems to guide re-importing what they have exported. However, there are other situations, including user-generated categories, for which the holder may create the label, and systems cannot use the label to guide re-import.

The atom:category element has the equivalent attribute, also "label", in the atom: namespace, so no namespace abbreviation is given with label used within a category element in Leap2A.

Apart from this category case, all other cases use the leap2: namespace, as leap2:label.

See also the relevant section of the core specification

service

This is an attribute of persondata and orgdata that identifies a related service for that piece of data. The service attribute is mandatory where the leap2:field="id".

The attribute value must either be one of the service abbreviations for persondata or for orgdata or be a URL for another service (not bound to a particular context).

Where it is desired to record an identifier with an organisation where either the holder is a member, or the identifier is relevant only to a particular activity recorded in the portfolio, this should be recorded using a Leap2A/affiliation or Leap2A/activity accordingly, not within persondata. Services recorded in persondata are often communication services, or long lasting services available in several contexts.

See also the relevant section of the core specification

when added

This is an optional attribute for parts. It represents the time at which the item was added to the particular list. If desired, this can be used as the basis of an ordering for display.

The attribute value should be a date-time string in the same format as updated, namely rfc3339.

See also the relevant section of the core specification

Namespaces

A suitable namespace must be declared, to use the above representations, and this form is recommended:

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

When the namespace and field name are concatenated, it should give a helpful URL of an informative page.

The default namespace is expected to be the Atom one

xmlns="http://www.w3.org/2005/Atom"