Review of country codes in the eKYC / IdA spec, suggestion for uniform preference

[Vladimir Dzhuvinov]

The spec makes use of country codes in four places. There appears to be a general preference for the 3-letter codes, however the place_of_birth.country code deviates from that - in fact it allows only for 2-letter codes (unless we have a former country / territory, allowing for their 4-letter codes). Unless there is a specific reason to have this, our suggestion is to bring the place_of_birth.countrycode in line with the rest.

‌

We also noticed that some of the places where a country code is defined refer to the ISO spec, others to the ICAO spec. We don’t know if this is intentional. If it is a note to implementers might be helpful.

‌

This is a summary of the country codes appearing in the current spec (v12):

‌

In the place_of_birth.country claim:

https://openid.bitbucket.io/eKYC-IDA/openid-connect-4-identity-assurance-1_0-master.html#section-4.1

place_of_birth.country: String representing country in [ISO3166-1] Alpha-2 (e.g., DE) or [ISO3166-3] syntax.

‌

In the nationalities claim:

https://openid.bitbucket.io/eKYC-IDA/openid-connect-4-identity-assurance-1_0-master.html#section-4.1

nationalities array End-User's nationalities using ICAO 3-letter codes [ICAO-Doc9303], e.g., "USA" or "JPN". 2-letter ICAO codes MAY be used in some circumstances for compatibility reasons.

‌

In the address claim:

https://openid.bitbucket.io/eKYC-IDA/openid-connect-4-identity-assurance-1_0-master.html#name-extended-address-claim

country_code: OPTIONAL. country part of an address represented using an ISO 3-letter code [ISO3166-3], e.g., "USA" or "JPN". 2-letter ISO codes [ISO3166-1] MAY be used for compatibility reasons. country_code MAY be used as alternative to the existing country field.

‌

‌

As country_code parameter in the document and electronic record evidences, and also via the extended address.country_code parameter in the vouch, utility bill evidences (see above):

https://openid.bitbucket.io/eKYC-IDA/openid-connect-4-identity-assurance-1_0-master.html#section-5.1.1.1

https://openid.bitbucket.io/eKYC-IDA/openid-connect-4-identity-assurance-1_0-master.html#section-5.1.1.2

country_code: OPTIONAL. String denoting the country or supranational organization that issued the document as ISO 3166/ICAO 3-letter codes [ICAO-Doc9303], e.g., "USA" or "JPN". 2-letter ICAO codes MAY be used in some circumstances for compatibility reasons.

‌

[Mark Haine]

I’m sure there has been some discussion around this topic before. I think this inconsistency comes from the sources of the data in question with the idea that we should not transform the claims if at all possible. However, some of the list may have stronger derivation than others and soem of our assumptions may not be that strong.

place_of_birth.country - I can’t remember where that one comes from but birth certificate would seem a good start - unfortunately there are not consistent country codes on English birth certificates and the UK Gov guide even states “Date and place of birth - The later the date of birth, the more likely a full address will appear“. I suppose it is an address and as such it’s quite positive this is aligned with the standard used in address.

nationalities - pretty sure this uses ICAO because we anticipate it coming from passport

address - see issue #1239 - not that strong a reason and looking at postal addressing a number of places use the full country name

evidences - pretty sure this is using ICAO and aligned to nationalities due to that assumption it is coming from a passport which seems a reasonable decision

‌

I think there are reasons for inconsistency through the spec but I’m not 100% sure we have got it right. It might be worth debating whether the format should be controlled by the source evidence format rather than standardised.

‌

Final thought is that we should take care to avoid a breaking change for existing deployments if at all possible.

[Kosuke Koiwai]

Refer to: https://bitbucket.org/openid/ekyc-ida/issues/1099/use-icao-codes-for-nationality-and-issuer

[Kosuke Koiwai]

also https://bitbucket.org/openid/ekyc-ida/issues/1159/analyse-difference-deviation-from-icao-933

‌

[Vladimir Dzhuvinov]

@Kosuke Koiwai Thanks for those pointers, they helped us a lot!

In the OIDC SDK we included an API to enable developers to check an ISO country code and map between 2 and 3 letter codes. Do you think IdA developers will also need to know whether a particular code is a base ISO country code, or a code that is defined exclusively by ICAO (their special non-country codes)? I.e. to be able to differentiate between the origins of the code definition?

[Nat Sakimura]

