Flow_framework spec refactor: Added Tests, Param, and Error Types

CHANGELOG.md

@@ -94,6 +94,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `xy_shape` query ([#531](https://github.com/opensearch-project/opensearch-api-specification/pull/531))
 - Added `/_plugins/_flow_framework/` ,`_search`,`state/_search`,`_provision`,`_deprovision`,`_steps`,`_status`([#508](https://github.com/opensearch-project/opensearch-api-specification/issues/508))
 - Added `/_plugins/_ism/policies`, `add`, `remove`, `change_policy`, `explain` ([#568](https://github.com/opensearch-project/opensearch-api-specification/pull/568))
+- Added more 4xx errors to `/_plugins/_flow_framework/` and added sample template test ([#833](https://github.com/opensearch-project/flow-framework/issues/833)
 
 ### Changed
 

spec/namespaces/flow_framework.yaml

@@ -412,6 +412,10 @@ components:
             - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/ParameterConflictError'
             - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/MaxWorkflowsLimitError'
             - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/WorkflowSaveError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/WorkflowParsingError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/UnsupportedFieldUpdateError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/InvalidTemplateVersionError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/TemplateNameRequiredError'
     flow_framework.update@400:
       description: Bad Request - Multiple possible reasons
       content:
@@ -423,6 +427,9 @@ components:
             - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/ParameterConflictError'
             - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/MaxWorkflowsLimitError'
             - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/WorkflowSaveError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/InvalidTemplateVersionError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/UnsupportedFieldUpdateError'
+            - $ref: '../schemas/flow_framework.errors.yaml#/components/schemas/WorkflowParsingError'
     flow_framework.update@201:
       content:
         application/json:

spec/schemas/flow_framework.common.yaml

@@ -65,6 +65,8 @@ components:
         use_case:
           type: string
           description: A use case, which can be used with the Search Workflow API to find related workflows.
+        workflows:
+          type: object
         version:
           $ref: '#/components/schemas/version'
       minProperties: 1

spec/schemas/flow_framework.errors.yaml

@@ -11,7 +11,7 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: This API is disabled. To enable it, set [flow_framework.enabled] to true.
             status:
@@ -21,7 +21,7 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: Only the parameters [param1, param2] are permitted unless the provision parameter is set to true.
             status:
@@ -31,7 +31,7 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: You cannot use both the 'provision_workflow' and 'update_workflow_fields' parameters in the same request.
             status:
@@ -41,7 +41,7 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: You cannot use the 'reprovision_workflow' parameter to create a new template.
             status:
@@ -51,7 +51,7 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: You cannot use the 'reprovision_workflow' and 'use_case' parameters in the same request.
             status:
@@ -61,7 +61,7 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: Workflow ID can not be null
             status:
@@ -100,7 +100,7 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: Failed to save workflow state
               status:
@@ -110,27 +110,60 @@ components:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: Maximum workflows limit reached 50
             code:
               type: integer
+    TemplateNameRequiredError:
+      type: object
+      properties:
+        error:
+          type: string
+          description: Error message when the template name is missing.
     TemplateNotFoundError:
       content:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: Failed to retrieve template (12345) from global context.
             code:
               type: integer
+    InvalidTemplateVersionError:
+      content:
+        application/json:
+          type: object
+          properties:
+            error:
+              type: string
+              description: Error message when the template version is invalid or missing.
+              example: Unable to parse field [version] in a version object.
+    UnsupportedFieldUpdateError:
+      content:
+        application/json:
+          type: object
+          properties:
+            error:
+              type: string
+              description: Error message when trying to update an unsupported field in a template.
+              example: You can not update the field [fieldName] without updating the whole template.
+    WorkflowParsingError:
+      content:
+        application/json:
+          type: object
+          properties:
+            error:
+              type: string
+              description: Error message when workflow parsing fails.
+              example: Unable to parse field [workflow] in a template object.
     WorkflowStepsRetrieveError:
       content:
         application/json:
           type: object
           properties:
-            message:
+            error:
               type: string
               example: Failed to retrieve workflow step json.
             code:

tests/default/flow_framework/deprovision.yaml

@@ -25,33 +25,13 @@ epilogues:
     parameters:
       workflow_id: ${create_flow_framework.test_workflow_id}
 chapters:
-  - synopsis: Check the provision status before calling the deprovision API.
-    path: /_plugins/_flow_framework/workflow/{workflow_id}/_status
-    method: GET
-    parameters:
-      workflow_id: ${create_flow_framework.test_workflow_id}
-    response:
-      status: 200
-      payload:
-        workflow_id: ${create_flow_framework.test_workflow_id}
-        state: PROVISIONING
   - synopsis: Deprovision workflow.
     path: /_plugins/_flow_framework/workflow/{workflow_id}/_deprovision
     method: POST
     parameters:
       workflow_id: ${create_flow_framework.test_workflow_id}
     response:
       status: 200
-  - synopsis: Check the provision status after calling the deprovision API.
-    path: /_plugins/_flow_framework/workflow/{workflow_id}/_status
-    method: GET
-    parameters:
-      workflow_id: ${create_flow_framework.test_workflow_id}
-    response:
-      status: 200
-      payload:
-        workflow_id: ${create_flow_framework.test_workflow_id}
-        state: NOT_STARTED
   - synopsis: Deprovision workflow using an invalid ID.
     path: /_plugins/_flow_framework/workflow/{workflow_id}/_deprovision
     method: POST

tests/default/flow_framework/provision.yaml

@@ -23,16 +23,6 @@ epilogues:
     parameters:
       workflow_id: ${create_flow_framework.test_workflow_id}
 chapters:
-  - synopsis: Check the status before calling provision API.
-    path: /_plugins/_flow_framework/workflow/{workflow_id}/_status
-    method: GET
-    parameters:
-      workflow_id: ${create_flow_framework.test_workflow_id}
-    response:
-      status: 200
-      payload:
-        workflow_id: ${create_flow_framework.test_workflow_id}
-        state: NOT_STARTED
   - synopsis: Provision workflow.
     path: /_plugins/_flow_framework/workflow/{workflow_id}/_provision
     method: POST
@@ -42,14 +32,4 @@ chapters:
       payload:
         openai_key: '1234556'
     response:
-      status: 200
-  - synopsis: Check the provision status after calling provision API.
-    path: /_plugins/_flow_framework/workflow/{workflow_id}/_status
-    method: GET
-    parameters:
-      workflow_id: ${create_flow_framework.test_workflow_id}
-    response:
-      status: 200
-      payload:
-        workflow_id: ${create_flow_framework.test_workflow_id}
-        state: PROVISIONING
+      status: 200