[ADP-771] OpenAPI: Language Code Format

Overview

Because OpenAPI specification does not define a standard format for language code fields, we establish our own format guidelines based on ISO-639-1 for two-letter language codes and BCP 47 for extended language tags.

Guidance

• MUST use ISO 639-1 two-letter language codes as the base format (e.g., "en", "zh", "ja")
• SHOULD use BCP 47 format for more complex language tags when needed (e.g., "zh-CN", "en-US")
• MUST represent language codes as string type

Implementation

Schema Definition

components:
  schemas:
    LanguageCode:
      type: string
      format: iso-639-1
      description: Language code in ISO 639-1 format
      example: "en"
    ExtendedLanguageCode:
      type: string
      format: bcp-47
      description: Extended language tag in BCP 47 format
      example: "zh-CN"

Reference

• ISO 639-1 Language Codes
• BCP 47 - Tags for Identifying Languages
• IETF Language Tags
• Zalando API Guidance
• OTTO Custom Format

  INFO

  In OTTO's API design guidelines, they utilize a single identifier otto:language-code that accommodates both ISO-639-1 and BCP 47 formats.