feat: Add Request Body Object

examples/1.0.0/FAPI-PAR.workflow.yaml

@@ -110,9 +110,8 @@ workflows:
           - name: client_assertion
             in: query
             value: $inputs.client_assertion
-          - name: requestBody
-            in: body
-            value: $inputs.PARrequestBody
+        requestBody:
+          payload: $inputs.PARrequestBody
         successCriteria:
           # assertions to determine step was successful
           - condition: $statusCode == 200
@@ -148,22 +147,14 @@ workflows:
           - name: client_assertion
             in: query
             value: $inputs.client_assertion
-          - name: requestBody
-            in: body
-            target: '/grant_type'
-            value: 'authorization_code'
-          - name: requestBody
-            in: body
-            target: '/code'
-            value: $steps.AuthzCodeStep.outputs.code
-          - name: requestBody
-            in: body
-            target: '/redirect_uri'
-            value: $inputs.redirect_uri
-          - name: requestBody
-            in: body
-            target: '/code_verifier'
-            value: $inputs.code_verifier                       
+        requestBody:
+          payload: |
+            {
+              "grant_type": "authorization_code",
+              "code": "{$steps.AuthzCodeStep.outputs.code}",
+              "redirect_uri": "{$inputs.redirect_uri}",
+              "code_verifier": "{$inputs.code_verifier}"
+            }                      
         successCriteria:
           # assertions to determine step was successful
           - condition: $statusCode == 200

examples/1.0.0/oauth.workflow.yaml

@@ -52,9 +52,11 @@ workflows:
         description: >-
           This is where you do the refresh
         operationId: get-token
-        parameters:
-          grant_type: refresh_token
-          refresh_token: $steps.do-the-auth-flow.outputs.my_refresh_token
+        requestBody:
+          contentType: application/x-www-form-urlencoded
+          payload:
+            grant_type: refresh_token
+            refresh_token: $steps.do-the-auth-flow.outputs.my_refresh_token
         successCriteria:
           - condition: $statusCode == 200
           - context: $response.body
@@ -89,20 +91,12 @@ workflows:
         description: >-
           This is where you get the token
         operationId: get-token
-        parameters:
-        - name: client_id
-          in: body
-          style: form
-          value: $inputs.client_id
-        - name: client_secret
-          in: body
-          style: form
-          value: $inputs.client_secret
-        - name: grant_type
-          in: body
-          style: form
-          value: 'client_credentials'
-
+        requestBody:
+          contentType: application/x-www-form-urlencoded
+          payload:
+            client_id: $inputs.client_id
+            client_secret: $inputs.client_secret
+            grant_type: client_credentials
         successCriteria:
           - condition: $statusCode == 200
           - context: $response.body
@@ -165,28 +159,14 @@ workflows:
           description: >-
             This is where you get the token
           operationId: get-token
-          parameters:
-          - name: client_id
-            in: body
-            style: form
-            value: $inputs.client_id
-          - name: client_secret
-            in: body
-            style: form
-            value: $inputs.client_secret
-          - name: grant_type
-            in: body
-            style: form
-            value: 'authorization_code'
-          - name: redirect_uri
-            in: body
-            style: form
-            value: $inputs.redirect_uri
-          - name: code
-            in: body
-            style: form
-            value: $steps.browser-authorize.outputs.code
-
+          requestBody:
+            contentType: application/x-www-form-urlencoded
+            payload:
+              grant_type: authorization_code
+              code: $steps.browser-authorize.outputs.code
+              redirect_uri: $inputs.redirect_uri
+              client_id: $inputs.client_id
+              client_secret: $inputs.client_secret
           successCriteria:
             - condition: $statusCode == 200
             - context: $response.body

examples/1.0.0/pet-coupons.workflow.yaml

@@ -47,10 +47,8 @@ workflows:
         workflowId: place-order
         parameters:
           - name: pet_id
-            in: body
             value: $steps.find-pet.outputs.my_pet_id
           - name: coupon_code
