This schema describes the EMREX ELMO XML format, used for formatting students'
Transcripts of Records.
This format was first used for formatting content returned in EMREX EMP
responses. For more information on EMREX, please visit http://emrex.eu/.
Status of this document
=======================
This schema has been ACCEPTED by all the partners. It has been agreed that
schema designers SHOULD attempt to keep all future schema releases
backward-compatible with the 1.0.0 version. However, at the same time, it was
noted that some backward-incompatible changes MAY arise during EMREX field
trial test, and a `v2` major version of the schema MAY be released.
Also see the versioning and backward-compatibility sections below.
The list of all the officially released schema versions can be found here:
https://github.com/emrex-eu/elmo-schemas/releases
Usually you should be using the latest release of the schema (for implementing
both servers and clients).
Relationship with the other schemas
===================================
The EMREX ELMO format is loosely based on the "ELMO" schema used in various
sources under the namespace of "http://purl.org/net/elmo". However, the
original ELMO XSD schema seems to be unsupported by its authors and it is very
hard to find any official version of it. You can find some (possibly obsolete)
XSDs in the Git history of THIS repository
(https://github.com/emrex-eu/elmo-schemas/), but EMREX ELMO format is no longer
compatible with those XSDs.
The following terms are *equivalent* throughout the EMREX specs:
- EMREX ELMO format (this is the "official" name of this format),
- EMREX response file,
- EMP response file,
- ELMO file.
A general note for server implementers
======================================
(Server implementers are these developers who *generate* the EMREX ELMO
format in their code.)
Before you start implementing, be sure that you are reading the most recent
version of the schema! See status and versioning sections.
Most of the elements described in this schema are marked as optional, but they
are *strongly recommended*. Even for the vital elements, we allow them to be
non-existent, but this is solely to support some uncommon edge cases. You
SHOULD include as much data as you can. The less data you include, the less
usable your file will be (although, of course, if you know exactly how it will
be used, you are allowed to skip unnecessary parts).
Also, please note, that reading all the schema annotations is crucial in order
to produce a valid EMREX ELMO element. Some restrictions cannot be expressed by
the schema language itself, some others we chose not to express in this way, to
avoid complexity. However, the schema itself, combined with all the annotations
included within it, should be clear enough. If it is not, then please contact
us.
Unless explicitly stated otherwise, all elements (such as names or
descriptions) MUST contain plaintext values (and MUST NOT contain HTML markup).
If you store some of the values in HTML form in your database then you MUST
strip the HTML markup (possibly in such a way that will still leave the content
formatted in a way that will make it easy for a human to read its contents).
In case when EMREX ELMO elements are embedded in other XML files, you SHOULD
consult the XSD annotations found in those "parent" files. There might be some
additional requirements the server (or clients) are required to meet.
A general note for client implementers
======================================
(Client implementers - the developers who attempt to *parse* the EMREX ELMO
format in their code.)
You MUST expect the worse. It is possible that the file you receive will not
contain much data. In such cases it might not fit your requirements for
automatic processing and you would need to send it "to a human" for manual
processing. The PDF attachments (documented below) should be of use in such
cases.
In case when EMREX ELMO elements are embedded in other XML files, you SHOULD
consult the XSD annotations found in those "parent" files. There might be some
additional requirements the server (or clients) are required to meet.
Backward-compatibility policy
=============================
If you are implementing your client using the `X.Y.Z`th version of the schema,
you MUST be prepared to receive the `X.Y+1.Z`th version at any time. Once the
field trail finished (and EMREX is released to be used by everyone), all newer
versions of the schema MUST be backward-compatible, so both sides MUST adhere to
the following rules:
- Client implementers MUST ignore all unknown elements and attributes.
- Schema designers must change the existing elements in a backward-compatible
manner. If it it impossible to upgrade an element without breaking backward
compatibility, then a new element should be added (while preserving the old
one - for the sake of older Clients).
- More backward-compatibility rules may apply in regard to particular schema
elements. You MUST read all the annotations for each of the elements.
A general note on schema versioning
===================================
We follow the "Semantic Versioning Specification" in our releases:
http://semver.org/
Please note that the targetNamespace of this schema contains an URL which
resolves to a GitHub webpage with the content of the XSD file. The URL contains
a Git branch name - the *major* version of the schema:
https://github.com/emrex-eu/elmo-schemas/tree/v1
Additionally, we release new versions of the schema as Git tags. Every
version number consists of three parts (X.Y.Z) which conform to the Semantic
Versioning Specification. In particular:
* If a documentation is being clarified (in a insignificant way), the XSD can
be altered in the master branch. Periodically, such changes are merged to
the v1 branch and the THIRD number of the version string is then incremented.
* If the schema is changed in a significant way, for example a new element is
added, but the change does not break backward compatibility, then the SECOND
number of the version string MUST be incremented. (The namespace itself is
not changed.)
* The FIRST number of the version string (along with the number within the
target XML namespace of the schema) will be increased ONLY if major backward
incompatible changes occur. And backward-incompompatible changes MUST be
avoided (especially after the EMREX trial is finished!).
Also note, that some future versions of the schema MAY be hosted in elsewhere.
As one EU project ends, and it is being continued by some other EU project, the
ownership of the GitHub project MAY change. However, the XML namespace itself
SHOULD NOT change in order to stay backward-compatible. GitHub's redirect
features can be used in such cases:
https://github.com/blog/1508-repository-redirects-are-here
The datetime when the file was generated. It SHOULD contain the timezone
suffix. Example values: "2015-08-01T12:00:00+02:00", "2015-08-01T10:00:00Z".
This describes the student whose achievements we will be describing. One EMREX
ELMO element may contain multiple reports, but all of the reports are always
describing exactly one student.
The ISO 3166-1-alpha-2 code of the country the student is a citizen of.
E.g. "PL".
For server implementers: If this is not known then you MUST skip the element
altogether (instead of, for example, providing an empty value).
For server implementers: Please read thought the list of predefined identifier
types below and try to provide all of those you can get. We are aware that
some of those will be difficult to get (especially for the foreign students).
For client implementers: If a given identifier is present you can use
it for any purpose you want. However, you should expect them to be NOT present
most of the times.
Currently there are only a few predefined types you can have here:
nationalIdentifier - if present, then the value of it should contain the
"primary" national identifier of the student. For more information on
national identifiers used for various nationalities, see:
https://en.wikipedia.org/wiki/National_identification_number
esi - European Student Identifier. For more information see:
https://wiki.geant.org/display/SM/European+Student+Identifier
You can also have any number of custom types. Contact us if you'd like
them added to the official specs.
The given names of the student. All servers MUST provide it (if it is impossible
for some reason, please provide an empty string here).
The family name of the student. All servers MUST provide it (if it is impossible
for some reason, please provide an empty string here).
For server implementers: The birth date is vital to EMREX and SHOULD be provided.
If you cannot provide it, you MUST skip the bday element altogether.
For client implementers:
- Remember that xs:date format allows for the value to contain a time zone.
You might need to remove the time zone date before parsing it!
- The birth date combined with the names of the student should be enough for
you to identify such student automatically within your system. Please consult
EMREX documentation for more information.
The student's place of birth.
For server implementers: If this is not known then you MUST skip the element
altogether (instead of, for example, providing an empty value).
First name(s) and family name(s) of the student at birth, described as a single text value.
For server implementers: If this is not known then you MUST skip the element
altogether (instead of, for example, providing an empty value).
The student's current physical address. This is the address which should work when, for example,
the user pastes it (without the recipientName part) into Google Maps.
This element has been described in detail in Erasmus Without Paper:
https://github.com/erasmus-without-paper/ewp-specs-types-address
ISO/IEC 5218 code of human gender.
https://en.wikipedia.org/wiki/ISO/IEC_5218
Unknown - the gender of the person has not been recorded.
Male
Female
Not Applicable - indeterminate, i.e. unable to be classified as either male or female
Responses MUST contain at least one report.
Please note, that one response may contain multiple reports, issued by
different institutions. All of those reports MUST be issued for the same
student though (that's why the learner element is placed outside of the
report element).
This describes an institution (issuer) and a *subset* of courses *completed*
by the student within this institution.
This element identifies the host institution - the institution at which the
student has studied in order to achieve the credits described in this report).
Note for server implementers: If your data comes from multiple institutions then
you MUST put it inside separate report elements.
An ISO 3166-1-alpha-2 code of the country in which the institution is
operating. If the country is not known, or the institution is an international
one, then this element MUST NOT be present.
For server implementers: You MUST be able to provide at least one identifier of
the institution. You SHOULD provide all of them, if you can.
Please note, that you might be able to generate SCHAC identifiers by yourself,
based on the knowledge of the web domain bound to this institution. If you
don't have any other ID, use your "best guess" for the SCHAC ID. SCHAC
identifiers may change in time (e.g. after institutions are merged), but you
should use your best guess nonetheless.
These are the currently supported predefined types:
pic - the PIC code,
erasmus - the ERASMUS code,
schac - the SCHAC identifier (e.g. "uw.edu.pl"). These identifiers are used
in other EU projects too, in particular the EWP (Erasmus Without Paper)
project. See here:
https://github.com/erasmus-without-paper/ewp-specs-api-registry/#schac-identifiers
address - full address of the institution (e.g. streetName 1, postNumber, city, state, country)
You can also have any number of custom types.
The name of the institution. May be provided in multiple languages. At least
one name is required.
For server implementers:
- This element SHOULD contain the xml:lang attribute. You may skip the xml:lang
attribute only when you really don't know the language which your will be
using here.
- You SHOULD try to include the name of the institution both in English and
in the original language.
The URL of the intitution's web page. It is a required element, because it
should be easy to acquire it on server's side, and it might be used as a last
resort when attempting to pinpoint the issuing institution on the EMREX
Client's side.
Please consult the documentation on the LearningOpportunitySpecification type.
Additional note for client implementers:
Please note that it is ALLOWED for the report to contain zero
learningOpportunitySpecifications. This may happen for example when the student
has unchecked all the courses during the EMREX EMP export process. This is NOT an
error, and it should NOT trigger the "manual verification" process on your
part (you might want to show a warning though).
The datetime when the report has been issued. It SHOULD contain the timezone
suffix. Example values: "2015-08-01T12:00:00+02:00", "2015-08-01T10:00:00Z".
Since EMREX ELMO may contain multiple reports, the issuing dates of each of
these reports may be different. This may happen if the server does not posses the
most recent data from all the institutions and is responding with cached data.
For most server implementations though, all issueDates will be the same as the
generatedDate included in the file header.
These elements describe all grading schemes which were used in other sections
of the report. Elements in this set can be referenced by their identifiers.
Note, that this list may contain local grading schemes, which are not
standardized in any way. They have been introduced to the ELMO schema to give
server implemeneters a way of providing their clients with some details about
the grading schemes they use. However, since there exists no such thing as a
"global directory" of grading schemes, these schemes cannot be identified by
any universal unique ID, and each needs to be separately described.
These grading schemes are (currently) identified only by their local
identifiers, but this does not necessarilly mean that the grading scheme itself
is "local only". In particular, popular grading schemes (like ECTS) can also be
listed here, but they cannot be easily identified.
A set of descriptions (in multiple languages). It is RECOMMENDED to include a
description, at least in English.
Local identifier, provided by the institution which has generated this report.
This identifier is used to reference `gradingScheme` elements from other places
in this document, and as such, is guaranteed to be valid only within this
single document. This means that it can even be dynamically generated, just for
the purpose of sticking with the format of this document. Clients SHOULD NOT
store this identifier.
Please note that attachments can be included in multiple places. This is the
place for those attachments which are related to a *single institution*.
Read the description of the Attachment type for further information.
Please note that attachments can be included in multiple places. This is the
place for those attachments which are *either unrelated to any institution, or
are related to multiple institutions*.
Read the description of the Attachment type for further information.
Groups...
Every EMREX ELMO element MUST be signed with xmldsig-core2 enveloped signature. The
ds:SignedInfo element MUST contain a single ds:Reference with an empty URI. The
key used by the server for signing must often match some external criteria, which
are NOT documented here. (E.g. If you're implementing EMREX EMP, then the certificate
used must match the one previously published in EMREG for your EMP.) The ds:Signature
element SHOULD contain the copy of the its certficate in the ds:KeyInfo element.
A xs:token value with at optional xml:lang attribute. It is used in places
where server developers may provide the name of an entity in multiple languages.
This is very similar to TokenWithOptionalLang, but it inherits from xs:string
(instead of xs:token), and it MAY contain basic whitespace formatting, such
as line breaks and double line breaks (for spliting paragraphs). The values
still must be in plain text though (no HTML is allowed).
A note for client implementers:
Whenever you want to display the values read from a field of this type, you
SHOULD make sure that the end user will see the line breaks in the right
places. E.g. use your equivalent of the well known `nl2br` function.
"Simple" (but still dangerous) HTML string. This type is very different from
PlaintextMultilineStringWithOptionalLang, because it contains HTML, not
plain-text.
Notes for SERVER implementers
=============================
There's the word "Simple" in the name of this type. This is because servers are
RECOMMENDED to use only the basic HTML tags for formatting (paragraphs,
italics, emphasis, lists, etc.). You SHOULD avoid inserting more complex
content (such as tables, images or h1..h6 headers), because clients might not
be able to display these.
Also note, that this type is usually used in contexts where the content is also
provided in non-HTML form (such as the `descriptionHtml` and `description`
pair). Therefore, many clients will simply ignore the HTML values, and use the
plain-text counterparts instead.
Notes for CLIENT implementers
=============================
DO NOT TRUST THAT THIS MARKUP IS SAFE. If you decide to display this HTML
content, then you SHOULD sanitize it. Otherwise you will leave your system
vulnerable to various attacks, including XSS. If you're not sure how
sanitization works, then you SHOULD NOT display this content in your
application. Use the plaintext counterparts instead (if available).
Also note, that you SHOULD NOT apply `nl2br`-like funtions on this input (the
ones you do apply in the PlaintextMultilineStringWithOptionalLang format above).
It's up to the server to make sure that its HTML is valid (properly split into
paragraphs). You may however attempt to detect and fix HTML errors, if this
HTML seems broken.
This is the type of "extension" elements. Extension elements may contain any
elements, as long as they are from a different namespace. Server implementers may
use them to include additional metadata in various places of the XML document.
The content of such extensions is not documented within this schema.
Please note that it *might* be possible to extend the "official" EMREX ELMO
schema format. If you're a server implementer and you find the namespace lacking
some data which you think might be useful for the clients, then please try to
contact EMREX representative and/or the current owner of the
https://github.com/emrex-eu/elmo-schemas/ repository.
Groups is a way of organizing and sorting over groups of LOI's.
Notes for server implementers:
The attachements MUST contain a human-readable version of all the crucial data
contained within the reports. This also includes all the data which may help to
prove the identity of the student (such as birth date). You MAY include all
this data in a single file, or you MAY split it into several ones (e.g. one PDF
per report) - we're leaving this decision to individual server implementers.
The attachments SHOULD be in PDF format. All other types of attachments MAY
be ignored by the clients.
If you wonder why attachements are required, then you should remember, that
some clients MAY ignore all learningOpportunitySpecification elements
(even if they are 100% valid) and simply choose to forward the attached
transcript of records to a staff member for manual processing (this is a
valid EMREX ELMO use case and all servers need to support it).
Try to order your attachments by importance (we'll leave it for the implementer
to decide which attachments are more important).
Also, try to keep them lightweight - some clients will need to store your
EMREX ELMO files for some time. Take their storage space into account when you
think about embedding logos or fonts inside your PDFs!
Notes for client implementers:
You will probably need these attachments in case when something goes wrong, and
you want this response to be imported or verified manually.
You MAY also use the attachment to view a human-readable "preview" of the ELMO
data for the student.
This identifier has been primarily established to enable internal references
to attachment from LOI's.
Currently, the only type recognized is "internal"
Title of the attachment, e.g. "Transcript of records". May be provided in
multiple languages. This is not required, but recommended - it might be used
by the clients, for example when displaying a list of attachments.
Type of the attachment. SHOULD be included if any type from the enclosed
enumeration applies to the content of the attachment. If the none of the
predefined values apply then this element SHOULD either be skipped, or
"Other" value should be used.
More types MAY be added in the future. You SHOULD be prepared for that.
This is similar to a Transcript of Records, with one big difference.
The "EMREX Transcript" is meant to include all the records within the
transferred ELMO file (which can span over *multiple* institutions), that is, it
should be located *outside* the `report` elements.
In comparison, "Transcript of Records" is meant to be issued (and possibly
signed) by a single institution, and should be located inside the `report`
element.
This type can be used when none of the other currently defined types matches.
Using this type is more or less equivalent to not providing any type.
Client implementers should be reminde, that the the number of types will grow.
Therefore, if the server seems to be using "Other" in place of some other
better-fitting type X, then it's not necessarilly the fault of the server. It
also might be caused by the fact the type X was added recently, and the server
didn't discover it yet.
An optional detailed description of the attachment (in multiple languages).
Avoid redundancy - you SHOULD NOT include the description if its value is
already included in the title element.
The content of the attachment encoded using a data URI scheme. E.g.
"data:application/pdf;base64,iiNhz6QfDnnDybjHLBF2..."
If you have several attachments of the same type with different languages, there
is now a possibility to add more than one content.
Notes for client implementers:
For security reasons, you may consider checking the content type of the file
before displaying it in the browser (there's a possibility of XSS attacks if
EMREX ELMO producer's server was compromised). It might be safer to force the
browser to save all non-PDF attachments instead of displaying them.
If you want to allow the users to download the attachment, then you might need
to dynamically generate the name for the file - the extension can be determined
from the content type use in the data URI.
This describes a single "branch" of the "LOS tree": One "parent" node along
with all its descendants (via the hasPart elements).
Each report element contains a set of such trees (a forest). For example, a
report may contain a set of degree programmes, and each of these programme may
contain a set of courses. But it is also valid for the report to contain only
the courses (without the degree programmes), or a mixture of some programmes
alongside some seperate courses (unbound to any degree programme).
In theory the depth of such tree is unlimited, but in practice no more than
4 levels are usually reached. Each level has an OPTIONAL type, and these types
(if given) SHOULD follow a logical structure - in order of their depth, these
would be: "Degree programme", "Module", "Course" and "Class". That is, it is
valid to include a "Course" with a "Degree programme" parent, but it would be
invalid to include them the other way around.
Notes for server implementers
=============================
Depending on the scenario, EMREX ELMO file will contain only a subset of the
student's degree programmes and courses. (E.g. in case of EMREX EMP server,
students are allowed to select any subset of courses are to be exported, but
only from among the passed/completed courses. This might however be different
in other contexts.)
Notes of client implemeneters
===================================
We cannot guarantee the *all* servers will follow the "max of 4 levels deep"
structure, nor that all of them will fill in the "type" elements for all the
nodes.
If you're trying to import the data into your system, and the "possibly
infinite tree" representation seems to be incompatible with your model, then
you will need to dynamically analyze the types of all the the nodes included in
the report and decide if the structure can be automatically imported.
For server implementers: Depending on your clients, you might be required to
supply specific identifier types (because clients expect them). E.g. some EMREX
clients expect the "local" identifier to be present.
Some predefined type values include:
"local" - the local unique identifier of the node. "Unique" means that the
[node type, local identifier] tuple MUST uniquely identify this node
*within the scope of the host institution* (the one provided in the issuer
element). If you cannot provide the "type" for this node, then the provided
"local" identifier MUST be unique by itself. If you cannot guarantee such
uniqueness then you MUST NOT provide the "local" identifier at all (you can
still use other identifiers).
"ewp-los-id" - LOS identifier used in the Erasmus Without Paper project.
https://github.com/erasmus-without-paper/ewp-specs-api-courses#unique-identifiers
You can also have any number of custom types.
The name(s) of the node (the title of a degree programme, or the name of a
course, etc.).
Note for server implementers:
You MUST provide at least one name, preferrably in English. If your node does
not have a name (or cannot have a name), then you should attempt to generate
one, for example based on its ID and type. As a last resort, use an empty
string here.
The type of the node.
Note for server implementers:
You SHOULD include the type of your entity if it is compatible with any of the
types provided by the enumeration described below. Some clients won't be
able to import (or even properly display) the data if some elements are missing
their types.
You SHOULD NOT include the type if the type of your entity does not seem to
match any of the types described in the enumeration below. You might also
want to contact us so we may include such new types in the next schema version.
Make sure that the proper structure is followed. All types can be put on the
top level (the report/LearningOpportunitySpecification element), but the type
of the descendant nodes is limited by the types of their ancestors.
Note for client implementers:
You MUST be prepared to receive an unknown type here. A new version of the
schema may allow for the servers to use some newer values of types which
are yet unknown to your implementation. You SHOULD handle such cases
gracefully (treat it the same way as you would treat the node if the type
was not present at all).
A study programme. Finalizing a study programme ends with a degree (e.g.
Bachelor degree, Master degree, etc.).
"Degree programme"s should not have a parent and should contain only "Module"s
or "Course"s as their descendants. (However, we have some reason to believe
that in some rare cases, it is possible that they MAY also contain other
"Degree programme"s.)
A group or collection of courses.
"Module"s may have a "Degree programme" parent, and should contain "Course"s
only.
In EMREX we define "Course" as the *smallest* entity for the students to be
able to gain ECTS credits from.
A "Course" may have a "Degree programme" or a "Module" as a parent, and should
contain "Class"es.
A single education element a course consists of (like lecture, classes etc.).
"Class"es should have a "Course" ancestor, and - if they contain any children -
then these children should not have any type.
If there are many "types of classes" in the server side, then such types MAY be
further described in the node title (e.g. "Lecture class" or "Laboratory
class"). The EMREX ELMO format does not currently provide any enumeration
for such subtypes though.
The Erasmus subject area code of the course.
The ISCED-F code of the course or programme.
ISCED-F codes define fields of education and training at the secondary,
post-secondary and tertiary levels of education. Details:
http://www.uis.unesco.org/Education/Documents/isced-fields-of-education-training-2013.pdf
The URL of the entity's web page (with the description of the course or
degree programme).
An optional plain-text description of the programme/course/class (in multiple
languages).
An optional HTML description of the programme/course/class (in multiple
languages).
Notes for SERVER implementers
=============================
Remember to read the documentation on the SimpleHtmlStringWithOptionalLang
format!
Additionally:
It is RECOMMENDED to supply this content in the plain-text (non-HTML) format
too. If internally you keep these descriptions in HTML format, then you SHOULD
try to convert this format to proper multiline plaintext and provide this
version in the `description` element. It's okay to supply `descriptionHtml`
alongside with it, but you should avoid supplying ONLY `descriptionHtml`.
Notes for client implementers
=============================
Remember to read the documentation on the SimpleHtmlStringWithOptionalLang
format! DO NOT JUST TRUST THAT THIS MARKUP IS SAFE.
Just a wrapper for learningOpportunityInstance (we're trying to be
ELMO-compatible).
While the "learningOpportunitySpecification" element describes a "Degree
programme" (or a "Course", etc.) by itself, this element tells us more of the
relation between such programme (or course, etc.) and our "learner" (which
includes student's grades, credits, and other achievements).
A list of identifiers of this Learning Opportunity Instance.
Some predefined type values include:
"ewp-loi-id" - LOI identifier used in the EWP (Erasmus Without Paper) project.
https://github.com/erasmus-without-paper/ewp-specs-api-courses#unique-identifiers
You can also have any number of custom types.
The date on which the student started studying this learning opportunity
(may contain a time zone).
A note for server implementers: Usually this will match the beginning of one of
the academic terms.
The date on which the student finished studying (may contain a time zone). It
doesn't necessarilly need to match the end of the academic term. Prefferably,
this should be the date when the student has passed his final exam.
A note for server implementers: If the exact date cannot be determined, please
try to include an approximate date, e.g. the last day of the academic term.
Describes the academic term in which the course took place.
A note for server implementers: You SHOULD include this element for "Course"-type
learning opportunities (EMREX's "Course" entities *always* span over a single
academic term). You SHOULD NOT include the academicTerm element for "Degree
Programme"s, or any other learning opportunities which span over multiple
terms.
The displayed name of the academic term, in multiple languages. Servers SHOULD
provide at least the name in English.
SHOULD match the first day of the academic term (may contain a time zone).
SHOULD match the last day of the academic term (may contain a time zone).
The status of this LOI. It is STRONGLY RECOMMENDED for all server implementers
to include this element explicitly (even if the server does not ever include
LOIs other than "passed" in this particular context).
Because of backward-compatibility, if no explicit status is present, then
clients SHOULD assume that the status is "passed".
Clients MAY assume that this enumeration WILL NOT grow in the future. No new
status values will be added here. If schema designers ever decide that more
status values are needed, then a new element (e.g. `status2`) will be
introduced instead (while `status` will probably get deprecated).
Indicates that this LOI has been passed by the student. Once the status is
"passed", it SHOULD NOT change to any other status.
Indicates that the student permanently failed to pass this LOI. Once the
status is "failed", it SHOULD NOT change to any other status.
Indicates that the student has started this LOI, but has not completed it yet.
Eventually, this status SHOULD change to "passed" or "failed".
RECOMMENDED. Identifier of the grading scheme used in `resultLabel` and
`resultDistribution` below.
This identifier is provided by the institution which has generated this report,
and is only guaranteed to be valid within this single file. Clients SHOULD NOT
store this identifier. It is used here only to provide a reference to the
grading scheme descriptions in the `gradingScheme` children of the `report`
element.
The final grade awarded for the student. This SHOULD contain the same value as
the one printed in the official documents in the server's country.
A note for client implementers: You MUST be prepared for the resultLabel
to NOT be present. Some servers may not actually keep the grades, so they
may not be able to include them here.
Optional. Might be provided by some servers.
This element may be used by clients as an indicator of *how well* the
student was graded when compared to other students. The three values don't
need to be very exact (one decimal place should be more than enough), but
they SHOULD sum up to 100.
The percentage of students of the same course who got a lower grade than
our learner (this includes the students which have failed the course).
A decimal number between 0 and 100 (though 100 is never reached).
The percentage of students of the same course who got exactly the same grade as
our learner.
The percentage of students of the same course who got a higher grade than
our learner.
Optional. Might be provided by some servers.
At first, this element might seem similar to the shortenedGrading element, but
it serves a different purpose. It describes a histogram of results achieved by
all the students of this course instance. However, since the ranges of the
histogram are artificial labels only, and they may contain ranges (e.g.
"10-20"), the client cannot easily determine in which category the result
of the learner comes into.
If provided, then it should contain the distribution of results of all the
students (including the ones that have failed the course).
This describes a single range within the histogram.
The label of the histogram range. Should correspond to the grading scheme
which have been used. E.g. "C", or "20-30". If possible, the label should
be understandable in any language. If not, you should try to use English.
The number of students whose grades fall within that category.
Optional additional description of the histogram (in multiple languages).
This describes various credit types which student has achieved by completing
this module/course/class.
At least ECTS credits SHOULD be included.
If this tree node contains ECTS credits earned, then all of its descendants
and ancestors MUST NOT. E.g. if the student has been given credits for
completing a course, he/she should not be given the same credits "again" for
completing the degree programme which this course has been a part of.
Currently there is only one predefined scheme you can have here:
ects - if the scheme is "ects", then the value element MUST contain the number
of ECTS credits awarded for our learner for completing this learning
opportunity.
You can also include any number of other credits with custom schemes.
This one was never properly documented, and is planned to be deprecated soon.
Servers and clients who plan to use it SHOULD first refer to these threads:
https://github.com/emrex-eu/elmo-schemas/issues/26
https://github.com/emrex-eu/elmo-schemas/issues/33
The number of credits acquired.
This describes various levels of education.
Here, issuers of ELMO can describe types of education levels.
Consumers of ELMO should ignore any level types they do not recognize.
Suppliers of ELMO should not expect consumers to interpret the levels
that have types they do not support.
On a national level, issuers can add level types used within a
specific country and which have been agreed upon with national clients.
Mandatory supported types are described in the type section below.
Currently supported types are:
- EQF (European Qualification Framework)
An optional detailed description of the the type of level that is being supplied.
The level value.
Recommended, especially for courses and/or classes. An ISO 639-1 code of the
language which has been used as the primary language for teaching the learner
during the classes. E.g. "pl" if the course was instructed/conducted in Polish.
A note for server implementers: This MUST be a single language. If multiple
languages were used, attempt to select the primary one. If you cannot select a
single primary language, then you MUST NOT include this element at all.
Recommended. For courses or classes. The number of hours the student had spent
on attending the classes.
List the attachments connected to this specific LOI.
Reference to the attachment.identifier
A reference to the groups.id
A reference to the groups.group.id
Each learningOpportunityInstance of type Degree Programme can include a Diploma Supplement, see the DiplomaSupplement type for details.
Just a wrapper for learningOpportunitySpecification (we're trying to be
ELMO-compatible).
Each hasPart contains exactly one learningOpportunitySpecification, which
contains one child node of our tree. Every node may have an unlimited number
of hasPart/learningOpportunitySpecification elements.
The Diploma Supplement (DS) is a document accompanying a higher education diploma, providing a standardised description of the nature, level, context, content and status of the studies completed by its holder.
Details:
http://ec.europa.eu/education/resources/diploma-supplement_en
The version number refers to the official rules for what a DS should include. As these rules rarely change, it was agreed the version to be the year the rules this document adheres to were introduced (1997, 2007, 2018). As of creating this schema, the last change was introduced in 2018, so this is the default version, unless specified otherwise.
The date when the DS was generated. Example values: "2015-08-01", "2017-01-31".
The standard introduction which in English starts with "This Diploma Supplement model was developed by the European Commission (...)"
The DS itself can be digitally signed, e.g. if the DS issuer is not the same entity as the one issuing the ELMO document.
The language the DS has been issued in, of type xml:lang as defined in BCP 47.
The section element in the DS refers to the official section numbers (1, 2...), and can include other sections (1.1, 1.2, 2.1, 2.2...)
The section title SHOULD match the official rules for DS.
The content of the section. The element is optional in cases where a section only has subsections (like top level sections might have).
The format (media type), as defined by IANA. Some predefined type values include:
"text/plain" - plain text
"text/html" - HTML formatted text
Details:
https://www.iana.org/assignments/media-types/media-types.xhtml
Note: If HTML, XML or similar formatting are used, the content MUST be enclosed in <![CDATA[ (...) ]]>
Any additional information, including possible references to other sections.
Please note that attachments can be included in multiple places. This is the
place for those attachments which are related to this particular section.
Read the description of the Attachment type for further information.