How to Implement Leap2A

Implementing the Leap2A specification can be broken down into the two distinct options of Exporting and Importing. Exporting in Leap2A is the process of outputting your systems mapped objects into an the Leap2A format which can them easily be imported by any other software that is able to import Leap2A. Importing Leap2A is the process of mapping as much of the Leap2A specification as possible to your own system types to enable as much of another systems export to be imported. Exporting and Importing are discussed below.

Exporting

The main challenge in exporting information is getting the mapping right. This page is intended to help you think about the portfolio information in your system in a way that will be easiest to map onto this specification, and then to identify the right types, relationships and categories for each item. The question of mapping is never going to be completely obvious, because with information as soft and complex as this, there are bound to be several ways of mapping the same thing. The purpose of the guidance here is to help people to find the same way.

Mapping your information

First, a few general principles which might help orient you to the recommended approach.

Focus on what constitutes a Leap2A item, which in turn is represented as an Atom entry. Remember that in essence Leap2A consists of portfolio items linked by meaningful relationships, not a tree structure.
If there is a choice of using one or two items, prefer just one. Generally, do without unnecessary items.
Don't go against the way Atom does things. A title is a title or heading; content is content or description.
Only use hierarchical structure if you have to. Prefer representing structure in terms of meaningful relationships and/or categories. Try not to use selections unless there is no better way.

Finding the right granularity of item

Let us consider any "chunk" of information that may be recorded in a portfolio or related system, and find the right granularity to fit properly with this specification.

Firstly, can parts of the chunk be reused separately and independently? For example, perhaps you have a structure where a number of actions or activities are listed. If the list is simply one piece of text, you cannot easily break it up and it will have to remain as a whole. But if the actions are stored separately, it is possible that each action could be thought of separately, one action could be changed, replaced, or left out independently of the others. In these latter cases, your original chunk is too large, and needs to be split into its parts.

Now it may be that the large chunk simply consists of smaller chunks, with nothing left over. More likely, perhaps, is that there are a set of smaller chunks, and something in the middle that holds them together. This is fine: there are structures in this specification that allow you to handle that case well, including the selection type.

Secondly, and conversely, does your chunk of information mean anything by itself? A date, by itself, means nothing. A title is lost without being attached to the thing it is the title of. If your chunk means nothing by itself, it is probably too small, and needs to be lumped together with enough other things so that the set of information has independent meaning.

But this is not quite always true, and this is the exception. Often, perhaps in personal development planning, there will be a set of related questions with text answers. For example, your system may invite learners to reflect on different aspects of a particular experience. Because of the way that the questions are introduced, the resulting short pieces of text - perhaps down to one sentence, or even just a phrase - may make no sense out of context. In order to convey as much as possible of the structure of these answers, each answer needs to be represented by itself, with relationships and categories put in to clarify as much as commonly possible the role of each piece of text in context.

As a rule, one portfolio item, in terms of this specification, can only have at most one piece of independent text, which is its main content or description. All other pieces of text that are stored separately need to be represented as independent portfolio items.

When you have broken down, or lumped together, the portfolio information in the ways described, you will be left with a set of related portfolio items that can be represented in terms of this specification. An attached file is a special case. A file by itself may be referred to by portfolio items, but to integrate best into the rest of the portfolio information, a file really needs to have some information about it recorded in a format which fits in with the rest of the portfolio information. Information about a file will normally be a resource in terms of this specification, unless the file stands in for the content of an item. The file and this resource information can be thought of together: in fact for the rest of the process here the file itself need not be considered, as it will be the resource (or other item) information which will have type, relationships and categories.

Which type of portfolio item is it?

If it is information about a digital artefact - that is, effectively, a file - the type will usually be resource. The only exception to this may be that a file is simply the content of another item, and these are discussed now.

If the item is a piece of text that is not the (main) description of some particular thing, then the item will be represented as an entry. This will become clear only after considering whether it fits into any of the other types.

At this point, you can refer to the page on types and see which type fits best. You will want to consider the relationships which the item has with other items, and the categories which may fit it. However, there are some tricky cases where some guidance may be of help.

The type is represented with an rdf:type element.

Achievement, activity, or plan?

