Add description of scopes, upgrade OpenAPI spec version [SA-23072]

openapi/components/parameters/calendarQuery/end.yaml

@@ -6,6 +6,7 @@ description: |
   This is used to bound the range of calendar events returned.
 schema:
   type: integer
-  example: 1762606800
+  examples:
+    - 1762606800
 required: true
 

openapi/components/parameters/calendarQuery/folderId.yaml

@@ -6,6 +6,7 @@ description: |
 schema:
   type: integer
   minimum: 1
-  example: 42
+  examples:
+    - 42
 required: false
 

openapi/components/parameters/calendarQuery/start.yaml

@@ -6,6 +6,7 @@ description: |
   This is used to bound the range of calendar events returned.
 schema:
   type: integer
-  example: 1758981600
+  examples:
+    - 1758981600
 required: true
 

openapi/components/parameters/calendarQuery/userId.yaml

@@ -5,5 +5,6 @@ description: |
 schema:
   type: integer
   minimum: 1
-  example: 1
+  examples:
+    - 1
 required: true

openapi/components/parameters/search/filter.yaml

@@ -57,13 +57,15 @@ schema:
           format: date-time
           description: |
             A date in YYYY-MM-DD format.
-          example: '2023-01-01'
+          examples:
+            - '2023-01-01'
         to:
           type: string
           format: date-time
           description: |
             A date in YYYY-MM-DD format.
-          example: '2023-12-31'
+          examples:
+            - '2023-12-31'
 
     creator:
       type: object

openapi/components/requestBodies/differentiation.yaml

@@ -6,49 +6,48 @@ content:
       type: object
       properties:
         adjustment_category:
-          type: array
-          nullable: true
+          type: [array, 'null']
           description: Array of adjustment category ids
           items:
             type: object
             properties:
               id:
                 type: integer
-                example: 1
+                examples:
+                  - 1
         adjustment_level:
-          type: array
-          nullable: true
+          type: [array, 'null']
           description: Array of adjustment level ids
           items:
             type: object
             properties:
               id:
                 type: integer
-          example:
-            - id: 3
-            - id: 4
+          examples:
+            - - id: 3
+              - id: 4
         overview:
-          type: string
-          nullable: true
+          type: [string, 'null']
           description: Overview of the differentiation profile (if applicable)
-          example: null
+          examples:
+            - null
         interests_strengths:
-          type: string
-          nullable: true
+          type: [string, 'null']
           description: Interests and strengths (if applicable)
-          example: null
+          examples:
+            - null
         needs_challenges:
-          type: string
-          nullable: true
+          type: [string, 'null']
           description: Needs and challenges (if applicable)
-          example: null
+          examples:
+            - null
         strategies_adjustments:
-          type: string
-          nullable: true
+          type: [string, 'null']
           description: Strategies and adjustments (if applicable)
-          example: null
+          examples:
+            - null
         goals:
-          type: string
-          nullable: true
+          type: [string, 'null']
           description: Goals for the student (if applicable)
-          example: 'Goal 1: Improve reading comprehension.'
+          examples:
+            - 'Goal 1: Improve reading comprehension.'

openapi/components/requestBodies/evidence-item.yaml

@@ -6,21 +6,19 @@ content:
       properties:
         body:
           type: string
-          example:
-            <p>I can count forwards and backwards by 2s.</p>\n
+          examples:
+            - <p>I can count forwards and backwards by 2s.</p>\n
         file:
-          nullable: true
-          type: string
-          example: store:1f8f836cce05750ac98302c74d4081f99fdd443f
+          type: [string, 'null']
+          examples:
+            - store:1f8f836cce05750ac98302c74d4081f99fdd443f
           description: hash as returned by asyncUpload.php
         curriculumNodes:
-          nullable: true
-          type: array
+          type: [array, 'null']
           items:
             $ref: ../schemas/curriculumItem.yaml
         tags:
-          nullable: true
-          type: array
+          type: [array, 'null']
           items:
             type: object
             description: |
@@ -29,11 +27,13 @@ content:
               id:
                 type: integer
                 description: the DB identifier of the Learning Moment Tags
-                example: 1
+                examples:
+                  - 1
               name:
                 type: string
                 description: the name of the Learning Moment type, may not be unique
-                example: Class Work
+                examples:
+                  - Class Work
         type:
           type: string
           enum:
@@ -42,7 +42,8 @@ content:
             - upload
             - video
             - audio
-          example: upload
+          examples:
+            - upload
       required:
         - body
         - type

openapi/components/requestBodies/file-item.yaml

@@ -8,17 +8,21 @@ content:
           type: string
           description: |
             limit of 250 characters
-          example: 2022-School-Events
+          examples:
+            - 2022-School-Events
         title:
           type: string
-          example: School Events
+          examples:
+            - School Events
         description:
           type: string
           description: |
             limit of 255 characters
-          example: |
-            Current
-            Banner image for 2022 school events
+          examples:
+            - |
+              Current
+              Banner image for 2022 school events
         hidden:
           type: boolean
-          example: false
+          examples:
+            - false

openapi/components/requestBodies/newsItem.yaml

@@ -43,7 +43,8 @@ content:
             and "Time Format" settings: ideally, this would just be a "datetime" format
             but the datetime input was developed before JSON was used for request bodies.
           type: string
-          example: 22/06/2021 11:28am
+          examples:
+            - 22/06/2021 11:28am
         expiresAt:
           description: |
             The datetime at which this article should be achieved.
