Belongs to the Leap2A/specification
This is the original documentation for personal data on Leap2A.
The core of this has been included in the relevant section of the core specification, but this documentation is left here for reference and further notes.
Some information is not really to do with portfolio practice, particularly in the PDP sense but is there to identify and give basic factual information about and contact details of, the portfolio holder, for possible use in CVs, presentations and indeed portfolios. To keep this conceptually separate, this is represented by the separate persondata element.
This information is placed only in an entry of type person. There is a parallel structure for organizational data within an entry of type organization. Student, staff, employee, etc. ids dependent on role are properly held in the activity entry they relate to.
This element is for non-relational data about a person - that person's literal attributes if you like - and belongs within a person-type entry. The most important reason for this is to ensure that information about a person is listed exactly once, rather than duplicated.
Within the person entry, any number of leap2:persondata elements can appear. For example:
<leap2:persondata leap2:field="legal_given_name" leap2:label="First name">Andrew</leap2:persondata> <leap2:persondata leap2:field="legal_given_name" leap2:label="Middle name">Simon</leap2:persondata> <leap2:persondata leap2:field="legal_family_name">Grant</leap2:persondata> <leap2:persondata leap2:field="preferred_given_name" leap2:label="Name used">Simon</leap2:persondata> <leap2:persondata leap2:field="email">firstname.lastname@example.org</leap2:persondata> <leap2:persondata leap2:field="mobile">+447710031657</leap2:persondata> <leap2:persondata leap2:field="country" leap2:countrycode="GBR">UK</leap2:persondata> <leap2:persondata leap2:field="website">http://www.simongrant.org/home.html</leap2:persondata> <leap2:persondata leap2:field="website" label="Blog">http://blogs.cetis.ac.uk/asimong/</leap2:persondata> <leap2:persondata leap2:field="website">http://en-gb.facebook.com/people/Simon-Grant/616865170</leap2:persondata> <leap2:persondata leap2:field="website">http://www.linkedin.com/in/asimong</leap2:persondata> <leap2:persondata leap2:field="website">http://www.slideshare.net/asimong</leap2:persondata> <leap2:persondata leap2:field="id" leap2:service="skype">asimong</leap2:persondata> <leap2:persondata leap2:field="id" leap2:service="miap_uln">1234512345</leap2:persondata>
There is one mandatory attribute and there are three optional attributes.
Each persondata element has a mandatory leap2:field attribute to distinguish what the field means.
The attribute value should normally be taken from the list below. Otherwise, for extension purposes, the value of the leap2:field attribute can be a URI, identifying a non-Leap2A predicate or property.
Where needed, this attribute gives the service associated with the information in the field. The attribute is required if the field is "id".
The attribute value may be one of the abbreviations given below for service providers that are currently in frequent use, or if the service is not listed here, it could be a URI or URL of a service provider. A service provider can be on the web, such as Google, but can also be a service that could be offline, such as MIAP, or UCAS, or an educational institution providing educational services. The value of the service attribute could also, in principle, be an internal reference to an organization, but there is no practice yet built up. In all cases where a URL is given as the attribute value, it is suggested that the one used should be the shortest that is completely associated with that id and no other id.
This is an optional attribute intended to hold the version of the field name given in the originating system. However, it is mandatory where the field is "other".
The attribute value must be a plain text string.
This is optional, but specifically only for the "country" field, as in addresses, and no other fields.
As persondata element always have an order of occurrence in the XML, the order in which they occur is taken to be the order for display. Thus there is no need for the attribute "display_order" - indeed it could introduce confusion. If the family name is first for this person, it is recommended that, as well as including the "family_name_first" field with value "yes", family name fields are shown before the corresponding given name fields.
M is the allowed multiplicity within a single person entry.
|0..1||text||This is equivalent to a concatenated subset of prefix, legal given names, preferred given name, legal family name, preferred family name, suffix (given and family reversed if family name first)|
legal family name
legal given name
|0..*||text||It is not important how these are split, except to provide a default preferred name. The order in the XML should be the same as the order in legal documents.|
preferred family name
|0..1||text||If not present, assume legal family name is preferred|
preferred given name
|0..1||text||Name treated as single name. If not present, assume first legal given name is preferred.|
family name first
|0..1||Following MIAP: "yes" or "no": default = "no".||Because the default is "no", this field will not be needed for most European/American and many other names.|
|0..1||text||serves as honorific "title"|
|0..1||text||Everything after the main name parts|
|0..*||countrycode (optional)||Text. But, as in addresses, with an optional attribute of leap2:countrycode following SIF(UK): 3-letter ISO 3166-1 code.||This may be nationality, but as the details of nationality, citizenship etc. are highly complex, it is better thought of as association with a country. More significant country connections should be listed in the XML before less significant ones.|
|0..1||W3C Complete date, e.g. 1989-03-20||If more precise format is used, any time part should be treated as insignificant.|
"0 = not known, 1 = male, 2 = female, 9 = not specified.
|0..*||URL||Any URL associated with the holder, including profiles. The order in the XML should reflect the order of importance or significance given to the URLs by the holder.|
|0..*||service||string||A context-free service ID through which other people can access information about or communicate with the holder (including, e.g. IM and VOIP). IDs that are specific to a context should be given in their context, as roleid within e.g. an affiliation or activity.|
|0..*||Specifically, the openid service which extends across many service providers|
||0..*||e-mail: rfc5322||If there are multiple e-mail addresses given, the preferred or default one should come first in the XML.|
|0..*||recommended format: full international, starting with + (+44 for UK)||If an exporting system attempts to replace a leading "0" in an unchecked field with "+44", the number should first be checked as a plausible UK number.|
|0..*||recommended format: full international, starting with + (+44 for UK)|
|0..*||recommended format: full international, starting with + (+44 for UK)|
|0..*||recommended format: full international, starting with + (+44 for UK)||Included because of SIF(UK) having it.|
|0..*||recommended format: full international, starting with + (+44 for UK)||Surprisingly, several people still record this information.|
|0..*||label; your own (optional)||use the label to indicate what the field is about||Obviously, do not use this for information which could go in an existing field. You can add an attribute with your own namespace to specify for yourself.|
These are the ones specified for this version.
|miap_uln||http://www.miap.gov.uk/products/uln/||The Unique Learner Number provided by the UK Learning Records Service|
|msn||http://www.msn.com/||IM, VoIP, etc.|
|http://twitter.com/||The currently fashionable micro-blogging service|
This part of the specification has been designed with several related things in mind, including:
Old cross-reference table
This old table cross-references several different specifications and usages. However, it only gives outline information, omitting several details about the fields in the different systems and specifications. It is intended to allow a broad view relevant to what to include in Leap2A, not the detail of exactly how to specify the fields.
The information about different specifications and usage is not guaranteed to be accurate. Please check with an authoritative source.
Also, not everything adopted above is entered here.
Where the specification or usage clearly appears not to represent a particular field, this is shown with "~".
|MIAP CDD||SIF (UK)||HR-XML 3||h/vCard||:||PebblePad||ePET||Nottingham||Mahara|
|legal family name||Person Family Name||FamilyName||FamilyName||~||:||Surname (official)||surname||surname||lastname||.|
|legal given name||Person Given Name||GivenName MiddleNames||GivenName MiddleName||~||:||Forename, Middle Name (official)||forenames||FirstName OtherNames||firstname||.|
|preferred family name||Person Preferred Family Name||PreferredFamilyName||~||n family-name||:||Surname (preferred)||.|
|preferred given name||Person Preferred Given Name||PreferredGivenName||PreferredGivenName||n given-name||:||Forename (preferred)||PrefName||preferredname||.|
|family name first||Person Preferred Family Name First||PreferredFamilyNameFirst||:||.|
|name prefix||Person Title||Title||PreferredSalutation||n honorific-prefix||:||Title/prefix||Title||.|
|n honorific-suffix||:||Post nominal letters||.|
|dob||1.7||Person Birth Date||BirthDate||BirthDate||bday||:||Date of Birth||DOB||DOB||.|
|1.5||Person Email Address||Email (in EmailList)||(structured)||:||.|
|homephone||1.3||Person Telephone Number||PhoneNumber (Home)||(structured)||tel||:||Telephone||Phone||TelCode, TelNumber||homenumber||.|
|workphone||1.3||Person Telephone Number||PhoneNumber (Work)||(structured)||tel||:||Telephone||Phone||TelCode, TelNumber||businessnumber||.|
|mobile||1.3||Person Telephone Number||PhoneNumber (Mobile)||(structured)||tel (cell)||:||Mobile||Mobile||MobileNumber||mobilenumber||.|
|fax||PhoneNumber (Fax)||(structured)||tel (fax)||:||.|
|Street||StreetName||street-address||:||Address Line 1||Street||address||.|
|Locality||locality||:||Address Line 2||Town||town||.|
|~||Unique Learner Number, etc.||(various)||~||:||studentid||.|
Notes on names
With non-British/European/American names, there is the issue of which name comes first, the family name or the given name. SIF (UK) follows MIAP, which has fields "Person Family Name First" and "Person Preferred Family Name First", with the values "yes" or "no", "no" being the default. Other practice, including vCard, is to hold the full, formatted name separately, indicating the correct order. Once one has the preferred family and given names, the only variable is which way round they are, so it seems rather unnecessary and error-prone to hold the full name separately.
Nicknames seem problematic. Preferred given name appears to do the job of a single consistently used nickname. Other nicknames probably depend on context, and therefore belong in a rather different place.
A personal portfolio would probably want a preferred name in any case, rather than a legal name. A single family name field and single given name field, to be interpreted as the ones that are preferred, along with a field equivalent to the "Family Name First" fields of MIAP CDD and SIF (UK), would be sufficient to give a name on the top of a CV.
However, to avoid confusion, the proposal is to have preferred family and given names, and optionally legal family and given names.
There are different structures possible here. The HR-XML structures include
- Mobile Telephone
- Instant Message
- UseCode: either Personal or Business
then other details depending on the ChannelCode. The mapping is not entirely clear, but it seems possible to make reasonable guesses which should work most of the time.
SIF(UK) has these phone types:
- A Alternate Home
- D Minicom (hearing impaired/disabled)
- F Fax
- H Home
- M Mobile
- W Work
As there seems no reason to arbitrarily leave out any of these, the proposal covers all of them. SIF's alternate home phone can be coded as another homephone, relying on the order of presentation to be the order of priority, if any.
Notes on addresses
One big challenge of addresses is that they are typically multiple for one individual. There must therefore be some structure somewhere. Either we have to have a structured address element within a person entry, which can be repeated, or we have to have a separate entry for each address.
Not surprisingly, there is no real agreement on how to break down an address into individual fields. The way of setting out an address is notoriously dependent on convention, national custom, politics, local and personal animosity, and vagaries of individual addresses.
In the MIAP CDD documentation there is a note that says "The use of multiple address lines is proposed as a practical way of taking forward a standard approach to addressing in parallel until BS7666 becomes fully usable in practice. Multiple address lines will satisfy the Conformance Notes majority of the requirements for address data in the post-16 sector, and this is proposed in the initial set of CDD."
For portfolio purposes, it would appear to be satisfactory to be able to produce a postal address that works, either for postal delivery or finding an address on the ground. Thus, a combination of address lines plus postcode and country would seem to be a reasonable approach for LEAP2A.
Notes on countries
Most people probably use plain text to represent a country, so we will stay with that as the basis.
For consistency and accuracy, it would also be good to have the countries, both of citizenship and address, as ISO codes of some sort. SIF (UK) uses "The 3-character alphabetic country code defined by ISO 3166-1." Moreover, they seem to be consistent about this. In "Implementation of the MIAP Common Data Definitions Phase 2" has a country as simply an address line type, which is not easily checkable. For Nationality, MIAP uses the two-letter form of ISO 3166-1, just to be confusing. However, we need to recall that various postal services use different country names, which are not necessarily the same as each other. An ISO code may well not be recognised as part of a postal address.
Given an unambiguous postal country, it is not difficult to find the form of the postcode for that country. Could we perhaps follow SIF in this instance, and use the 3-letter ISO code in all places? Or simply allow either 2-letter or 3-letter codes, as they are very easy to interconvert.
The proposal is now to have an unstandardised text in the main text, and an optional leap:countrycode attribute to hold the 3-letter code, following SIF.
Some useful sources
Note that many SIF UK fields have slightly different names from the American SIF fields.