Base64 encodes binary bytes as text so an API can embed files in JSON. It simplifies single-call uploads, but increases content size by 33%; compression reduces the practical increase for some files. section 14.3.2
Single-call account application
A POST /account-applications request can include applicant data and a documents array. Each document identifies an identity or residence file and carries its Base64-encoded content. Multipart/form-data is usually smaller, but Base64 remains useful when JSON-only integration is simpler or required. section 14.3.2
Describe embedded files explicitly:
- Set JSON Schema contentMediaType to the file type, such as image/png. section 14.3.5
- Set contentEncoding to base64 for the encoded string. section 14.3.5
- Prefer multipart/form-data for larger or mixed uploads when consumers and gateways support it. section 14.3.2
Listing 14.3 Embedding a file in JSON
...
components:
schemas:
Account:
properties:
...
icon:
type: string
contentMediaType: image/png #1
contentEncoding: base64 #2
...
OpenAPI 3.1 example declaring a PNG property as Base64-encoded content. section 14.3.5
