Data Formats

Data format design is a critical part of API design. A well-defined data format improves interoperability, backward compatibility, and long-term API evolution.

This section defines guidelines for:

• JSON data encoding
• Binary data handling
• Media type usage
• Standard property formats
• Date and time representation
• Number precision definition
• Country, language, and currency codes

8.1 Use JSON for Structured Data

JSON SHOULD be used as the default format for transferring structured data between API clients and servers.

JSON provides:

• Broad language support
• Simple parsing
• Good compatibility with OpenAPI specifications
• Easy interoperability between different platforms

Example:

GET /users/123

Accept: application/json

Response:

```json
{
  "id": "123",
  "name": "Alice",
  "email": "alice@example.com"
}

JSON payloads SHOULD follow standard JSON specifications:

• UTF-8 encoding MUST be used.
• Strings MUST contain valid Unicode characters.
• Object property names MUST be unique.

Example of valid JSON:

{
  "id": 1001,
  "name": "Alice"
}

Example of invalid JSON:

{
  "id": 1001,
  "id": 1002
}

Duplicate property names may lead to different parsing results between clients.

8.2 Use Non-JSON Media Types for Binary Data

JSON is not suitable for all types of data.

Alternative media types SHOULD be used when transferring:

• Images
• Documents
• Videos
• Binary files
• Data that does not need to be interpreted by clients

Example:

GET /users/123/avatar

Accept: image/png

Response:

Content-Type: image/png

Avoid embedding binary content directly into JSON:

{
  "image": "base64 encoded data"
}

Advantages of using dedicated media types:

• Smaller payload size
• Lower encoding and decoding overhead
• Better streaming support

8.3 Encode Embedded Binary Data Using base64url

Binary data SHOULD generally not be embedded inside JSON documents.

The preferred approach is to expose binary content using dedicated media types:

Client
  |
  |
  v

image/png
application/pdf
application/octet-stream

If binary data must be embedded in JSON, it MUST be encoded using:

base64url

Example:

{
  "fileName": "document.pdf",
  "content": "JVBERi0xLjQK..."
}

base64url differs from standard Base64:

base64url avoids characters that may cause problems in URLs.

8.4 Prefer Standard Media Types

APIs SHOULD use standardized media types whenever possible.

Recommended:

application/json

Avoid proprietary media types:

application/x-company-json
application/custom-data

Standard media types provide:

• Better tooling support
• Easier client implementation
• Improved interoperability

For API errors, the standardized format SHOULD be used:

application/problem+json

Example:

{
  "type": "https://example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "The requested resource does not exist"
}

8.5 Use Standard Property Formats

API properties SHOULD use standardized formats defined by OpenAPI and JSON Schema.

Common formats include:

Example:

properties:

  createdAt:
    type: string
    format: date-time

  userId:
    type: string
    format: uuid

  email:
    type: string
    format: email

8.6 Use Standard Date and Time Formats

Date and time values MUST use standardized formats.

The recommended standard is:

RFC 3339

Date

Format:

YYYY-MM-DD

Example:

{
  "birthday": "1990-01-01"
}

Date-Time

Format:

YYYY-MM-DDTHH:mm:ssZ

Example:

{
  "createdAt": "2026-08-06T10:30:00Z"
}

Avoid custom formats:

{
  "createdAt": "06/08/2026 10:30"
}

Reasons:

• Date formats differ between regions.
• Time zone interpretation may become ambiguous.

8.7 Use Standard Country, Language and Currency Codes

APIs SHOULD use internationally recognized standards for country, language, and currency codes.

Recommended standards:

Example:

{
  "country": "US",
  "language": "en-US",
  "currency": "USD"
}

Avoid custom values:

{
  "country": "America",
  "currency": "Dollar"
}

8.8 Define Format for Number and Integer Types

API specifications MUST define the format for all numeric properties.

Without an explicit format, clients may incorrectly determine the precision and cause unintended data changes.

Avoid:

amount:
  type: number

Because clients cannot know whether the value represents:

• float
• double
• decimal

Integer Formats

Example:

orderCount:
  type: integer
  format: int32

Number Formats

For financial values, use decimal:

amount:
  type: number
  format: decimal
  example: 99.95

Avoid:

amount:
  type: number
  format: float

because floating-point numbers may introduce precision errors.

Example:

0.1 + 0.2 != 0.3

8.9 OpenAPI Example

components:

  schemas:

    Money:
      type: object
      properties:

        amount:
          type: number
          format: decimal
          description: Amount expressed in major currency units
          example: 99.95


    OrderList:
      type: object
      properties:

        pageSize:
          type: integer
          format: int32
          description: Number of items returned in the list
          example: 50

Summary Checklist