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.

[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?

[Tasilee]

I was wondering about that. Paul Call?

[Tasilee]

Removed TestField "Warning Type" as it highly correlates with "Data Quality Dimension". I will be working through the 99 CORE tests making this change but will not add separate Comments, so to reduce another round of email notifications.

[chicoreus]

Updated notes to replace "fail" with more explicit: This test must return NOT_COMPLIANT if there is leading or trailing whitespace or there are leading or trailing non-printing characters.

[Tasilee]

Playing with this test as an example for the Example Use Case (replaced 'Source')

[Tasilee]

Recent discussions by the team resulted in recommendations for how we handle Use Cases. This test is an example template for all other tests (CORE, Supplementary, DO NOT IMPLEMENT and Immature/Incomplete) and will not be further commented.

The Use Cases will be documented in the form of Label - Description in the Vocabulary (#152).

Use Case being Informative (non-normative), we will not update 'Specification Last Updated'. Speak now or forever ....

[chicoreus]

Note that the recommendation was that we place the UseCase definitions and relationships of UseCases to Tests in a separate document, not include the application of UseCases to tests in the tests, and rever this test to show the source, rather than replacing source with UseCase. In the UseCase document, the UseCase label and guid should probably be normative, and the description, citations, and list of included tests should be informative.

…

On Thu, 11 Apr 2024 21:52:05 -0700 Lee Belbin ***@***.***> wrote: Recent discussions by the team resulted in recommendations for how we handle Use Cases. This test is an example template for all other tests (CORE, Supplementary, DO NOT IMPLEMENT and Immature/Incomplete) and will not be further commented. The Use Cases will be documented in the form of Label - Description in the Vocabulary (#152). Use Case being Informative (non-normative), we will not update 'Specification Last Updated'. Speak now or forever ....

[Tasilee]

Changed "was" to "is" to align with standard phrasing in ER as in "INTERNAL_PREREQUISITES_NOT_MET if xxx is EMPTY"

[chicoreus]

Discussion of how to mark the high seas in TG2 working group meeting in Seattle: Options are "High Seas" in dwc:country, used by three institutions feeding data to GBIF for about 60k occurrences, a three letter country code BNJ (beyond national jurisdiction) used by OBIS (along with BBNJ for biological material beyond national jurisdition), or the UN use of the User assigned codes in the ISO country code standard of XZ for installations on the high seas, in some use for marking origins from the high seas.

dwc:countryCode=XZ, country="" appears the best means to mark occurrences as being in the high seas, this is consistent with the darwin core specification of ISO country code values.

[Tasilee]

Thanks to @davewatts3 for raising the BBJ and BBNJ possibilities which we have noted. Hopefully we get some solution to this in the future.

[Tasilee]

The Expected Response/Specification in this test is now the only odd one in that it references both bdq:sourceAuthority and ISO 3166-1-alpha-2 when the former is the latter, which I think could be confusing:

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; otherwise NOT_COMPLIANT

We have at least three instances where it is probably better phrased: #199, #200 and #201.

Thoughts?

[chicoreus]

On Tue, 17 Sep 2024 19:53:42 -0700 Lee Belbin ***@***.***> wrote: interpreted as a valid ISO 3166-1-alpha-2 country code;

"interpreted as a valid country code in the bdq:sourceAuthority;" ? Both hasExpectedResponse and hasAuthoritiesDefaults are data properties off of Specification, so no particular concern in generalizing to source authority here, even though we don't have a parameter: https://raw.githubusercontent.com/tdwg/bdq/master/tg2/_review/docs/bdqffdq_guide/bdqffdq_data_quality_needs_validation.svg In order to change to a three letter country code, a new specification would need to be framed in either case (though the framework allows this to happen off the same Validation, separating the generality of satisfying criteria for the information element from the specifics iin the specification).

[Tasilee]

To align the Expected Response/Specification with the standard pattern, I've changed it from

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; otherwise NOT_COMPLIANT

to

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