From c09c4fe4bbea48465d376179d869e2b135d4378d Mon Sep 17 00:00:00 2001
From: Wojciech Rygielski <rygielski@mimuw.edu.pl>
Date: Mon, 9 Jan 2017 14:01:55 +0100
Subject: [PATCH] Introduce `los-code` (separate from `los-id`)

https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/issues/9#issuecomment-270414439
---
 response.xsd | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/response.xsd b/response.xsd
index 7348513..0bfc56a 100644
--- a/response.xsd
+++ b/response.xsd
@@ -58,13 +58,30 @@
                                 <xs:annotation>
                                     <xs:documentation>
                                         Unique identifier of this LOS. Will always match one of the `los_id` values
-                                        passed in the Courses API call.
+                                        passed in the Courses API call. It SHOULD NOT be displayed to the user (use
+                                        `los-code` for that).
 
                                         Server implementers! Please read this introduction:
                                         https://github.com/erasmus-without-paper/ewp-specs-api-courses#unique-identifiers
                                     </xs:documentation>
                                 </xs:annotation>
                             </xs:element>
+                            <xs:element name="los-code" minOccurs="0" maxOccurs="1" type="xs:string">
+                                <xs:annotation>
+                                    <xs:documentation>
+                                        Since LOS IDs should be surrogate identifiers (and, as such, should not be
+                                        displayed to the user), we allow additional "human readable" unique codes (aka
+                                        "natural identifiers") to be provided here. These codes MAY be displayed to the
+                                        user along the LOS title, but they are *not used* to identify entities in EWP
+                                        network.
+
+                                        Related links:
+                                        https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/issues/9
+                                        https://en.wikipedia.org/wiki/Surrogate_key
+                                        https://en.wikipedia.org/wiki/Natural_key
+                                    </xs:documentation>
+                                </xs:annotation>
+                            </xs:element>
                             <xs:element name="title" type="ewp:StringWithOptionalLang" minOccurs="1" maxOccurs="unbounded">
                                 <xs:annotation>
                                     <xs:documentation>
@@ -220,7 +237,9 @@
                                                     <xs:element name="loi-id" minOccurs="1" maxOccurs="1" type="LoiID">
                                                         <xs:annotation>
                                                             <xs:documentation>
-                                                                Unique identifier of this LOI.
+                                                                Unique identifier of this LOI. It SHOULD NOT be displayed to the user (use
+                                                                `los-code` and start/end dates if you want the user to be able to uniquely
+                                                                identify this LOI).
 
                                                                 Server implementers! Please read this introduction:
                                                                 https://github.com/erasmus-without-paper/ewp-specs-api-courses#unique-identifiers