v2 "alpha" species/match API

[timrobertson100]

To support the new occurrence ingestion pipelines [and in particular see issue 7] we'd like to revise the species/match API to reduce the possibility of mistakes by callers. In particular issues exist around handing of synonyms and especially where that spans species and subspecific ranks.

The design goals are to:

1. Return a single result that should contain all keys and strings that can be copied verbatim into e.g. an interpreted occurrence view
2. Enable the ability to add new ranks in the future without changing the API response format
3. Make clearer separation of nomenclature and taxon concept
4. Expose information explaining the reasoning behind the resulting match
5. Raise the profile of nomenclature databases in their roll in this process. Exposing source nomenclature IDs (e.g. an IPNI LSID) enables reporting and search of occurrences using their IDs.

An initial response format for a Felis concolor conccolor match might be:

{
  "synonym": true,
  "confidence": 98,

  // this is a synonym, so this effectively documents the 'name' and not the taxon concept
  "usage": {
    "key": 6164627, "rank": "SUBSPECIES", "name": "Felis concolor concolor (Kerr 1871)",
  }
  
  // the following documents the accepted taxon concept (it may repeat the above)  
  "acceptedUsage": {
    "key": 7193927, "rank": "SUBSPECIES", "name": "Puma concolor subsp. concolor (Tim 1872)"
  }
  
  // holds the nomenclature ID (IPNI, IF, ZK etc)
  "nomenclature": {
    "source": "IPNI", "id": "urn:lsid:ipni.org:names:1234-1"  // obviously bogus here
  }

  // the classification includes the accepted taxon concept view
  "classification": [
    {"key": 1, "rank": "KINGDOM", "name": "Animalia"},
    {"key": 44, "rank": "PHYLUM", "name": "Chordata"},
    {"key": 359 "rank": "CLASS", "name": "Mammalia"},
    {"key": 732, "rank": "ORDER", "name": "Carnivora"},
    {"key": 9703, "rank": "FAMILY", "name": "Felidae},
    {"key": 2435098, "rank": "GENUS", "name": "Puma Jardin 1834"},
    {"key": 2435099, "rank": "SPECIES", "name": "Puma concolor (Linneaus 1771)"},
    {"key": 7193927, "rank": "SUBSPECIES", "name": "Puma concolor subsp. concolor}
  ],

  // intended for anyone seeking clarity on why it arrived on the  result (e.g. debugging)
  "lineage": [
    "Fuzzily matched [Felis concolor subsp. conccolor] to [Felis concolor subsp. concolor]",
    "Synonym [Felis concolor subsp. concolor] to [Puma concolor subsp. concolor] provided by [Catalogue of Life]",
    "No potential homonyms detected in ancestry" 
  ],

  // intended for "internal users"
  "diagnostics": {
    "status": "SYNONYM",
    "matchType": "EXACT",
  "note": "Similarity: name=110; authorship=0; classification=-2; rank=5; status=0;singleMatch=5",
  }
}

[mdoering]

first implementation just wrapping the classic response to the new API. This misses the accepted usage and lineage still which requires a refactoring: f472d81

[mdoering]

http://api.gbif-uat.org/v1/species/match2?verbose=true&name=Abies%20alba

[mdoering]

update to include the accepted usage: http://api.gbif-uat.org/v1/species/match2?verbose=true&name=Agallisus%20lepturoides

[thomasstjerne]

gbif/pipelines#9 (comment)

Maybe this as a matter of changing the "classification" property from object to array?
To facilitate facetting on taxonomic lineage/path