These types can be easily confused. If I want to walk up a hill, is that a planned activity or an actual plan? If I walked up a hill, was that an achievement or a past activity? It is particularly difficult to distinguish when the item is described, as here, by a short phrase or sentence.

There are clear logical distinctions that can be made. Activities take time; achievements are states of the world that have been reached; plans include a goal to achieve in the future. That is, activities have two associated dates, for a start and for a finish, while achievements have only one, the time at which they were achieved.

In that something has distinct start and finish times, it must be an activity or plan of some kind. The walk itself, if planned, is a planned activity, which could be part of a plan. Clearly it could be planned to start at a certain time, and expected to finish at a certain time. If in the past, it will have definite start and finish times. The related goal could be reaching the top of the hill (and return safely). If the goal is just to walk up the hill nearby, that may not need much of an explicit plan, but if it is climbing a Himalayan peak, it will need a plan, which may comprise many activities, and when it is achieved, you may well want to count it as an achievement.

Plans, which are very significant in much portfolio-related practice (e.g. personal development planning) do complicate matters slightly. Because a plan is associated with a goal, it may have a target date for completion. On the other hand, the execution of plans takes time, and involves several activities that take time, and these activities will have an overall start and finish date, which can be associated with the plan.

The important thing is to try to distinguish these types in a clear way that is likely to be the same as the way other people distinguish them. If something is going to count as an achievement, then it is likely to deserve a plan. In this specification, the goal of a plan is represented by an entry which expresses the goal, as a desired state. This is (hopefully) similar to the way in which the achievement is described when it is achieved. Anything that is not, or is not going to be, counted as an achievement may safely be regarded as an activity or action. Small action points, or steps if you like, may just look like sub-goals, particularly if they have no times attached to them, but as they may actually have start and finish times, it will work to represent them as activities.

Ability

One of the confusing things about abilities is the many terms that can be used, including skill, competence, and competency. Though distinctions may be made, all of these are about what someone may be able to do, possibly in certain circumstances. Qualifications are also related, but perhaps slightly more complex. A qualification is evidence that a person has demonstrated certain knowledge or abilities in certain defined situations, assessed in a particular way.

There are two positive ways a person may relate to an ability. Someone may aim to acquire or achieve an ability, or they may claim to have (or not to have) that ability. These are clearly closely related, but equally clearly opposite in meaning! For representation of portfolio information, it is essential to distinguish these two unambiguously.

A safe way that is the basis of representation for this specification is to represent the ability as an impersonal definition. Thus, an ability as such is not the statement "I can ride a bicycle", but something more like "able to ride a bicycle (along a road safely)".

The statement "I can ride a bicycle" is a claim, which is represented in this specification as an entry. This claim may have evidence attached. Obvious things to attach as evidence would be a video of you riding, or a statement from a reliable witness. However, it is also common practice, which can be represented in this specification, to skip the claim itself, and simply to record as evidence things that are evidence of the ability, with the tacit assumption that the portfolio holder is claiming that ability.

Structured questions

Particularly with materials that are more guided, perhaps for younger people, often one sees much material entered by a user that is essentially in answer to some questions. Each answer may not make much sense by itself. Sometimes the answers are short one-liner pieces of text; sometimes they are not text at all, but check boxes or selections, as in some questionnaire responses.

Examples may help: try looking at the Leap2A case study 1.

In Atom there is no smaller unit for a text answer than the atom:entry, so for text questions/answers, create a separate entry for each question/answer. Put the question, if less than about 80 characters, in the atom:title element. If the question is longer, put a short version in the title.

If the question/answer pairs are understandable on their own, and they relate to a substantial item such as an activity, just have them as separate entries, with a link rel="leap:supports" to the main item. This is a very general idea of supports, in that the questions and answers support the understanding of the activity.

Alternatively, if there is more context that is needed to allow understanding of the answer, or if the questions are long and involved, if there is more than one answer on a page, and if there is no main item to relate them to, create a selection with a category of Grouping. Put contextual material in the selection content, and have each separate question/answer as "part of" the Grouping selection.

Non-text answers can be handled in a similar way, with a separate entry for each answer. The title of the entry can be the question, and in the content, put a text representation of the answer. Each answer entry can additionally have a category, which makes the answer unambiguous, and is more likely to map onto the answer to a similar question than plain text.

