IPA-122: Standard Codes

References to countries and languages across the API platform need to adhere to standardized ISO codes to facilitate a uniform customer experience.

Guidance

1. A country data field must use the ISO 3166-1-alpha-2 two-letter country code format.

   components:
     schemas:
       Address:
         type: object
         properties:
           country:
             type: string
             description: ISO 3166-1 alpha-2 country code.
             minLength: 2
             maxLength: 2
             example: US

   Why:

   The country field constrains its value to a two-letter ISO 3166-1 alpha-2 code, so every producer and consumer interprets the same field the same way.

   components:
     schemas:
       Address:
         type: object
         properties:
           country:
             type: string
             description: Country of residence.
             example: United States

   Why:

   The country field carries a free-form name. The same country can be written as "United States", "USA", or "U.S.", so values cannot be compared or validated across consumers.

   1. For each schema under components.schemas, list its properties, including properties nested inside objects and array items.

   2. Identify the country fields using the property name (country, countryCode, nationality, region when it denotes a nation), the description, and any example value.

   3. For each country field, confirm the value is constrained to an ISO 3166-1 alpha-2 code: a two-character string (minLength and maxLength of 2, an enum of alpha-2 codes, or a pattern such as ^[A-Z]{2}$), with a description or example that names the ISO 3166-1 alpha-2 format.

   4. Flag any country field that allows full country names, three-letter codes, numeric codes, or an unconstrained string.

2. A language data field must use the ISO 639-1 two-letter language code format.

   components:
     schemas:
       UserPreferences:
         type: object
         properties:
           language:
             type: string
             description: ISO 639-1 language code.
             minLength: 2
             maxLength: 2
             example: en

   Why:

   The language field constrains its value to a two-letter ISO 639-1 code, giving every consumer one canonical representation of a language to validate against.

   components:
     schemas:
       UserPreferences:
         type: object
         properties:
           language:
             type: string
             description: Preferred language.
             example: English

   Why:

   The language field accepts a free-form name. "English", "english", and "Eng" all denote the same language but cannot be matched, so consumers cannot rely on the value.

   1. For each schema under components.schemas, list its properties, including properties nested inside objects and array items.

   2. Identify the language fields using the property name (language, languageCode, locale, lang), the description, and any example value.

   3. For each language field, confirm the value is constrained to an ISO 639-1 code: a two-character string (minLength and maxLength of 2, an enum of alpha-2 codes, or a pattern such as ^[a-z]{2}$), with a description or example that names the ISO 639-1 format.

   4. Flag any language field that allows full language names, three-letter codes, or an unconstrained string. A locale that combines a language and a region (such as en-US) is acceptable only when its language part is an ISO 639-1 code.