Linking keys - AtlasOfLivingAustralia/ala-keys-ui Wiki

There are two types of links available in KeyBase for the items that can be keyed out. One goes to a page with information about the item (taxon). In the default display this link is under the name of the item and by default (unless another URL is set for the project) it links to the page for the taxon in the ALA Biodiversity Information Explorer. The other, which is by default displayed as an arrow after the item name, links to the next key in KeyBase. Keys in KeyBase are linked from the keyed-out item to (what I have called) the 'taxonomic scope' of the next key. (It turns out I may have adopted that from SDD)

There are situations where the next key you want to link to is not the key to the taxon that has been keyed out. The most important case is where a taxon that keys out is monotypic in the scope of a project (i.e. has only one directly subordinate taxon), but the subordinate taxon – or the subordinate taxon of that etc. – itself has multiple directly subordinate taxa. An example is in the Key to the families in the Flowering plants of Australia project, where there is only one genus in the family Dioscoreaceae, but that one genus, Dioscorea, itself has five species. So the key to the species of Dioscorea is an orphan key, as there is no key to the genera of Dioscoreaceae) to provide the link between that key and the key to the families.

Orphan keys and missing links between keys are ostensibly not so much of a problem when KeyBase keys are ran inside other projects, as in the other project the keys will be linked through the taxonomy in that project. However, KeyBase doesn't have a taxonomy, just linked (or not) keys, so, if you use the keys in KeyBase, your identification might very well end prematurely. More importantly, missing links break the global filters: if your filter includes an item from an orphan key, the filtered key won't be able to key out that item. In the above example, if the filter contains Dioscorea or one of its species, the filtered key to the families will not contain Dioscoreaceae, as the link between Dioscorea and Dioscoreaceae is missing. To my great chagrin, the global filters is what most people like most about KeyBase.

I resolved this by creating the ability to put another link in. You actually see that in published keys sometimes (but not so much for monotypic taxa). People can add them in the keys they upload by adding the extra item between braces, like 'Dioscoreaceae {Dioscorea}' (I had parentheses first, but parentheses occur in the CHAH-endorsed junk names, so that broke a few keys). At first the extra item was a second item in the Lead record, which worked fine for monotypic taxa, but, as soon as I had implemented it, people started to use it for other things than monotypic taxa, which caused a problem in the display of the Player. For example, in the same family key cited above, things that had been entered as 'Cunoniaceae', 'Cunoniaceae {Bauera}', 'Cunoniaceae {Davidsonia}' and 'Cunoniaceae {Eucryphia}' might display as 'Cunoniaceae: Eucryphia', as that is the one that occurs first in the key.

I tried to turn it around, i.e. the subordinate taxon as the main item and the parent (or ancestor) as the extra item, but that broke something else, so in the end I decided to have a "compound" item with two member items, the parent and the child. In the JSON of the web service I currently have it in a possibly rather confusing (not to me) way, like so:

{
  "item_id":"37943",
  "item_name":"Cunoniaceae",
  "url":"http:\/\/bie.ala.org.au\/species\/urn:lsid:biodiversity.org.au:apni.taxon:397725",
  "to_key":"275",
  "link_to_item_id":"9703",
  "link_to_item_name":"Eucryphia",
  "link_to_url":"http:\/\/bie.ala.org.au\/species\/urn:lsid:biodiversity.org.au:apni.taxon:374516",
  "link_to_key":"2913"
}

Probably better is something like this:

{
  "item_id":"37941",
  "item_name":"Cunoniaceae",
  "url":"http:\/\/bie.ala.org.au\/species\/urn:lsid:biodiversity.org.au:apni.taxon:397725",
  "to_key":"275"
}

for "simple" items and

{
  "item_id":"37943",
  "item_name":"Cunoniaceae (Eucryphia)",
  "member_items": [
    {
      "order":"parent",
      "item_id":"37941",
      "item_name":"Cunoniaceae",
      "url":"http:\/\/bie.ala.org.au\/species\/urn:lsid:biodiversity.org.au:apni.taxon:397725",
      "to_key":"275"
    },
    {
      "order":"child",
      "item_id":"9703",
      "item_name":"Eucryphia",
      "url":"http:\/\/bie.ala.org.au\/species\/urn:lsid:biodiversity.org.au:apni.taxon:374516",
      "key":"2913"
    }
  ]
}

or

{
  "item_id":"37943",
  "item_name":"Cunoniaceae (Eucryphia)",
  "parent_item": {
    "item_id":"37941",
    "item_name":"Cunoniaceae",
    "url":"http:\/\/bie.ala.org.au\/species\/urn:lsid:biodiversity.org.au:apni.taxon:397725",
    "to_key":"275"
  },
  "child_item": {
    "item_id":"9703",
    "item_name":"Eucryphia",
    "url":"http:\/\/bie.ala.org.au\/species\/urn:lsid:biodiversity.org.au:apni.taxon:374516",
    "key":"2913"
  }
}

for "compound" items.