multipart/form-data ambiguity

[karenetheridge]

https://spec.openapis.org/oas/latest#additional-encoding-approaches says that if we want to serialize an object as multipart/form-data but use a fixed part order (e.g. we sort alphabetically by "name"), the way to specify that in the OAD is with:

content:
  multipart/form-data:
    prefixEncoding:
      - 
        contentType: ..something.. (or possibly a style/encoding here)
        headers:
          "Content-Disposition":
            schema:
              const: 'form-data; name="alpha"'
      - 
        contentType: ..something.. (or possibly a style/encoding here)
        headers:
          "Content-Disposition":
            schema:
              const: 'form-data; name="beta"'

Now, when I deserialize this message content, and I get data that looks like:
{ alpha => "something-encoded", beta => "something-else-encoded" },

..now I need to find the encoding object (prefixEncoding entry) that corresponds with each property value so it can be appropriately further decoded. The spec suggests that I do this by looking at the headers keyword under each prefixEncoding encoding object and parsing its schema -- this seems far too fragile to be useful as it cannot be expected to be implemented consistently across implementations.

I would suggest one of these two alternatives:

• when prefixEncoding (as opposed to encoding) is present in the media-type object (or itemSchema is present instead of schema), that the form data be decoded directly to an array instead of an object, and then prefixEncoding objects can be applied to each array item as normal for array content (after all, why would it be important to keep parts in a specific order in the message body if we're just going to deserialize back to an object anyway, where the ordering is lost? so surely the user wants the data in array form anyway);

• introduce a "name" property in the encoding object, which is to be used when prefixEncoding or itemEncoding objects are used (and ignored in encoding, as it is redundant with the property name for this encoding object). This provides a direct and unambiguous mechanism to find which prefixEncoding entry corresponds to each value in the deserialized object.

As an aside, this would also be a useful application of the parameters-in-headers idea (#2342), as then "name" could be indicated as a parameter under the header:

        headers:
          "Content-Disposition":
            parameters:
              name: beta
              filename: foo.jpg
            schema:
              const: 'form-data'  # this is a fixed value for this media-type and can be omitted

[handrews]

@karenetheridge

when prefixEncoding (as opposed to encoding) is present in the media-type object (or itemSchema is present instead of schema), that the form data be decoded directly to an array instead of an object

Since prefixEncoding can only be used with prefixItems in the schema, which only applies to type: array, this is already what has to happen.

introduce a "name" property in the encoding object

I don't think this is necessary because the problem you're trying to solve is one of a header advertising a value instead of needing a schema constraint, and that's one of the core problems we're trying to solve with SAFs (#5310). So I think whatever solution we come up with there is what should be used here.

However, I don't really think this needs much of a solution anyway. There's nothing meaningful you can do with Content-Disposition other than having a const schema. Plus, the schema search rules for non-JSON data apply here, so we already define exactly how much searching is needed.

[handrews]

However, I don't really think this needs much of a solution anyway.

@karenetheridge BTW I don't mean that you're wrong that it's awkward, it's just that I think we have a rule for the awkwardness and this is a pretty obscure corner.

I do think your parameters-in-headers point is worth further exploration, though, particularly if we think through what, if any, interactions that has with SAFs (I don't have an answer in mind here- I have not throught it through myself!) But I think this is a better option than adding a field to the Encoding Object.