Just making a list of relevant tickets for your convenience.

#1099, #1119, #1159, #1207, #1208, #1271, #1273, #1274

[Mark Haine]

I don’t know the answer to your last question @Vladimir Dzhuvinov

I would like to close this issue as I don’t think there are any changes to the draft spec arising.

[Adrian Field]

Looking into country_code, it is actually context-specific as to the best underlying spec to use, for example an address in Bermuda will use ISO (BM/BMU), whereas an issuer of a Bermudan passport may use ICAO (GBD) as it’s a British Overseas Territory

address

country_code: OPTIONAL. country part of an address represented using an ISO 3-letter code [ISO3166-3], e.g., "USA" or "JPN". 2-letter ISO codes [ISO3166-1] MAY be used for compatibility reasons. country_code MAY be used as alternative to the existing country field.

Comment: using ISO (as we do) seems best as it’s an address

evidence.document

country_code: OPTIONAL. String denoting the country or supranational organization that issued the document as ISO 3166/ICAO 3-letter codes [ICAO-Doc9303], e.g., "USA" or "JPN". 2-letter ICAO codes MAY be used in some circumstances for compatibility reasons.

Comment: using ICAO (as we do) seems best as it’s an issuer, so need to allow for non-country issuers such as UN. Description could be ‘issued the evidence’ to make it non evidence-specific.

evidence.electronic_record

country_code: OPTIONAL. String denoting the country or supranational organization that issued the document as ISO 3166/ICAO 3-letter codes [ICAO-Doc9303], e.g., "USA" or "JPN". 2-letter ICAO codes MAY be used in some circumstances for compatibility reasons.

Comment: using ICAO (as we do) seems best as it’s an issuer/source. Description could be ‘issued the evidence’ to make it non evidence-specific.

(side comment - should we use ‘issuer’ rather than ‘source’ for electronic_record? this would cater for digital IDs issued by Governments/NGOs, and also align to W3C VC terminology where ‘issuers’ is used. Also, do we need to consider whether a source is a primary source (issuer) vs a secondary source of data?)

evidence.vouch - voucher

Comment: country_code not used currently (PR #108 adds it, not merged yet) - but should use ISO as it’s the address of the voucher that is the context

place_of_birth.country

country: String representing country in [ISO3166-1] Alpha-2 (e.g., DE) or [ISO3166-3] syntax.

Comment: address context, so should be ISO, but should this be named ‘country_code’ and use the same description as address.country_code (i.e. ISO 3-letter)? ICAO spec mentions ‘place of birth’ in the spec (page 21, section 5 title), but are any ICAO codes used in a place of birth context? Maybe Kosovo documents (“The KS and RKS codes are operationally in use, although not reflected in [ISO 3166-1].”)?

[Vladimir Dzhuvinov]

Mark, my original questions that let me to open this ticket had been answered, so based on that the ticket can be closed. I was hoping that by having a single representation everywhere (3 letter codes) things will be simplified for implementers and software. That for example logic that needs to perform certain country related checks will only need to have the country configured in a single representation. So, to work around that we created a table to map between 3 and 2 letter codes (sans the ICAO only set that doesn’t have 2 letter code representations).

I also thank Adrian for his comment. I now see the general rule as being - when dealing with issuer countries - use / expect ICAO codes, when dealing with addresses - ISO codes.

[Adrian Field]

It’s probably worth keeping it open to discuss next week, as there are a few oddities, such as what if my address or place_of_birth country_code is Kosovo? (on ICAO list but not ISO)

[Adrian Field]

Summary of questions from above:

1. For country_code (address or place_of_birth context), options are:

• allow ISO only (problem - Kosovo addresses not allowed)
• allow full ICAO (problem - supranational codes don’t make sense in an address context)
• allow ISO+ non-supranational ICAO, to allow for Kosovo & other partially recognised countries to use the spec

2) For country-code (evidence context), keep ICAO

3) Why does place_of_birth.country use ISO alpha-2 and not 3-letter like other ISO country_code attributes?

4) Should place_of_birth.country be renamed country_code?

5) Should we use ‘issuer’ rather than ‘source’ for electronic_record? this would cater for digital IDs issued by Governments/NGOs, and also align to W3C VC terminology where ‘issuers’ is used

[Mark Haine]

some of these points are reasonable but to avoid breaking change we can tolerate these relatively minor issues