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.