ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-765] OpenAPI: Timezone Format ​

Overview ​

The OpenAPI schema does not cover timezone data as a default format. To address this, we have introduced a new format based on IANA tzdata.

Guidance ​

  • MUST use the customized iana-timezone data format (e.g., "America/New_York", "Europe/London").
  • MUST be represented as a string type.
  • SHOULD provide examples of valid timezone values in the schema.
  • SHOULD include a description explaining the expected format and any restrictions.

Implementation ​

Schema Definition ​

yaml
components:
  schemas:
    Timezone:
      type: string
      format: iana-timezone
      description: Timezone in IANA format
      example: "America/New_York"

Usage Example ​

yaml
openapi: 3.1.0
info:
  title: Timezone API
  version: 1.0.0
paths:
  /example:
    get:
      summary: Example endpoint
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  timezone:
                    $ref: '#/components/schemas/Timezone'

Reference ​