There is another pattern that could be considered for more complex questions. The question itself can be given as a separate entry, with care being taken to ensure that the author of that entry is not the portfolio holder, but rather the system, the host institution, or someone with authority in the host institution. The answer can then be given "in reply to" the question. This could even be used for questionnaire-type sets of questions with non-text answers. The questionnaire could be given as the question entry, and the answer entry could have one category for each answer. The categories would have to be specially constructed for each question and answer.

Exporting items

Adding literal metadata

Once you have established the type of a given item, you need to add required sub-elements to it. Start with the literals applicable to all types. Atom's title is mandatory, as is id (guidance givenelsewhere). Author must be given for an entry if it is not for the feed as a whole.

Then move on to the appropriate type in the type specifications where further guidance is given.

Noting the relationships

After determining the literal metadata, you will need to add the relationships as atom:link sub-elements to the entry. Relationships are a vital part of portfolio information in general, and for this specification in particular they are fundamental, as the principle of splitting the information into small items removes much of the possibility for tacit relationships to be implicit in the information structure. So try to include as many relationships as are meaningful.

On the appropriate part of the types page you will see the expected relationships for the type, and you can click through to see the relevant definition in the relationships page.

Now, there is an issue with whether the relationships are always defined at both ends, or not. Ideally, they would be, so if you can do this, so much the better. However, for an initial implementation, this may be simply too much hard work. In this case, you need to make it clear to partners that you are exporting at least some one-ended relationships. If you do have relationships represented at both ends, the one in one entry must be the correct inverse of the one in its related entry.

On the whole, it is advisable to start by considering whether you can apply the most specific relationships first. These are the ones for meetings, and for threads. Then consider whether one item is considered to be evidence of another. This may be implicit in your system, rather than explicit. If none of the more specific relationships holds, you may consider the support relationship and its inverse, which is relatively general but still directed, or the relation relationship which is completely general and non-directed.

For selection types, that is, anything which is essentially composed of parts, the important decision is whether the parts have a significant order or not. See the selection type categories. If they do not, or if the order is given by the selection content, it is easier to use the plain part relationships. If necessary, use the ordered part relationships. See the appropriate part of the relationships page.

Importing

The overall task for systems importing Leap2A portfolio material is, for each set of related information, to identify the closest corresponding structure within their system, and then to populate it with the information presented.

For some Leap2A items, this will be fairly straightforward. For instance, if your system holds meetings as a particular type of thing, and if a Leap2A meeting is encountered, there is a good chance that the information relating to the Leap2A meeting will slot into your meeting structure. You will know roughly how much it does through you knowledge of exporting your meetings in Leap2A representation.

But for other items, particularly Leap2A entries, it may be less immediately clear where the information goes. You may need to take into account not only the type (in that case, an entry), but also some of the relationships and possibly categories.

Leap2A information does not have a defined order, and in any case, whatever order the information comes in, there can be no guarantee that all items will be defined before being referred to. Hence, before putting the information into your database, it will make sense to construct an overall map of the information, with a first pass through it, so that at a second pass, it will be clear what everything relates to and therefore where it should go.

For example, one could first build some temporary database tables.

One table would be the entry id and type table, where each atom:entry had noted

its ID (which would be unique)
its rdf:type

A second table could be a link table. For each atom:entry/link one could have

the relationship type
the source entry id
the destination entry id

Because the relationships can be noted at either end or both ends, it would be a good idea to go through at some point filtering out duplicate inverse relationships, where the same relationship between two entries has been noted using inverse relationships.

A third, category table may or may not also be needed, which would have

the entry id (not necessarily unique)
the category scheme-term, made up by concatenating the scheme and the term strings

Relationship directions

It was noted in the Leap2A exporting page that some systems may not export all the relationships bidirectionally. For these systems, there may be a relationship one way, but not the other way.

A superior, sophisticated importing capability will be able to handle unidirectional relationships. A simple one may not, or may be able to handle only some unidirectionality. Please ensure that this aspect of your import, as well as export, is fully tested and documented.

Individual approaches

These should be documented in, or linked from, the PIOP partner pages.

Leap2A for e-portfolio portability and interoperability