List or object usage in runtime expressions embedded in strings

[DmitryAnansky]

What/Why/How?

HI All,
I’ve noticed that the expected behavior for runtime expression evaluation, particularly when dealing with lists or objects, is not clearly defined.
Technically, it is possible to produce a Step output in the following form:

    steps:
      - stepId: get-products
        operationId: listOfProducts
        outputs:
          products: $response.body#/items

Lets consider that response items is a list of objects:

[
   {
       "name": "item1",
       "id": 0
   },
   {
       ...
   },
]

It is also possible to use the Step output as runtime expressions embedded in string,
like in some specification examples:

  contentType: application/xml
  payload: |
    <order>
      <items>{$steps.get-products.outputs.products}</items>
    </order>

  contentType: application/x-www-form-urlencoded
  payload: 
    products: {$steps.get-products.outputs.products}

How should we interpret the expression in case when it is a list / list of objects / object ?
Should it be stringified value, or should we throw an error in this case?

Reference

Might be related to #424

[frankkilcommins]

The general expectation would be replacing with it's string value (or stringifying).

We could look to tighten the language here. Something like:

Expressions can be embedded into string values by surrounding the expression with {} curly braces. When a runtime expression is embedded in this manner, the following rules apply based on the value type:

• Scalar values (string, number, boolean, null) are converted to their string representation.
• Complex values (object, array) are handled based on their current representation:
  • If the value is already a string (e.g., an XML or YAML response body stored without parsing), it is embedded as-is without modification.
  • If the value is a parsed structure (e.g., a JSON object or array from a parsed response, or workflow input), it MUST be serialized as JSON per RFC 8259.

Whether a value is stored as a string or parsed structure depends on the source API's content type and how the implementation handles response bodies. JSON responses are typically parsed into structures, while XML and plain text responses are typically stored as strings. When embedding a parsed structure into a non-JSON payload format, the resulting JSON serialization may not match the target format's expected structure.

[handrews]

Scalar values (string, number, boolean, null) are converted to their string representation.

String representation according to what rules? This is not a trivial problem, as noted in OAS Appendix B: Data Type Conversion.

If the value is a parsed structure (e.g., a JSON object or array from a parsed response, or workflow input), it MUST be serialized as JSON per RFC 8259.

I don't know if this is possible, but it would be better if it were possible to indicate the serialization format, as the OAS Encoding Object allows for application/x-www-form-urlencoded.