-
Notifications
You must be signed in to change notification settings - Fork 4
/
update-request.xsd
331 lines (297 loc) · 18.2 KB
/
update-request.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
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:ewp="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
xmlns:mobility="https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/blob/master/endpoints/get-response.xsd"
elementFormDefault="qualified"
targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/blob/master/endpoints/update-request.xsd"
xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/blob/master/endpoints/update-request.xsd"
>
<!-- WRTODO: Replace all occurrences of 'master' (in all projects) with 'stable-v1' upon release. -->
<xs:import
schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-architecture/stable-v1/common-types.xsd"
namespace="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
/>
<xs:import
schemaLocation="get-response.xsd"
namespace="https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/blob/master/endpoints/get-response.xsd"
/> <!-- WRTODO: absolute paths! -->
<xs:annotation>
<xs:documentation>
This schema is a part of the Erasmus Without Paper project. Before you start
using it, make sure you have read the general rules described here:
http://developers.erasmuswithoutpaper.eu/
</xs:documentation>
</xs:annotation>
<xs:element name="mobilities-update-request">
<xs:annotation>
<xs:documentation>
This describes the format of the REQUEST to be submitted to the `update`
endpoint of EWP Outgoing Mobilities API.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="sending-hei-id" type="ewp:AsciiPrintableIdentifier" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
ID of the sending HEI of the mobility (or mobilities) being updated.
All updated mobilities in a single request MUST come from a single sending HEI.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
One request contains exactly one update element. But there are many possible
types of this update element.
Servers publish the list of supported update in their manifest entry.
</xs:documentation>
</xs:annotation>
<xs:element ref="approve-components-studied-draft-v1"/>
<xs:element ref="update-arrival-departure-dates-v1"/>
<xs:element ref="update-components-studied-v1"/>
<xs:element ref="update-statuses-v1"/>
<!--
Note for future XSD designers: When adding new types here, remember to add them
in the manifest-entry.xsd file too.
-->
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="approve-components-studied-draft-v1">
<xs:annotation>
<xs:documentation>
This request is sent by the receiving HEI when it wants to approve the
`latest-draft-snapshot` version of components-studied. For many HEIs, this
approval has the same meaning as "signing" this section of the LA.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="mobility-id" type="ewp:AsciiPrintableIdentifier" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
ID of the mobility which this update request is about.
The sending partner of this mobility MUST match the partner provided in
`sending-hei-id`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="approving-party" minOccurs="1" maxOccurs="1" type="mobility:ApprovingParty">
<xs:annotation>
<xs:documentation>
The party which is approving. In almost all cases, this will be
`receiving-hei`, but in some use cases it MAY also be `student` (if the
student is allowed to use receiving HEI's UI to approve Learning
Agreements).
The server MUST verify this value (it MUST NOT assume that it always equals
`receiving-hei`). If remote approval by this party is unsupported by this
server, HTTP 400 response MUST be returned, with proper user-message (e.g.
"University of Warsaw requires its students to approve their Learning
Agreements via local USOSweb system. It is not allowed to approve them
remotely.").
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="current-latest-draft-snapshot" minOccurs="1" maxOccurs="1" type="mobility:SnapshotOf_ComponentsStudied">
<xs:annotation>
<xs:documentation>
The current state of the `latest-draft-snapshot`, which is also the state which
is being approved. (It is not allowed to approve any other state, but you might
be allowed to send suggestions via `update-components-studied-v1`.)
This element is required here to prevent edit conflicts. The server MUST
verify it, in similar way as it's described in `update-components-studied-v1`.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="update-arrival-departure-dates-v1">
<xs:annotation>
<xs:documentation>
This request is sent by the receiving HEI when it wants to add or update the
`actual-arrival-date` and/or `actual-departure-date` values on the mobility
object. The sending HEI *expects* the receiving HEI to provide these values at
some point.
If none of the replace-* elements are provided in the request, then the server
SHOULD respond with HTTP 400. If the dates are in an incorrect format, the
server MUST respond with HTTP 400.
If the dates have been saved (either directly, or for review), the server MUST
return HTTP 200.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="mobility-id" type="ewp:AsciiPrintableIdentifier" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
ID of the mobility which this update request is about.
The sending partner of this mobility MUST match the partner provided in
`sending-hei-id`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="replace-actual-arrival-date" minOccurs="0" maxOccurs="1" type="xs:date">
<xs:annotation>
<xs:documentation>
The new value for `actual-arrival-date`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="replace-actual-departure-date" minOccurs="0" maxOccurs="1" type="xs:date">
<xs:annotation>
<xs:documentation>
The new value for `actual-departure-date`.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="update-components-studied-v1">
<xs:annotation>
<xs:documentation>
This request is sent by the receiving HEI when it want to suggest changes in
the `components-studied` section of the mobility object.
The sending HEI, on whose servers the mobility object is stored, MAY allow for
the receiving HEI to change `components-studied` freely, but it also MAY keep
these changes "on the side", and require a human to review them (e.g. a Sending
Coordinator, or a student).
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="mobility-id" type="ewp:AsciiPrintableIdentifier" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
ID of the mobility which this update request is about.
The sending partner of this mobility MUST match the partner provided in
`sending-hei-id`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="current-latest-draft-snapshot" minOccurs="1" maxOccurs="1" type="mobility:SnapshotOf_ComponentsStudied">
<xs:annotation>
<xs:documentation>
The current state of the `latest-draft-snapshot`, which is the *base for the
suggested changes*. It is required here to prevent edit conflicts:
https://en.wikipedia.org/wiki/Edit_conflict
The client - the receiving HEI - extracts this element from the response of the
Outgoing Mobilities API's `get` endpoint served at the sending HEI.
If the contents of `current-latest-draft-snapshot` don't match the current
values as kept in the server's database, then the server MUST respond with
HTTP 409 error response.
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10
* Error response SHOULD include the `user-message` element with a brief
explanation (e.g. "Your copy of the Learning Agreement is not up-to-date. We
are unable to process your suggestions because we lack a common base for
comparison. Please refresh your copy from our servers and repeat your
request.").
* XML supplied by the client MAY use different XML namespace prefixes than the
one the server uses in its Outgoing Mobilities API. These prefixes MUST NOT
be taken into account when snapshots are being compared.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="suggested-changes" minOccurs="1" maxOccurs="1" type="mobility:ListOfChangesTo_ComponentsStudied">
<xs:annotation>
<xs:documentation>
The list of suggested changes. Changes are formatted in the same format as in
Outgoing Mobilities API.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="snapshot-with-changes-applied" minOccurs="1" maxOccurs="1" type="mobility:SnapshotOf_ComponentsStudied">
<xs:annotation>
<xs:documentation>
This is the "target" snapshot which the requester is aiming for.
It might seem redundant because it can be generated automatically from the
other two. It is required however - to prove consistency. We want both parties
to be sure that they generate changes and snapshots properly.
If the server detects that the snapshot calculated by the client is different
than a similar snapshot calculated by the server, then it MUST respond with an
either HTTP 400 error. At this point, both parties should review their snapshot
generation algorithms.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="update-statuses-v1">
<xs:annotation>
<xs:documentation>
This request is usually sent by the receiving HEI when it wants to accept or
reject a group of nominations proposed by the sending HEI. In other words, it
allows to suggest that the status of the mobility should be changed from
"nomination" to either "live" or "rejected".
Additionally, receiving HEI MAY also use this API to suggest changing the
status to other values (e.g. notify that the mobility is cancelled), but
servers are not required to support such changes (if a particular change is
not supported for some reason, then the server will describe the fact in its
HTTP 400 response message).
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="single-update" minOccurs="1" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
This update request may contain multiple "single updates". This is different
than in most of the other update types, which support only a single mobility at
a time.
Servers MUST run this update in a transaction. If something is wrong with one
of the "single updates", then none of the updates should be saved (and the
error response should describe what went wrong).
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="mobility-id" type="ewp:AsciiPrintableIdentifier" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
ID of the mobility being updated.
The sending partner of this mobility MUST match the partner provided in
`sending-hei-id`.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="new-status" type="mobility:MobilityStatus" minOccurs="1" maxOccurs="1">
<xs:annotation>
<xs:documentation>
Suggested new status for this mobility.
If you want to accept the nomination, then you should send "live" here. If you
want to reject it, then send "rejected". You MAY also allow your users to send
other status values, but - if you choose to do so - then you SHOULD make your
users aware, that in many cases such transaction will fail (because most
partners will use this update-type only for accepting and rejecting
nominations).
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="comment" type="ewp:MultilineString" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>
An optional comment. It is RECOMMENDED for comments to be provided only when
necessary (i.e. when nominations are rejected). These comments MUST be visible
only to the IRO members, not the students.
Note, that this API allows for every mobility to have a different comment.
However, it is also okay for the clients to simply "batch copy" a single
comment to all mobilities being rejected.
It is left unspecified how servers should handle these comments - e.g. they may
store them along their mobilities, or they may forward them to specific
persons, etc.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>