Belongs to the 2009-03/Leap2A specification > predicates
This page specifies sub-elements of entry/items, adopted or defined for this specification. Additionally and separately:
Contents |
<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).
<title>A self-explanatory portfolio item</title>
This is mandatory in Atom for every entry, and described in the Atom documentation.
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.
<content>This is some really simple content, 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.
Content has a type, which defaults to text, but can also be html or xhtml. Care is needed in following the Atom specification. If the type is html, any < and > signs from html markup must be escaped as < and >. If the type is xhtml, markup should not be escaped. There should be a single div element immediately inside the content (to be discarded on import) so that the whole content section is structured as follows:
<content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml"> <p>The actual xhtml content goes here, with < and > 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>
Atom provides for content of an entry to be represented by an IRI, rather than inline. Not enough experience has been built up to give reliable guidance on when this should be done, but in any case all the provisions of Atom should be followed, in particular section 4.1.3.2 of the Atom spec. This 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. You must use the specified '%20' for URL encoding spaces, 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.
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.
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.
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 2009-03/Leap2A structured content.
For the main Atom time fields, atom:published and atom:updated, rfc3339 is specified. This means that you must put in all the fields from years to seconds, and you must add a date-time zone indicator, either numeric or "Z" for UTC (=GMT).
For leap: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.
These are essential to many portfolio records. Atom comes with these two sub-elements of entry (examples taken from the Atom documentation). These date-times must conform to rfc3339.
<published>2003-12-13T08:29:29-04:00</published>
This corresponds to dc:created, (URI) If known, this should be the initial date of creation of the record. The text node must conform to rfc3339.
<updated>2005-07-31T12:29:29Z</updated>
<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.
These are used here in the same sense as Atom, to indicate dates relevant to the record itself, not to any times or events referred to by, or relevant to the subject of the entry.
In this version of this specification there is no place for a separate date of publication, other than the date of creation. As items are made public through selections, it is suggested that the date of creation of a selection could represent the date of being made public.
Time information connected with the subject matter of the records, as opposed to temporal metadata about the records themselves, is represented with this new leap:date element, and can use any of the W3C date time formats.
The date element takes one mandatory attribute, point, and one optional attribute, label.
The point attribute of the date element has three possible values:
represents the envisaged, planned, or actual finish date. While in the future, this may be changed freely, following the user's planning process. Example:
<leap:date leap:point="end" leap:label="Christmas 2009">2009-12-25</leap:date>
represents the envisaged, planned, or actual starting date. Example:
<leap:date leap:point="start">2009-03-19</leap:date>
if present, may represent a firmer end point, whether determined by the user or set externally. Example:
<leap:date leap:point="target">2010-01-07T17:00:00+00:00</leap:date>
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.
If any chronological display and management is to be supported, or to enable effective planning and scheduling, these leap:date fields need to be represented machine-processably, containing ISO standard dates as the element content. However, some systems may represent dates only as text fields. These systems may export empty leap: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.
<leap:date leap:point="start" leap:label="Summer 1999"></leap:date> <leap:date leap:point="end" leap:label="Summer 1999"></leap:date>
This is the time actually spent on an activity, for assessment, credit, time accounting or just personal record purposes.
<leap:activetime>PT8H30M</leap: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.
<leap:spatial>In the headteacher's office</leap:spatial>
This may be used as a simple textual field, following Dublin Core. See dc:spatial (URI), which this matches exactly.
It may also be used to contain an address. For example:
<leap:spatial> <leap:addressline>University of Bolton</leap:addressline> <leap:addressline>Deane Road</leap:addressline> <leap:addressline leap:label="Town">Bolton</leap:addressline> <leap:postcode>BL3 5AB</leap:postcode> <leap:country leap:countrycode="GBR">UK</leap:country> </leap:spatial>
The spatial element may contain any number of addressline elements (normally fewer than 6); zero or one postcode elements, and zero or one country elements.
Using these elements within leap:spatial allows varying degrees of precision when specifying the location of, e.g., meetings or other activities. For instance, just the leap: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 spatial element, putting each sub-element on its own line, should result in a usable postal address.
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.
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".
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 leap: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.
<leap:status leap:stage="planned" leap:label="Current" />
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.
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.
The stage attribute value must be one of the three principle names only, as here below.
Other plausible labels include "desired", "current", "intended".
This is intended for activities and plans. Other plausible labels include "in progress", "current".
Other plausible labels include "achieved"
This is an optional attribute for parts. It represents the intended order of display in an ordered list. The 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.
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 value should be in the same format as updated, namely rfc3339.
This is an optional attribute for the Leap2A elements addressline, date, orgdata, persondata and status. It is intended to represent 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.
Atom has the equivalent attribute, also "label", but only within the atom:category element. Outwith this usage with atom:category, it is therefore namespaced with "leap:".
This is the mandatory attribute of persondata and orgdata that identifies the nature of the data.
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 leap:field="id".
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.
This version of Leap2A follows SIF in using 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 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())'
A suitable namespace must be declared, to use the above representations, and this form is recommended:
xmlns:leap="http://wiki.cetis.ac.uk/2009-03/Leap2A_predicates#"
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"