-            in: body
             value: $steps.find-coupons.outputs.my_coupon_code
         successCriteria:
           - condition: $statusCode == 200
@@ -84,7 +82,6 @@ workflows:
         workflowId: place-order
         parameters:
           - name: pet_id
-            in: body
             value: $steps.find-pet.outputs.my_pet_id
         successCriteria:
           - condition: $statusCode == 200
@@ -113,26 +110,14 @@ workflows:
     steps:
       - stepId: place-order
         operationId: placeOrder
-        parameters:
-          - name: pet_id
-            in: body
-            target: /petId
-            value: $inputs.pet_id
-          - name: coupon_code
-            in: body
-            target: /couponCode
-            value: $inputs.coupon_code
-          - name: quantity
-            in: body
-            value: $inputs.quantity
-          - name: status
-            in: body
-            target: /status
-            value: "placed"
-          - name: complete
-            in: body
-            target: /complete
-            value: false
+        requestBody:
+          contentType: application/json
+          payload:
+            petId: $inputs.pet_id
+            quantity: $inputs.quantity
+            couponCode: $inputs.coupon_code
+            status: placed
+            complete: false
         successCriteria:
           - condition: $statusCode == 200
         outputs:

versions/1.0.0.md

@@ -328,6 +328,7 @@ Field Name | Type | Description
 <a name="stepOperationPath"></a>operationPath | `string` | A reference to a [Source](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [runtime expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`.
 <a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows Description. If multiple `workflowsSpec` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions.<name>.<workflowId>`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively.
 <a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reference Object is provided, it MUST link to parameters defined in [components/parameters](#components-object). The list MUST NOT include duplicate parameters.
+<a name="stepRequestBody"></a>requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.  In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
 <a name="stepSuccessCriteria"></a>successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful.
 <a name="stepOnSuccess"></a>onSuccess | [[Success Action Object](#success-action-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.
 <a name="stepOnFailure"></a>onFailure | [[Failure Action Object](#failure-action-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.
@@ -402,21 +403,18 @@ steps:
 
 #### Parameter Object
 
-Describes a single step parameter. A unique parameter is defined by the combination of a `name` and `in` fields. There are five possible locations specified by the `in` field:
+Describes a single step parameter. A unique parameter is defined by the combination of a `name` and `in` fields. There are four possible locations specified by the `in` field:
   - path - Used together with OpenAPI style [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
   - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
   - header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
   - cookie - Used to pass a specific cookie value to the source API.
-  - body - The request, message or form body to be sent to the referenced operation.
 
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterName"></a> name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_.
 <a name="parameterIn"></a> in | `string` | The name location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"cookie"`, or `"body"`.  When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified.
-<a name="parameterStyle"></a> style | `string` | Describes how the parameter value will be serialized depending on the location of parameter value. This fixed field is predominately used to express how a _request body_ is to be serialized. For example, when request data (`in` with value `"body"`) is to be serialized as `x-www-form-urlencoded`, the style SHOULD be `"form"`. `in` parameters with values of `"query"`, `"header"`, or `"cookie"` MUST derive their style from the referenced `sourceDescriptions` operation when applicable.
-<a name="parameterTarget"></a> target | `string` | A [JSON Pointer](https://tools.ietf.org/html/rfc6901) which MUST be resolved against the request body. Used to identify the location to inject the `value`.
-<a name="parameterValue"></a> value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or an [expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow.
+<a name="parameterValue"></a> value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or an [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow.
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -429,33 +427,12 @@ This object MAY be extended with [Specification Extensions](#specification-exten
   value: $inputs.username
 ```
 
-**Encoded Body Example**
+**Header Example**
 
 ```yaml
-- name: client_id
-  in: body
-  style: form
-  value: $inputs.clientId
-- name: grant_type
-  in: body
-  style: form
-  value: authorization_code
-- name: redirect_uri
-  in: body
-  style: form
-  value: $inputs.redirectUri
-- name: client_secret
-  in: body
-  style: form
-  value: $inputs.clientSecret
-- name: code
-  in: body
-  style: form
-  value: $steps.browser-authorize.outputs.code
-- name: scope
-  in: body
-  style: form
-  value: $inputs.scope
+- name: X-Api-Key
+  in: header
+  value: $inputs.x-api-key
 ```
 
 #### Success Action Object
@@ -694,6 +671,110 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
   type: JSONPath
 ```
 
+#### Request Body Object
+
+A single request body describing the `Content-Type` and request body content to be passed by a step to an operation.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="requestBodyContentType"></a>contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements.
+<a name="requestBodyPayload"></a>payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. This field is mutually exclusive to `pointers`.
+<a name="requestBodyPointers"></a>pointers | [[Payload Pointer Object](#payload-pointer-object)] | A list of locations and values to set within a payload. This field is mutually exclusive to `payload`.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### RequestBody Object Example
+ **JSON Templated Example**
+ ```yaml
+  contentType: application/json
+  payload: |
+    {
+      "petOrder": {
+        "petId": "{$inputs.pet_id}",
+        "couponCode": "{$inputs.coupon_code}",
+        "quantity": "{$inputs.quantity}",
+        "status": "placed",
+        "complete": false
+      }
+    }
+ ```
+
+  **JSON Object Example**
+ ```yaml
+  contentType: application/json
+  payload: 
+    petOrder:
+      petId: $inputs.pet_id
+      couponCode: $inputs.coupon_code
+      quantity: $inputs.quantity
+      status: placed
+      complete: false
+ ```
+
+  **Complete Runtime Expression**
+ ```yaml
+  contentType: application/json
+  payload: $inputs.petOrderRequest
+ ```
+
+  **XML Templated Example**
+ ```yaml
+  contentType: application/xml
+  payload: |
+    <petOrder>
+      <petId>{$inputs.pet_id}</petId>
+      <couponCode>{$inputs.coupon_code}</couponCode>
+      <quantity>{$inputs.quantity}</quantity>
+      <status>placed</status>
+      <complete>false</complete>
+    </petOrder>
+ ```
+
+**Form Data Example**
+ ```yaml
+  contentType: application/x-www-form-urlencoded
+  payload: 
+    client_id: $inputs.clientId
+    grant_type: $inputs.grantType
+    redirect_uri: $inputs.redirectUri
+    client_secret: $inputs.clientSecret
+    code: $steps.browser-authorize.outputs.code
+    scope: $inputs.scope  
+ ```
+
+**Form Data String Example**
+ ```yaml
+  contentType: application/x-www-form-urlencoded
+  payload: "client_id={$inputs.clientId}&grant_type={$inputs.grantType}&redirect_uri={$inputs.redirectUri}&client_secret={$inputs.clientSecret}&code{$steps.browser-authorize.outputs.code}&scope=$inputs.scope}"
+```
+
+#### Payload Pointer Object
+Described a target location within a payload (e.g., a request body) and a value to set within the target location. 
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="payloadPointerTarget"></a>target | `string` | **REQUIRED**. A [JSON Pointer](https://tools.ietf.org/html/rfc6901) or [XPath Expression](https://www.w3.org/TR/xpath-31/#id-expressions) which MUST be resolved against the request body. Used to identify the location to inject the `value`.
+<a name="payloadPointerValue"></a> value | Any \| {expression} | **REQUIRED**. The value set within the target location. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Payload Pointer Object Example
+
+**Runtime Expression Example**
+```yaml
+    target: /petId
+    value: $inputs.pet_id
+```
+
+**Literal Example**
+```yaml
+    target: /quantity
+    value: 10
+```
+
+
 ### <a name="runtimeExpressions"></a>Runtime Expressions
 A runtime expression allows values to be defined based on information that will be available within an HTTP message, an event message, and within objects serialized from the Workflows document such as [workflows](#workflow-object) or [steps](#step-object).