Update user schema to match actual API response

openapi/components/schemas/campus.yaml

@@ -18,11 +18,11 @@ properties:
     description: |
       The identifying code for the campus in the school's SIS.
   days:
-    type: string
+    type: number
     description: The number of days in a cycle for this campus' timetable.
 readOnly: true
 example:
   id: 1
   name: Secondary
   code: SEC
-  days: "5"
+  days: 5

openapi/components/schemas/user-readableFields.yaml

@@ -43,14 +43,20 @@ properties:
     type: array
     uniqueItems: true
     items:
-      $ref: ./userShort.yaml
+      $ref: ./userLinked.yaml
     nullable: true
     example:
       - id: 25
+        externalId: "25001"
+        title: ""
+        firstname: Janna
+        preferredName: null
+        givenName: Janna
+        lastname: Reed
         fullName: Janna Reed
-        yearLevel: [ ]
         role:
           id: 3
+          type: parent
           name: Parent
 
   students:
@@ -66,9 +72,33 @@ properties:
     type: array
     uniqueItems: true
     items:
-      $ref: ./userShort.yaml
+      $ref: ./userLinked.yaml
     nullable: true
-    example: [ ]
+    example:
+      - id: 4690
+        externalId: "4690"
+        title: ""
+        firstname: Sam
+        preferredName: null
+        givenName: Sam
+        lastname: Reed
+        fullName: Sam Reed
+        role:
+          id: 13
+          type: student
+          name: Secondary Student
+      - id: 4999
+        externalId: "4999"
+        title: ""
+        firstname: Jordan
+        preferredName: ""
+        givenName: Jordan
+        lastname: Reed
+        fullName: Jordan Reed
+        role:
+          id: 8
+          type: student
+          name: Primary Student
 
   impersonableUsers:
     description: |
@@ -79,24 +109,21 @@ properties:
     type: array
     uniqueItems: true
     items:
-      $ref: ./userShort.yaml
+      $ref: ./userLinked.yaml
     nullable: false
     example:
-      - id: 69
-        externalId: 69
-        title: null
-        firstName: Eden
-        preferredName: Reed
-        givenName: Eden
-        lastName: Reed
-        fullName: Eden Reed
+      - id: 5001
+        externalId: "5001"
+        title: ""
+        firstname: Jamie
+        preferredName: null
+        givenName: Jamie
+        lastname: White
+        fullName: Jamie White
         role:
           id: 5
-          name: Junior Student
           type: student
-        yearLevel:
-          id: 4
-          name: "3"
+          name: Junior Student
 
   email:
     type: string

openapi/components/schemas/userLinked.yaml

@@ -0,0 +1,57 @@
+# This represents linked user objects (eg students, guardians, impersonableUsers) as returned by the API
+# Ideally this would just use userShort, but this doesn't match the API response and too many clients will depend on the actual response structure.
+# so please don't change the API, unless adding additional fields.
+title: Linked User
+type: object
+properties:
+
+  id:
+    $ref: ./id.yaml
+
+  externalId:
+    $ref: ./externalId.yaml
+
+  title:
+    type: string
+    nullable: true
+    description: The user's title (Mr., Ms., etc.).
+    example: ""
+
+  firstname:
+    type: string
+    nullable: false
+    description: |
+      The user's first name.
+
+      Schoolbox doesn't distinguish between a person's actual first name
+      and any other names, and in any case is not the definitive source of
+      naming information; therefore in practice this will usually be the
+      user's given name.
+    example: Sam
+
+  preferredName:
+    type: string
+    nullable: true
+    description: The user's preferred name.
+
+  givenName:
+    type: string
+    nullable: false
+    description: The user's preferred name, if set. If preferred name is not set, returns the user's first name.
+    example: Sam
+
+  lastname:
+    type: string
+    nullable: false
+    description: The user's surname.
+    example: Reed
+
+  fullName:
+    type: string
+    nullable: false
+    description: The user's formatted full name.
+    example: Sam Reed
+
+  role:
+    $ref: ./role.yaml
+