the repetition of attribute descriptions in TRAPI messages can adversely affect system performance

[bill-baumgartner]

Attributes have a description field allowing documentation of the attribute to accompany its value as part of a TRAPI message.

ReasonerAPI/TranslatorReasonerAPI.yaml

Lines 701 to 706 in 96fc1ea

	description:
	type: string
	description: >-
	Human-readable description for the attribute and its value.
	example: Assertion Authored By Dr. Trans L. Ator
	nullable: true

For messages that contain many edges or for edges that have many attributes, e.g. a text-mined assertion may have 100's of evidence sentences represented as individual edge attributes, the attribute descriptions can add significantly to the size of the message which may contribute adversely to system performance. For example, the repeated attribute descriptions in a recent large (40MB) result from the Text Mining Provider were estimated to account for ~27% of the message size.

What is the best practice for the use of attribute descriptions? One suggestion has been to replace the text of the descriptions with URLs linking to external documentation. Another option could be to rely on the Biolink definition of each attribute_type_id to serve as the description, and to remove the description field entirely. Are there alternative suggestions/recommendations? Is there a preferred approach?

[edeutsch]

It's a good question about a problem that affects several of us now. I don't think we have a well documented set of best practices. But maybe we should develop one.

I had envisioned description to be something that would help the viewer understand what the attribute means in cases where the ontology terms used don't necessarily capture the concept well. For example if the attribute_type_id is biolink:synonyms, then you don't need a description. So maybe one policy could be that if the ontology terms describe the concept well, then just leave out the description. Only use a description if the ontology terms used doesn't naturally lead to a sufficiently detailed understanding of the attribute value.

I do rather like the idea of a URL leading to a detailed description. But placing that in the description property seems a bit icky.

[andrewsu]

So maybe one policy could be that if the ontology terms describe the concept well, then just leave out the description. Only use a description if the ontology terms used doesn't naturally lead to a sufficiently detailed understanding of the attribute value.

+1 to this idea from Eric. I agree that putting a URL in a description (my half-baked suggestion) is a bit icky.

(Slightly more context with a real example file are found in this thread: https://ncatstranslator.slack.com/archives/C022EL8D3AB/p1637300364047100?thread_ts=1637274714.045500&cid=C022EL8D3AB.)