Get feedback on current `gorefs.yaml` format and update if needed

[pkalita-lbl]

Review the format of the current gorefs.yaml file. If changes are desired, then use this issue to also:

• [ ] Update the LinkML schema which describes the format
• [ ] Ensure that the Markdown-to-YAML script produces the correct updated format

[pkalita-lbl]

I have two comments.

First is that most of the other metadata YAML files seem to be structured as an array at the top-level, such as:

- id: one
- id: two
- id: three

Whereas the current structure of gorefs.yaml wraps things in a top-level field:

gorefs:
  - id: one
  - id: two
  - id: three

This is probably influenced by the fact that LinkML implicitly encourages this kind of modelling, but recent changes to LinkML validation means it's not strictly required. If we want a top-level array that's fine.

Second is that I don't think the layout field is doing anything for us. No entries have anything other than layout: goref. I think any downstream page-building code should be free to choose an appropriate layout; it doesn't need to be asserted in the metadata.

@kltm who else might have input here?

[kltm]

@pgaudet Could have some input here (and is PO), but I think this is likely a more technical detail. I'll try and touch bases with her tomorrow morning. Sans input, I would go ahead with the most "natural" LinkML possible.

[pgaudet]

Hi @pkalita-lbl If the layout is not useful I would be in favor of removing it from the schema and from the files. I thought it was rendering the table as in https://github.com/geneontology/go-site/blob/master/metadata/gorefs/goref-0000001.md

It seems like some of these yaml schemas were copied/pasted and not always contain strictly relevant items, some fields do seem superfluous. Let me know if you want to go over this on a call, it may be easier for all of us (and also to write up some doc, if needed).

Thanks, Pascale

[pkalita-lbl]

I thought it was rendering the table

Nope! That's just part of GitHub's Markdown rendering. And just in case the big picture wasn't clear from all the granular issues: the end result will be that these Markdown files won't exist at all anymore, replaced by generated pages hosted on geneontology.org.

It seems like some of these yaml schemas were copied/pasted and not always contain strictly relevant items

That's definitely my impression, too! Since it seems like there aren't extremely strong opinions on this, I'll take a crack at doing the simplifications already mentioned. Once there's something to look at maybe we can find a venue for the three of us (plus anyone else who might be interested) to review it.

[suzialeksander]

I don't need to review necessarily but just keep me in the loop if anything on the geneontology.org changes. FYI the menus and headers on geneontology.org will be changing in the near future so "just place it anywhere" is a valid location for now as long as I know about any new pages I need to rehome.

[pkalita-lbl]

@pgaudet @kltm @suzialeksander Here is a proposal for the format of gorefs.yaml going forward:

https://gist.github.com/pkalita-lbl/4551e15e90407ad1f514a6f854fd26b5

Some fields to note:

• title: A single, required string. This is the text from first header in the Markdown files.
• description: A single, required string. This is the text from the remaining Markdown content (unless there is a "Comment" header in the document -- such as https://github.com/geneontology/go-site/blob/master/metadata/gorefs/goref-0000002.md -- which is not included in this field).
• comments: A array of strings (not required). This is the text of the Markdown content under the "Comment" header if it exists.

All of the fields from the Markdown frontmatter section (authors, id, year, etc) are copied directly over except for layout which isn't needed so is dropped.

Does this look like a format you'd be comfortable working with when we deprecate the Markdown files?

[pgaudet]

Hi @pkalita-lbl Are all the references going to be in a single page, and links will be to anchors within that page?

[pkalita-lbl]

They can be if that is what's desired. Or they can be separate pages. Those options aren't necessarily mutually exclusive; both individual pages and an index page could exist. But that's all sort of orthogonal to the task of this issue. The details of the generated page(s) will be worked out in https://github.com/geneontology/geneontology.github.io/issues/506.

[kltm]

Talking to @pkalita-lbl on https://github.com/geneontology/go-site/issues/2232#issuecomment-1958044207 , we'll go ahead with his schema.