Update process for using display hints directly from the schema

[jeffbaumes]

Look into a process and verification that display hints from the schema are being utilized properly by the web UI. Specifically, we could look into doing this for the study metadata in the submission portal and ensure we are directly using display hints like the following in the UI:

@turbomam @cmungall FYI.

[aclum]

@turbomam @naglepuff @marySalvi @jeffbaumes This has come up in some of the data portal user research. What is the best practice for which schema slot should be used for a tool tip display in nmdc UIs like the data portal? The screen shot above indicates it should be slot_usage.$SLOT.annotations.display_hit.value. Is that still correct?

[aclum]

Default to description and have a way of overwriting it. @turbomam will do this for env context terms using annotations (ie brief_description)

[turbomam]

See here for existing examples:

https://github.com/microbiomedata/nmdc-schema/blob/1d24f0de0f7ad0e7c9ef11a6c83fc34ff2c21dbc/src/schema/core.yaml#L230-L258

[turbomam]

related?

• Clarify what "sample" means across pages #1220

[dwinston]

[not directly addressing this issue, but noting here as related]

There may be an opportunity to spin out a separate “governance tier” for slot definitions for informal annotations, represented more dynamically e.g. as a database (“slotbase”?) rather than as a set of yaml files in a git repo.

prior art / reference: https://metadata.raid.org/en/latest/#core-extended-and-local-metadata-schema-components

[turbomam]

• Do we want to have multiple kinds of annotations? What would their names be?
• How would Kitware/nmdc-server access the values? Easy with Python SchemaView()
• Who is going to populate the values?

[turbomam]

Use alt_descriptions instead?

microbiomedata/berkeley-schema-fy24#167

[turbomam]

actually alt_descriptions isn't the best choice. we do have display_hint annotations already. but I propose switching them all to tool_tip annotations.

[aclum]

So slot_usage.$SLOT.annotations.tool_tip.value?

[aclum]

@turbomam I don't see any examples in berkeley-schema-fy24 or nmdc-schema which illustrate your most recent suggestion.

[aclum]

Using microbiomedata/nmdc-schema#2120 as an example for how this should be formatted.

[aclum]

Example of preferred way to model this:

    annotations:
      tooltip:
        tag: tooltip
        value: GOLD Ecosystem Classification paths describe the surroundings from which an environmental sample or an organism is collected.
        annotations:
          source: https://gold.jgi.doe.gov/ecosystem_classification

[turbomam]

Actually, I don't recommend that format (in which the annotation's key is repeated in the tag position) unless you need to make additional annotations on the tooltip annotation.

Otherwise, this compact form is preferable (in my opionion)

    annotations:
      tooltip: GOLD Ecosystem Classification paths describe the surroundings from which an environmental sample or an organism is collected.