multipart/form-data packages independently typed parts in one HTTP request, making it practical to submit form data and raw binary files together. Each part is separated by a boundary from the Content-Type header. section 14.3.2
Account application upload
A single POST /account-applications request can include a JSON data part containing the applicant name and document types, plus repeated documents parts containing identity and residence files. Repeated names represent an array. section 14.3.2
Choose the representation according to consumer and system constraints:
- Prefer multipart/form-data when binary files accompany metadata that does not fit conveniently in URLs or headers; raw files are smaller than Base64 content. section 14.3.2
- Use Base64 in JSON when a single JSON representation is more compatible, accepting roughly 33% larger encoded content before compression. section 14.3.2
- Describe multipart parts with an OpenAPI encoding object, including allowed media types for binary document parts. section 14.3.5
Listing 14.4 Defining a multipart request body
paths:
/account-applications:
post:
requestBody:
content:
multipart/form-data:
schema:
properties: #1
data: #2
properties:
name:
type: string
documents: #3
type: array
items:
properties:
type:
type: string
enum:
- identity
- residence
documents: #4
type: array
items:
type: string
format: binary #5
encoding: #6
documents:
contentType: application/pdf, #7
image/png, image/jpeg
Use the OpenAPI request-body example to see how data and repeated binary document parts are modeled together. section 14.3.5
