Merge pull request #29 from kschneider84/api-docs

Define report schema in more detail

Author: phev8

content/docs/participant-management/reports.mdx

@@ -38,6 +38,10 @@ A "report" is a data entry for a participant with the following fields in the da
       type: 'number',
       required: true,
     },
+    modifiedAt: {
+      description: 'Date-time format of the last modification of the report',
+      type: 'string'
+    },
     data: {
       description: 'Optional list of key/value data points attached to the report',
       type: 'Array<ReportDataItem> (optional)',

public/openapi/management-api.json

@@ -803,7 +803,7 @@
         "properties": {
           "id": {
             "type": "string",
-            "description": "ObjectID"
+            "description": "MongoDB ObjectID as hex string"
           },
           "key": {
             "type": "string"
@@ -815,7 +815,8 @@
             "type": "string"
           },
           "timestamp": {
-            "type": "integer"
+            "type": "integer",
+            "description": "Unix timestamp"
           },
           "modifiedAt": {
             "type": "string",
@@ -824,26 +825,27 @@
           "data": {
             "type": "array",
             "items": {
-              "type": "object",
-              "additionalProperties": true
+              "$ref": "#/components/schemas/ReportData"
             }
           }
         },
         "additionalProperties": false,
-        "description": "Report object"
+        "description": "Report object",
+        "required": [
+          "key",
+          "participantID",
+           "timestamp"
+        ]
       },
       "ReportData": {
         "type": "object",
         "properties": {
-          "key": {
-            "type": "string"
-          },
-          "value": {
-            "type": "string"
-          },
-          "dtype": {
-            "type": "string"
-          }
+          "key": { "type": "string" },
+          "value": { "type": "string" },
+          "dtype": { 
+            "type": "string", 
+            "enum": ["date", "float", "int", "string", "rawMessage", "keyList"]
+          }  
         },
         "additionalProperties": false
       },

public/openapi/participant-api.json

@@ -3619,7 +3619,21 @@
             "PaginationInfos": {
                 "type": "object",
                 "description": "Pagination information",
-                "additionalProperties": true
+                "properties": {
+                "totalCount": {
+                    "type": "integer"
+                },
+                "currentPage": {
+                    "type": "integer"
+                },
+                "totalPages": {
+                    "type": "integer"
+                },
+                "pageSize": {
+                    "type": "integer"
+                }
+                },
+                "additionalProperties": false
             },
             "SubmissionHistory": {
                 "type": "object",
@@ -3628,8 +3642,51 @@
             },
             "Report": {
                 "type": "object",
-                "description": "report object",
-                "additionalProperties": true
+                "description": "Report object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "MongoDB ObjectID as hex string"
+                    },
+                    "key": {
+                        "type": "string"
+                    },
+                    "participantID": {
+                        "type": "string"
+                    },
+                    "responseID": {
+                        "type": "string"
+                    },
+                    "timestamp": {
+                        "type": "integer",
+                        "description": "Unix timestamp"
+                    },
+                    "modifiedAt": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "data": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "key": { "type": "string" },
+                                "value": { "type": "string" },
+                                "dtype": { 
+                                    "type": "string", 
+                                    "enum": ["date", "float", "int", "string", "rawMessage", "keyList"]
+                                }
+                            },
+                            "additionalProperties": false
+                        }
+                    }
+                },
+                "required": [
+                    "key",
+                    "participantID",
+                    "timestamp"
+                ],
+                "additionalProperties": false
             },
             "Participant": {
                 "type": "object",