docs: document uploads and editor response data

Author: MHajoha

docs/qppe-lms.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.1
 info:
   title: Question Provider and Package Execution (QPPE) LMS Callback API
   version: 0.1.0
@@ -267,8 +267,7 @@ components:
       description: A unique file identifier that is determined by the LMS. It might be a file hash or some other
         identifier that changes when the content is modified.
       schema:
-        type: string
-        pattern: '^[a-zA-Z0-9\-_=]{1,64}$'
+        $ref: '#/components/schemas/FileRef'
 
     FileName:
       name: file_name
@@ -292,6 +291,12 @@ components:
       description: A question attempt reference that is determined by the LMS. It uniquely identifies an attempt
         of a question.
 
+    FileRef:
+      type: string
+      pattern: '^[a-zA-Z0-9\-_=]{1,64}$'
+      description: A unique file identifier that is determined by the LMS. It might be a file hash or some other
+        identifier that changes when the content is modified.
+
     AttemptAsyncScoringStatusFinished:
       type: object
       allOf:

docs/qppe-server.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.1
 info:
   title: Question Provider and Package Execution (QPPE) Server API
   version: 0.1.0
@@ -974,8 +974,62 @@ components:
               nullable: true
               default: null
               description: Data from the question's input fields.
+            uploads:
+              type: object
+              nullable: true
+              default: null
+              description: The files uploaded to any file upload elements, by their names.
+              additionalProperties:
+                type: array
+                items:
+                  $ref: '#/components/schemas/UserUploadedFile'
+            editors:
+              type: object
+              nullable: true
+              default: null
+              description: The text entered and files uploaded into rich text editor elements, by their names.
+              additionalProperties:
+                $ref: '#/components/schemas/RichTextEditorData'
           required: [ attempt_ref, attempt_state, response_ref ]
 
+    UserUploadedFile:
+      description: A file that is stored by the LMS. Contains metadata and a reference to retrieve the file.
+      type: object
+      properties:
+        path:
+          type: string
+          pattern: "^/(.+/)?$"
+          description: The folder path of this file. Must begin and end in `/`. Top-level files have a path of `/`.
+        filename:
+          type: string
+        file_ref:
+          $ref: "qppe-lms.yaml#/components/schemas/FileRef"
+        uploaded_at:
+          type: string
+          format: date-time
+        mime_type:
+          type: string
+          format: mime-type
+        size:
+          type: integer
+      required: [ path, filename, file_ref, uploaded_at, mime_type, size ]
+
+    RichTextEditorData:
+      description: The structure submitted by rich text editors.
+      type: object
+      properties:
+        text:
+          type: string
+        files:
+          type: array
+          items:
+            $ref: "#/components/schemas/UserUploadedFile"
+          default: []
+      patternProperties:
+        "^_":
+          description: The LMS may send and expect to receive again any additional fields beginning with `_`.
+      required: [ text ]
+
     AttemptScoreArguments:
       allOf:
         - $ref: "#/components/schemas/AttemptViewArguments"
@@ -984,6 +1038,20 @@ components:
             response:
               type: object
               additionalProperties: true
+            uploads:
+              type: object
+              default: {}
+              description: The files uploaded to any file upload elements, by their names.
+              additionalProperties:
+                type: array
+                items:
+                  $ref: '#/components/schemas/UserUploadedFile'
+            editors:
+              type: object
+              default: {}
+              description: The text entered and files uploaded into rich text editor elements, by their names.
+              additionalProperties:
+                $ref: '#/components/schemas/RichTextEditorData'
             timeout:
               type: number
               minimum: 0
@@ -999,7 +1067,7 @@ components:
             generate_hint:
               type: boolean
               description: Try to give a hint on how to improve the response.
-          required: [ response, timeout, compute_adjusted_score, generate_hint ]
+          required: [ response, uploads, editors, timeout, compute_adjusted_score, generate_hint ]
 
     AttemptScored:
       allOf:
@@ -1066,7 +1134,7 @@ components:
                     nullable: true
                     default: null
                   scoring_code:
-                    type: string
+                    type: [string, "null"]
                     enum:
                       - AUTOMATICALLY_SCORED
                       - NEEDS_MANUAL_SCORING