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.

[karenetheridge]

Okay I've gotten deeper into multipart/form-data serialization and what I've come up with is:

• first of all, always parse the form parts into an array, using the model:

[
  { "name": "alpha", "value": "blip" },
  { "name": "beta", "value": "blop" },
]

Then, we take a look at the corresponding schema (or itemSchema) and determine whether the desired type is an object or an array. If it's an array, we leave it as-is, and we can go ahead with parsing the individual parts further and use any prefixEncoding or itemEncoding keywords as we go.

This somewhat contradicts the spec which says "The prefixEncoding field can be used with any multipart content to require a fixed part order. This includes multipart/form-data, for which the Encoding Object’s headers field MUST be used to provide the Content-Disposition and part name, as no property names exist to provide the names automatically." -- which seems to suggest that the deserialized format (presented to the serializer, as most of the spec is written from the perspective of serialization rather than deserialization) is simply an array of the parts themselves. I find this a bit odd because I would think that the consumer of the deserialized information would actually want to know the part names -- form data is not that useful without the names attached to them. If we just wanted an array of parts, we'd use something like multipart/mixed instead. And also - if we supply the deserialized data to the serializer with names intact, we don't need header keywords at all to tell us what the Content-Disposition needs to be -- it's constructed from the name. Do we need the headers keyword for anything else? (I haven't looked closely at the other multipart/ media types yet.)

IMHO, I'd fix all this in Moonwalk.

---

If the desired type is an object, we reshape the data to look just like what it does for application/x-www-form-urlencoded:

{
  "alpha": "blip",
  "beta": "blop"
}

or for names with multiple values:

{
  "alpha": "blip", "blup",
  "beta": "blop"
}

..and in this case the prefixEncoding and itemEncoding keywords are ignored, as we don't have an array, and parsing proceeds exactly as it would for application/x-www-form-urlencoded.

I've worked out a schema for form objects that will accomodate both a single value and multiple values in a clean way; I'll submit it soonish as an example that can be plopped into the "Encoding by Name" section or perhaps an appendix.