Skip to content

ISO 3166-1: What's the policy for `common_name`?

In the iso_3166-1.json data, there are up to three fields for the name of a country: name, official_name and common_name.

According to the schema, the latter two are optional, but it doesn't say much about how and why each field is filled.

My (preliminary) understanding of these fields is:

  • name: always present; seems to roughly correspond to Short name lower case in ISO's Online Browsing Platform (OBP);

    chapter 3.15 of the full ISO 3166-1:2020 standard describes this field as:

    short name of country

    short form of the country name, distinctive word first, based on official short form in UNTERM

    Note 1 to entry: In language of the ISO 3166 standard.
    Note 2 to entry: This item might be inverted, listed with its articles if any, allowing an alphabetical order on the distinctive word. See Annex F, principles F.1.

  • official_name: mostly present; seems to correspond to Full name in ISO's OBP;

    chapter 3.16 of the full ISO 3166-1:2020 standard describes this field as:

    full name of country

    full name, as recorded in UNTERM

    Note 1 to entry: If the full name of country is identical to the short name of country (3.15), then the full name shall be omitted.
    Note 2 to entry: In language of the ISO 3166 standard.
    Note 3 to entry: The full name of country is also called "formal name" in some UNTERM files.

  • common_name: rarely present; unclear when it's filled; doesn't seem to directly correspond to any of the fields present in ISO's OBP;

    sometimes OBP contains a remark about such a "common name", e.g. for KR where it says "Often referred to as South Korea."

    but apparently there are other sources for common_name; e.g. BO has common_name: Bolivia set although the OBP entry doesn't contain any remark; in reverse, IR's OBP entry has the remark "Also referred to as Iran." but the data here does not (update: it meanwhile does thanks to d0552753);

So, I'd like to ask:

  1. Does this project even have a precise policy on how the above fields are to be filled, especially common_name?

  2. If there is no precise formal policy on common_name, would you welcome a PR adding common_name where it's currently still missing? Besides OBP, I would gather the information from Wikipedia, I guess...

This issue is somewhat related to #33.

Edited by Salim