How to describe multipart/form-data in TDs

[egekorkan]

In some cases, especially websites, clients send data as a form submission where every field of the form can have a different contentType . For this, there is the multipart/form-data contentType (Some info available at https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST). You can think of it as creating a profile page and uploading your name (string) and photo (image/jpeg). The question is, how do we describe this in TDs? Contrary to the #1463 , I do not have a nice example. Here is what Open API does, which is correct but still complicated. Also, for comparison with #1463: https://stackoverflow.com/questions/4007969/application-x-www-form-urlencoded-or-multipart-form-data I will try to sketch some TD ideas later on based on the feedback.

[JKRhb]

I suppose the OpenAPI example could look something like this as a TD affordance?

{
  "actions": {
    "submitForm": {
      "forms": [{
        "contentType": "multipart/form-data",
        "href": "http://example.org"
      }],
      "input": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "address": {
            "type": "object",
            "properties": {
              "street": {
                "type": "string"
              },
              "city": {
                "type": "string"
              }
          },
          "profileImage": {
            "type": "string",
            "format": "binary",
            "contentMediaType": "image/png" // This can't be an array at the moment
          },
        }
      }
    }
  }
}

I think one of the main problems here might be that you cannot indicate that the address is supposed to be serialized as JSON with a content type of application/json.

[egekorkan]

I think this works for the uniform contentType case but not for the second open API example where they use the word encoding with a simple json pointer.

Note: This was a use case from my time in TUM. My use case was a python flask server on a raspberry pi which gets an image (bitmap) and "renders" it as a pixel array. It can be seen at https://esiremotelab.esi.ei.tum.de:8081/ScrollPHAT under sendImage action, described by the description field. Of course this is annoying but this is the first method that shows up when one looks for flask image upload. If I were to build a product that needs this feature, I would probably implement a JSON string encoding (like the example above).

[JKRhb]

I think this works for the uniform contentType case but not for the second open API example where they use the word encoding with a simple json pointer.

I tried to realize this using a contentMediaType member, but this might be undesirable as it mixes schema information with information that should probably rather go into a form.

Maybe you could also use a JSON pointer in TDs for this?

{
  "actions": {
    "submitForm": {
      "forms": [{
        "contentType": "multipart/form-data",
        "href": "http://example.org",
        "encoding": {
          "#/actions/submitForm/profileImage": [
            "image/png",
            "image/jpeg"
          ]
        }
      }],
      "input": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "address": {
            "type": "object",
            "properties": {
              "street": {
                "type": "string"
              },
              "city": {
                "type": "string"
              }
          },
          "profileImage": {
            "type": "string",
            "format": "binary"
          },
        }
      }
    }
  }
}

[sebastiankb]

interesting topic which I think we should discuss for TD 2.0