TG2-VALIDATION_COUNTRYCODE_STANDARD

[iDigBioBot]

TestField	Value
GUID	0493bcfb-652e-4d17-815b-b0cce0742fbe
Label	VALIDATION_COUNTRYCODE_STANDARD
Description	Is the value of dwc:countryCode a valid ISO 3166-1-alpha-2 country code?
TestType	Validation
Darwin Core Class	dcterms:Location
Information Elements ActedUpon	dwc:countryCode
Information Elements Consulted
Expected Response	EXTERNAL_PREREQUISITES_NOT_MET if the bdq:sourceAuthority is not available; INTERNAL_PREREQUISITES_NOT_MET if the dwc:countryCode is bdq:Empty; COMPLIANT if dwc:countryCode can be unambiguously interpreted as a valid ISO 3166-1-alpha-2 country code in the bdq:sourceAuthority; otherwise NOT_COMPLIANT
Data Quality Dimension	Conformance
Term-Actions	COUNTRYCODE_STANDARD
Parameter(s)
Source Authority	bdq:sourceAuthority default = "ISO 3166 Country Codes" {[https://www.iso.org/iso-3166-country-codes.html]} {ISO 3166-1-alpha-2 Country Code search [https://www.iso.org/obp/ui/#search]}
Specification Last Updated	2024-09-19
Examples	[dwc:countryCode="GL": Response.status=RUN_HAS_RESULT, Response.result=COMPLIANT, Response.comment="dwc:countryCode is a valid ISO (ISO 3166-1-alpha-2 country codes) value"]
	[dwc:countryCode="GRL": Response.status=RUN_HAS_RESULT, Response.result=NOT_COMPLIANT, Response.comment="dwc:countryCode is NOT a valid ISO (ISO 3166-1-alpha-2 country codes) value"]
Source	TG2
References	ISO (n.dat.) ISO 3166 Country Codes. https://www.iso.org/iso-3166-country-codes.html ISO (n.dat) 3166-1 alpha-2. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 DataHub (2018) List of all countries with their two digit codes (ISO 3166-1). https://datahub.io/core/country-list Chapman AD and Wieczorek JR (2020) Georeferencing Best Practices. Copenhagen: GBIF Secretariat. https://doi.org/10.15468/doc-gg7h-s853
Example Implementations (Mechanisms)
Link to Specification Source Code
Notes	Locations outside of a jurisdiction covered by a country code may have a value in the field dwc:countryCode, the ISO user defined codes include XZ used by the UN for installations on the high seas and suitable for a marker for the high seas. Also available in the ISO user defined codes is ZZ, used by GBIF to mark unknown countries. This test should accept both XZ and ZZ as COMPLIANT country codes. This test must return NOT_COMPLIANT if there is leading or trailing whitespace or there are leading or trailing non-printing characters.

[iDigBioBot]

Comment by Lee Belbin (@Tasilee) migrated from spreadsheet: Added post scoring for consistency

[ArthurChapman]

Question from Gainesville meeting: what about records outside of country jurisdiction (e.g. Hugh seas). If material is from high seas - country code should be empty. Description altered to: If the dwc:countryCode contains a value but that value is not a valid ISO Code. Pass description is EMPTY if has a valid ISO Code.

We need a standard formalisation of what we mean by "EMPTY" which includes Empty, NULL, /N etc. Use EMPTY in all caps

[chicoreus]

This test should not be parameterized. Different users will not wish to apply different ISO country codes. The parameterized resource that provides a service for country code lookup is one (which we could recommend, though I suggest not, rather just mention) way of implementing this test, however most implementors will almost certainly want to work with a local data structure that holds the short list of valid country codes rather than making requests to a service on each data record. This parameter is (1) straying too far into forcing a particular form of implementation on implementors, and (2) requiring a parameterized version of the test when none is needed as all use cases refer to the same ISO country code list.

[ArthurChapman]

I have no idea why this is paramaterized. Particularly when the description says "dwc:countryCode is a valid ISO (ISO 3166-1-alpha-2 country codes)" @tucotuco - you paramaterized this - what was the thinking behind that?

[tucotuco]

I concur that this test should not be parametrized.

[ArthurChapman]

Removed paramaterized, added new references (Is the one I have listed as bbq:sourceAuthority - the best one here?)

[tucotuco]

To me, the best source is https://restcountries.eu/#api-endpoints-list-of-codes, simply because they have an API. I don't think it will matter too much. This is a straightforward controlled vocabulary.

[Tasilee]

@tucotuco: Agreed.

[chicoreus]

The assertion about external prerequisites not met in the specification is probably confusing in the absence of a defined source authority service.

We should probably note that implementers may use a service to obtain country codes (best implementation is probably for code to download and cache a list, e.g. the json copy from https://datahub.io/core/country-list) rather than making a service call for each run of the test. With a cached copy of country codes, implementors could have the choice of returning EXTERNAL_PREREQUISITES_NOT_MET if unable to refresh the cached copy on start up, or just using the cached copy, with how old the cache may be at a maximum being up to them. This could go in the notes rather than the specification (expected response).

Also noting that https://restcountries.eu/#api-endpoints-list-of-codes has been unresponsive of late.

[Tasilee]

Thanks @chicoreus. Local caching is likely to apply to a number of bdq:sourceAuthority. Why don't we just use the standard phrase "EXTERNAL_PREREQUISITES_NOT_MET if the bdq:SourceAuthority is not available", define our default in the Notes and leave the implementation up to the implementer?

[tucotuco]

"not available" seems like it covers the eventualities well. I like the solution.

[ArthurChapman]

I agree @tucotuco

[Tasilee]

Edited accordingly.

[tucotuco]

I suggest the Description:

'Is the value of dwc:countryCode a valid ISO 3166-1-alpha-2 country code?'

in place of:

'Is the value of dwc:countryCode a valid ISO country code value?'

[Tasilee]

Changed Description

Does the value of dwc:country occur as the equivalent of a nation in the bdq:sourceAuthority?

to

Does the value of dwc:countryCode occur as the equivalent of a nation in the bdq:sourceAuthority?

[ArthurChapman]

That is not the same as the ER

Should be

Is the value of dwc:countryCode a valid ISO 3166-1-alpha-2 country code value?

[Tasilee]

I agree and wonder how this was reverted.

[Tasilee]

Added to Notes: "This test will fail if there are leading or trailing white space or non-printing characters."

[ArthurChapman]

See comments under #48. If we agree to a change there, then this one should also be changed to

EXTERNAL_PREREQUISITES_NOT_MET if a configured service for checking ISO 3166 country codes is not available; INTERNAL_PREREQUISITES_NOT_MET if the dwc:countryCode was EMPTY; COMPLIANT if it can be unambiguously interpreted as a ISO 3166-1-alpha-2; otherwise NOT_COMPLIANT

and remove reference to bdq:sourcrAuthority under source:Authority

[Tasilee]

I agree, and wouldn't this apply also to

#38, #133 bdq:sourceAuthority default = "Creative Commons" [https://creativecommons.org/]

#62, #48

bdq:sourceAuthority is "ISO 3166-1-alpha-2" [https://restcountries.eu/#api-endpoints-list-of-codes, https://www.iso.org/obp/ui/#search]

and possibly a few more?

[Tasilee]

References need checking as restcountries.eu is no longer there. We will need a link check through all of the issues.

[ArthurChapman]

Suggested possibly using https://rapidapi.com/ajayakv/api/rest-countries - awaiting feedback

[ArthurChapman]

Updated References

[Tasilee]

Added Source Authority value as " {bdq:sourceAuthority = ISO 3166-1-alpha-2} { Country codes [https://dwc.tdwg.org/terms/#dwc:basisOfRecord]](https://www.iso.org/obp/ui/#search]}"

for now.

[Tasilee]

Amended Source Authority to align with @chicoreus suggested syntax

{bdq:sourceAuthority = ISO 3166-1-alpha-2} { Country codes [https://www.iso.org/obp/ui/#search]}

to

bdq:sourceAuthority default = "ISO 3166-1-alpha-2 country codes" { [https://www.iso.org/obp/ui/#search]}

[Tasilee]

Corrected syntax on Source Authority

[Tasilee]

Changed Expected response from

EXTERNAL_PREREQUISITES_NOT_MET if a configured service for checking ISO 3166 country codes is not available; INTERNAL_PREREQUISITES_NOT_MET if the dwc:countryCode was EMPTY; COMPLIANT if it can be unambiguously interpreted as a ISO 3166-1-alpha-2; otherwise NOT_COMPLIANT

to

EXTERNAL_PREREQUISITES_NOT_MET if a configured service for checking ISO 3166 country codes is not available; INTERNAL_PREREQUISITES_NOT_MET if the dwc:countryCode was EMPTY; COMPLIANT if it can be unambiguously interpreted as an ISO 3166-1-alpha-2 country code; otherwise NOT_COMPLIANT

and removed reference to bdq:sourceAuthority in Source Authority

[Tasilee]

Due to recent discussions, changed

EXTERNAL_PREREQUISITES_NOT_MET if a configured service for checking ISO 3166 country codes is not available; INTERNAL_PREREQUISITES_NOT_MET if the dwc:countryCode was EMPTY; COMPLIANT if it can be unambiguously interpreted as a ISO 3166-1-alpha-2 country code; otherwise NOT_COMPLIANT

to

EXTERNAL_PREREQUISITES_NOT_MET if bdq:sourceAuthority is not available; INTERNAL_PREREQUISITES_NOT_MET if the dwc:countryCode was EMPTY; COMPLIANT if dwc:countryCode can be unambiguously interpreted as an ISO 3166-1-alpha-2 country code; otherwise NOT_COMPLIANT

and Source Authority from blank to

bdq:sourceAuthority default = "ISO 3166 Country Codes" {[https://www.iso.org/iso-3166-country-codes.html]} {ISO 3166-1-alpha-2 Country Code search [https://www.iso.org/obp/ui/#search]}

and updated Specification Last Updated

[Tasilee]

I'm making a start on splitting bdqffdq:Information Elements into "Information Elements ActedUpon" and "Information Elements Consulted". I am working through the tests in numerical sequence. Please check.

[ArthurChapman]

Does that affect Specification Last Updated?