permit assertion descriptions to include references to supporting resources (CIViC or otherwise)

[jmcmichael]

Assertion descriptions will need to include references to internal CIViC entities and other resources e.g. EIDs, ACMG codes, PubMed articles, etc. Descriptions are intended to be a condensed rationale behind the summary statement, and must therefore include references to supporting evidence from a variety of sources.

These descriptions will likely be displayed in various knowledgebases and/or reports without the benefit of the surrounding CIViC context for reference. Therefore, we cannot use CIViC conventions or other non-standard methods for these links. Furthermore, we cannot depend on markup or template methods that require parsing and rendering as it's likely that the descriptions will be displayed in many contexts that do not have these capabilities, including printed reports. So we need to target the simplest display format: plain text.

We also want to avoid burdening our curators with the task of keeping in mind the various contexts in which their descriptions might be displayed, or the technical minutia of constructing links in some weird format. So whatever linking method we choose must be exceedingly simple to use, and appear the same in every context it is displayed.

Fortunately a URI standard exists that meets these requirements: CURIE identifiers. CURIE identifiers a compact uniform resource identifier from the XML ecosystem, and a W3C standard. They're simple, composed of a prefix and a reference separated by a colon and surrounded by square brackets, e.g.: [isbn:123456], [pubmed:16333295], [ncbigene:100010]. A reference to a CIViC evidence item will look like [civic:EID1234], which would replace the current convention of referring to CIViC evidence as EID1234. And, while they're not quite as readable as EID1234, they're a LOT more readable than <a href='https://civicdb.org/links/evidence/1234'>EID1234</a>, or pretty much any other linking/templating/markup method we've found.

CURIES are readable, in that they don't interrupt the flow of reading and understanding a block of text - so they can be printed as raw text w/o appreciably diminishing the quality of the content, for display contexts that do not support linking (like paper-printed text). The CIViC namespaced CURIE will be resolvable via an identifiers.org API and the the CIViC /links endpoint. And they are machine parseable such that they can be converted into uniform resource links in contexts that support this (like CIViC or any web-based medium).

Implementing CURIE linking, and integrating it into the CIViC requires:

• submit application to identifiers.org for civic CURIE namespace
• implement CIViC client parser to convert CURIEs to HTML anchors within CIViC descriptions
• implement CIViC client macro for aiding construction of CURIEs while curating
• implement CIViC server parser for CURIEs submitted to /links URL
• update CIViC docs, helptext etc. to reflect changes in curation workflow, UI features, and API

[malachig]

Note this issue documenting our registering of specific CURIEs:
#1631