@@ -52,10 +53,10 @@ content:
             and "Time Format" settings: ideally, this would just be a "datetime" format
             but the datetime input was developed before JSON was used for request bodies.
           type: string
-          example: 22/06/2021 11:28am
+          examples:
+            - 22/06/2021 11:28am
         attachment:
-          type: array
-          nullable: true
+          type: [array, 'null']
           description: |
             A single featured image to attach to this news item, supplied as a
             pointer to a file in Schoolbox. This parameter may be provided no
@@ -82,8 +83,7 @@ content:
             $ref: ../schemas/filePointer.yaml
           maxItems: 1
         attachedFiles:
-          type: array
-          nullable: true
+          type: [array, 'null']
           description: |
             Files to attach to this news item, supplied as pointers to a file in
             Schoolbox. This parameter may be provided multiple times to attach

openapi/components/requestBodies/pastoral-item.yaml

@@ -10,50 +10,44 @@ content:
           type: integer
         duplicateIds:
           description: A comma separated list of IDs of students to create this pastoral record for.
-          type: string
-          nullable: true
+          type: [string, 'null']
         heading:
           description: Pastoral record title.
           type: string
           maxLength: 255
         occurredOn:
           description: The date on which this is occurred in the format configured in your Admin area.
-          type: string
+          type: [string, 'null']
           format: date
-          example: 22/06/2021
-          nullable: true
+          examples:
+            - 22/06/2021
         typeId:
           description: The ID of a pastoral type to associate with this pastoral record.
           type: integer
-          nullable: false
         subtypeId:
           description: |
             The ID of a pastoral sub-type to associate to this pastoral record.\
             The sub-type must already be associated with the type provided as typeId.\
             This can be null, if the pastoral type does not have any sub-type.\
             This cannot be null, if the pastoral type has sub-type(s).
-          type: integer
-          nullable: true
+          type: [integer, 'null']
         severityId:
           description: |
             The ID of a pastoral severity to associate with this pastoral record.\
             Required only if Allow specification of severity on pastoral records config is ON.
-          type: integer
-          nullable: true
+          type: [integer, 'null']
         body_public:
           description: |
             General content of this pastoral record in raw HTML.\
             The following tokens will be substituted with the students details on creation: [firstname], [preferredname], [surname], [fullname], [year], [house].
-          type: string
+          type: [string, 'null']
           maxLength: 65535
-          nullable: true
         body_private:
           description: |
             Confidential content of this pastoral record in raw HTML.\
             The following tokens will be substituted with the students details on creation: [firstname], [preferredname], [surname], [fullname], [year], [house].
-          type: string
+          type: [string, 'null']
           maxLength: 65535
-          nullable: true
         public_attachments[]:
           description: |
             Files to attach to general content of the pastoral record, supplied as pointers to a file in Schoolbox.\
@@ -72,8 +66,7 @@ content:
             * `$filename` is the filename that the file will be given once it is uploaded to wherever it is being uploaded
 
             See the [Upload a file](#post-/storage/asyncUpload.php) endpoint for details on how to upload a file, and receive a file pointer from that upload.
-          type: array
-          nullable: true
+          type: [array, 'null']
         private_attachments[]:
           description: |
             Files to attach to confidential content of the pastoral record, supplied as pointers to a file in Schoolbox.\
@@ -92,37 +85,32 @@ content:
             * `$filename` is the filename that the file will be given once it is uploaded to wherever it is being uploaded
 
             See the [Upload a file](#post-/storage/asyncUpload.php) endpoint for details on how to upload a file, and receive a file pointer from that upload.
-          type: array
-          nullable: true
+          type: [array, 'null']
         actions[]:
           description: |
             An array of IDs of pastoral action.\
             Available only if Enable Pastoral Actions config is ON.
-          type: array
-          nullable: true
+          type: [array, 'null']
           items:
             type: integer
         tags:
           description: |
             Comma separated IDs of existing Pastoral Record Tags.\
             If non numerical string is provided, it'll be silently discarded.\
             To provide a name to create a new tag, use tagNames instead.
-          type: string
-          nullable: true
+          type: [string, 'null']
         tagNames:
           description: |
             Comma separated names of Pastoral Record Tags.\
             If Allow Staff to Create Pastoral Care Tags config is ON, attempts to create a new tag, if not alraeady exists.\
             The max length of a tag name is 255 chars.
-          type: string
-          nullable: true
+          type: [string, 'null']
         points:
           description: Points of this pastoral record.
-          type: number
+          type: [number, 'null']
           format: float
           minimum: -100000
           maximum: 100000
-          nullable: true
         role:
           description: |
             An array of pairs of a role and its access level to this pastoral record in the format of:\
@@ -135,8 +123,7 @@ content:
               * 0 - Deny
               * 1 - General
               * 2 - General + Confidential
-          type: array
-          nullable: true
+          type: [array, 'null']
         group:
           description: |
             An array of pairs of a pastoral group and its access level to this pastoral record in the format of:\
@@ -146,8 +133,7 @@ content:
               * 0 - Deny
               * 1 - General
               * 2 - General + Confidential
-          type: array
-          nullable: true
+          type: [array, 'null']
         user:
           description: |
             An array of pairs of a user and its access level to this pastoral record in the format of:\
@@ -159,8 +145,7 @@ content:
               * 0 - Deny
               * 1 - General
               * 2 - General + Confidential
-          type: array
-          nullable: true
+          type: [array, 'null']
       required:
         - student_id
         - heading