-
Notifications
You must be signed in to change notification settings - Fork 15
/
schema.xsd
1571 lines (1409 loc) · 93.2 KB
/
schema.xsd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified" targetNamespace="https://github.com/emrex-eu/elmo-schemas/tree/v1" xmlns="https://github.com/emrex-eu/elmo-schemas/tree/v1" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:europass="http://europass.cedefop.europa.eu/Europass/V2.0" xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ewpAddress="https://github.com/erasmus-without-paper/ewp-specs-types-address/tree/stable-v1">
<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/03/xml.xsd" />
<xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="https://raw.githubusercontent.com/emrex-eu/elmo-schemas/v1/references/xmldsig-core-schema.xsd" />
<xs:import namespace="http://europass.cedefop.europa.eu/Europass/V2.0" schemaLocation="https://raw.githubusercontent.com/emrex-eu/elmo-schemas/v1/references/EUROPASS_ISOCountries_V1.1.xsd" />
<xs:import namespace="https://github.com/erasmus-without-paper/ewp-specs-types-address/tree/stable-v1" schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-types-address/stable-v1/schema.xsd" />
<xs:annotation>
<xs:documentation>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
</xs:documentation>
</xs:annotation>
<!-- The root element -->
<xs:element name="elmo">
<xs:complexType>
<xs:sequence>
<xs:element name="generatedDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>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".
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="learner">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="citizenship" type="europass:countryCode">
<xs:annotation>
<xs:documentation>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).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="identifier">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:token">
<xs:attribute name="type" type="xs:token" use="required">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="givenNames" type="xs:token">
<xs:annotation>
<xs:documentation>The given names of the student. All servers MUST provide it (if it is impossible
for some reason, please provide an empty string here).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="familyName" type="xs:token">
<xs:annotation>
<xs:documentation>The family name of the student. All servers MUST provide it (if it is impossible
for some reason, please provide an empty string here).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" name="bday" type="xs:date">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" maxOccurs="1" name="placeOfBirth" type="xs:token">
<xs:annotation>
<xs:documentation>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).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" maxOccurs="1" name="birthName" type="xs:token">
<xs:annotation>
<xs:documentation>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).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" maxOccurs="1" name="currentAddress" type="ewpAddress:FlexibleAddress">
<xs:annotation>
<xs:documentation>
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
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" maxOccurs="1" name="gender">
<xs:annotation>
<xs:documentation>ISO/IEC 5218 code of human gender.
https://en.wikipedia.org/wiki/ISO/IEC_5218
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:enumeration value="0">
<xs:annotation>
<xs:documentation>Unknown - the gender of the person has not been recorded.</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="1">
<xs:annotation>
<xs:documentation>Male</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="2">
<xs:annotation>
<xs:documentation>Female</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="9">
<xs:annotation>
<xs:documentation>Not Applicable - indeterminate, i.e. unable to be classified as either male or female</xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="1" name="report">
<xs:annotation>
<xs:documentation>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).
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:annotation>
<xs:documentation>This describes an institution (issuer) and a *subset* of courses *completed*
by the student within this institution.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="issuer">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="country" type="europass:countryCode">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="1" name="identifier">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:token">
<xs:attribute name="type" type="xs:token" use="required">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="1" name="title" type="TokenWithOptionalLang">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="url" type="xs:token">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="learningOpportunitySpecification" type="LearningOpportunitySpecification">
<xs:annotation>
<xs:documentation>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).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="issueDate" type="xs:dateTime">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="gradingScheme">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0" name="description" type="PlaintextMultilineStringWithOptionalLang">
<xs:annotation>
<xs:documentation>A set of descriptions (in multiple languages). It is RECOMMENDED to include a
description, at least in English.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute name="localId" type="xs:token" use="required">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="attachment" type="Attachment">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="attachment" type="Attachment">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element maxOccurs="1" minOccurs="0" name="groups" type="Groups">
<xs:annotation>
<xs:documentation>Groups...
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" name="extension" type="CustomExtensionsContainer" />
<xs:element minOccurs="0" maxOccurs="1" ref="ds:Signature">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<!-- Common types with simple content. -->
<xs:complexType name="TokenWithOptionalLang">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:token">
<xs:attribute ref="xml:lang" use="optional" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="PlaintextMultilineStringWithOptionalLang">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="xml:lang" use="optional" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="SimpleHtmlStringWithOptionalLang">
<xs:annotation>
<xs:documentation>"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.
</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="xml:lang" use="optional" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<!-- Common types with complex content. -->
<xs:complexType name="CustomExtensionsContainer">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:any maxOccurs="unbounded" minOccurs="0" namespace="##other" processContents="lax" />
</xs:sequence>
<xs:anyAttribute />
</xs:complexType>
<xs:complexType name="Groups">
<xs:annotation>
<xs:documentation>
Groups is a way of organizing and sorting over groups of LOI's.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0" name="groupType">
<xs:complexType>
<xs:sequence>
<xs:element name="title" type="TokenWithOptionalLang" maxOccurs="unbounded"/>
<xs:element maxOccurs="unbounded" minOccurs="0" name="group">
<xs:complexType>
<xs:sequence>
<xs:element name="title" type="TokenWithOptionalLang" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="optional"/>
<xs:attribute name="sortingKey" type="xs:string" use="optional"/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="optional"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Attachment">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="identifier" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
This identifier has been primarily established to enable internal references
to attachment from LOI's.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:token">
<xs:attribute name="type" type="xs:token" use="required">
<xs:annotation>
<xs:documentation>
Currently, the only type recognized is "internal"
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="title" type="TokenWithOptionalLang" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" name="type">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="Diploma" />
<xs:enumeration value="Diploma Supplement" />
<xs:enumeration value="Transcript of Records" />
<xs:enumeration value="EMREX transcript">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="Micro Credential" />
<xs:enumeration value="Letter of Nomination" />
<xs:enumeration value="Certificate of Training" />
<xs:enumeration value="Learning Agreement" />
<xs:enumeration value="Other">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="description" type="PlaintextMultilineStringWithOptionalLang">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="content" type="TokenWithOptionalLang">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" name="extension" type="CustomExtensionsContainer" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="LearningOpportunitySpecification">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0" name="identifier">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:token">
<xs:attribute name="type" type="xs:token" use="required">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="1" name="title" type="TokenWithOptionalLang">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" name="type">
<xs:annotation>
<xs:documentation>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).
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="Degree Programme">
<xs:annotation>
<xs:documentation>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.)
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="Module">
<xs:annotation>
<xs:documentation>A group or collection of courses.
"Module"s may have a "Degree programme" parent, and should contain "Course"s
only.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="Course">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="Class">
<xs:annotation>
<xs:documentation>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.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element minOccurs="0" name="subjectArea" type="xs:token">
<xs:annotation>
<xs:documentation>The Erasmus subject area code of the course.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" name="iscedCode" type="xs:token">
<xs:annotation>
<xs:documentation>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
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element minOccurs="0" name="url" type="xs:token">
<xs:annotation>
<xs:documentation>The URL of the entity's web page (with the description of the course or
degree programme).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="description" type="PlaintextMultilineStringWithOptionalLang">
<xs:annotation>
<xs:documentation>An optional plain-text description of the programme/course/class (in multiple
languages).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element maxOccurs="unbounded" minOccurs="0" name="descriptionHtml" type="SimpleHtmlStringWithOptionalLang">