From f0c7eac398b1562e31dc507567fb481df51269e6 Mon Sep 17 00:00:00 2001 From: Andrei Matei Date: Fri, 19 Jun 2026 10:08:10 +0100 Subject: [PATCH] feat(ipa): Enrich IPA-122 Standard Codes with structured metadata CLOUDP-399916 --- ipa/general/0122.mdx | 168 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 162 insertions(+), 6 deletions(-) diff --git a/ipa/general/0122.mdx b/ipa/general/0122.mdx index ca62da0..db6226b 100644 --- a/ipa/general/0122.mdx +++ b/ipa/general/0122.mdx @@ -10,9 +10,165 @@ standardized ISO codes to facilitate a uniform customer experience. ## Guidance -- API producers **must** use - [ISO 3166-1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - two-letter country code format for country data fields -- API producers **must** use - [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) two - letter language code format for language data fields + + + + +A country data field **must** use the +[ISO 3166-1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) +two-letter country code format. + + + + + +```yaml +components: + schemas: + Address: + type: object + properties: + country: + type: string + description: ISO 3166-1 alpha-2 country code. + minLength: 2 + maxLength: 2 + example: US +``` + + + 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. + + + + + + +```yaml +components: + schemas: + Address: + type: object + properties: + country: + type: string + description: Country of residence. + example: United States +``` + + + 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. + + + + + + + For each schema under `components.schemas`, list its properties, including + properties nested inside objects and array items. + + + Identify the country fields using the property name (`country`, + `countryCode`, `nationality`, `region` when it denotes a nation), the + description, and any example value. + + + 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. + + + Flag any country field that allows full country names, three-letter codes, + numeric codes, or an unconstrained string. + + + + + + + + + +A language data field **must** use the +[ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) +two-letter language code format. + + + + + +```yaml +components: + schemas: + UserPreferences: + type: object + properties: + language: + type: string + description: ISO 639-1 language code. + minLength: 2 + maxLength: 2 + example: en +``` + + + 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. + + + + + + +```yaml +components: + schemas: + UserPreferences: + type: object + properties: + language: + type: string + description: Preferred language. + example: English +``` + + + 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. + + + + + + + For each schema under `components.schemas`, list its properties, including + properties nested inside objects and array items. + + + Identify the language fields using the property name (`language`, + `languageCode`, `locale`, `lang`), the description, and any example value. + + + 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. + + + 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. + + + + + + + +