Documentation: create a specifications document on how to write a MIxS LinkML slot #944

jfy133 · 2025-04-28T20:06:49Z

This is a natural extension of PR #943 .

Instead of providing examples to slots that can be used as templates by newcomers for writing/preparing new slots, this is meant to act as a precise and exact reference (as far as possible) of exactly how a slot should be designed.

I have based the structure (e.g. with numbering, which could be likely automated instead of manually defining by a website rendering engine) off of another bioinformatics community project I am heavily involved in (example).

This is not yet finished, and will likely need large community input - however I place this hear to kick-start a conversation.

I will write based on my impression of the MIxS LinkML schema.

Warning

This page is entirely based on the experiences of a novice user, and will likely require heavy editing by experts

…sStandardsConsortium#944

turbomam · 2025-05-06T14:10:10Z

I skimmed this and it looks like a fantastic starting point. I didn't see anything that I disagree with yet and I'm sure we can add more over time. So I will read it again more carefully and am looking forward to advocating for it to be merged in!

We should see if anything has come out of @only1chunts's related efforts about defining or clarifying the role of the different LinkML metaslots for MIxS terms/slots

@sierra-moxon and I have been talking about refining the definitions of LinkML metaslots, and this may serve as a contribution towards that.

jfy133 · 2025-05-07T13:15:46Z

nice :D I look forward to @only1chunts 's thoughts, and if mostly happy we can move to a bigger discussion in one of the TWG/CIG meetings?

src/docs/slot_specifications.md

…-standards-consortium-mixs into docs-slot-specifications

jfy133 · 2025-06-20T04:04:45Z

Mostly updated bsaed on your feedback @only1chunts, main outstanding one is about the mapping table

… definition)

src/docs/slot_specifications.md

turbomam

big positive step forward! Thanks @jfy133

src/docs/slot_specifications.md

turbomam · 2025-07-14T19:19:14Z

src/docs/slot_specifications.md

+| Term           | `slot`               | A single discrete bit of information (metadata) that has various attributes on how this information should be represented and formatted    |
+| Item           | `title`              | A short human readable name for the metadata term/slot                                                                                     |
+| MIXS ID        | `slot_uri`           |                                                                                                                                            |
+| Definition     | `description`        | A detailed human-readable explanation of what information the metadata term/slot should be holding                                         |


we need description writing guidelines. I recommend Guidelines for writing definitions in ontologies by Seppälä, Ruttenberg and Smith

We would need agreement on this from the wider TWG/CIG groups

src/docs/slot_specifications.md

turbomam · 2025-07-14T19:44:08Z

src/docs/slot_specifications.md

+
+The description SHOULD NOT include basic examples of the data the term is intended to hold (this is covered by the `examples` attribute).
+
+The description MAY include examples when the information for the term requires different formatting depending on certain conditions. The description MAY also include examples when it requires additional understanding that cannot be inferred by looking purely at the `examples` section.


examples please

I would need suggestoins as to what are the good examples of this from the CIG...

src/docs/slot_specifications.md

turbomam · 2025-07-14T19:46:24Z

src/docs/slot_specifications.md

+
+### 8.1 Number of keywords
+
+All term (slots) MUST have at least one keyword.


We need to discuss alignment and maintenance of keywords

personally I dislike keywords in general as they are by definition redundant, i.e. if its a key feature of the term then it should be in the name/title and or description. They are not useful for grouping things because they are uncontrolled free text, they are subjective based on the opinions of the person adding them and they are not specified to any particular level of granularity. But I'll step off my soap box now, rather than saying MUST I would suggest we use COULD.

I honestly agree, I never saw the purpose of them given there are sections/subsets already...

I could remove this for now as a specification and (leaving it entirely optional) unless @turbomam gives a useful use case and a way to standardise (in which case we keep it in, and bring it up for discussion with CIG/TWG)

turbomam · 2025-07-14T19:47:50Z

src/docs/slot_specifications.md

+
+### 9.2 MIXS ID format
+
+The MIXS ID (slot_uri) must begin with the string `MIXS`, a colon, and followed by a 7 digit number.


we should discuss who assigns these and when. Ideally, there would be no other system of record other than the schema file, so there could never be any conflicts.

@lschriml said at the GSC25 MIxS working day that currently this is specified on just prior release after a feature freeze for all new terms.

She was interest in automation of this though!

turbomam · 2025-07-14T19:57:00Z

Can we also take this opportunity to encourage/require the use of term creator, maintainer, last edited date metaslots etc?

src/docs/slot_specifications.md

jfy133 · 2025-08-11T20:08:41Z

@turbomam @only1chunts I think I've addressed all comments now, please have a look when you have a chance!

When i compar eagainst: https://www.gensc.org/pages/standards-intro.html

I think I've hit everything

MIxS Attribute	Covered	Spec section
Structured comment name	YES	Term structured naming
Item (rdfs:label)	YES	Term item title attribute
Definition	YES	Term description
Expected value	NO
Value syntax	YES	Slot range attribute
Example	YES	Term examples attribute
Section	YES	Term section attribute
Preferred unit	PARTIAL	Slot range attribute – Specifying units
Occurence	YES	Multiple occurance
MIXS ID	YES	Term MIxS ID attribute

I'm not sure how expected value fits in/if it's necessary, and the preferred unit bit whether what I've written is valid or not

jfy133 · 2025-08-11T20:11:12Z

Can we also take this opportunity to encourage/require the use of term creator, maintainer, last edited date metaslots etc?
* https://linkml.io/linkml-model/latest/docs/contributors/

* https://linkml.io/linkml-model/latest/docs/modified_by/

* https://linkml.io/linkml-model/latest/docs/created_on/

* https://linkml.io/linkml-model/latest/docs/last_updated_on/

I definitely think we should, but needs agreement from CIG/board etc I think..

src/docs/slot_specifications.md

only1chunts · 2025-08-12T07:31:02Z

src/docs/slot_specifications.md

+
+### 2.1 Term name length
+
+The term (slot) name must be a maximum of 20 characters in length as per INSDC guidelines ([https://www.insdc.org/submitting-standards/feature-table/#3.1](https://www.insdc.org/submitting-standards/feature-table/#3.1)).


replace "term (slot) name " with "structured comment name (name)", this should be done for heading 2.2 (nb that number needs to be corrected too, its currently 2.1), 2.4, 2.5, 2.6 and 2.7. and in other places in this section text.

I've updated but I would like to lightly protest this on my own soapbox: what is a 'structured comment' even?! A comment to me refers to additional possibly opinionated information... I wouldn't use 'comment' to refer for such a fundamental thing like a name... I think that's why I went simply for just 'Term name' because I'm very worried a reader not particular familiar with MIxS will not know what we are talking about (in case they skipped the mapping table)

Maybe we should bring up using the alias "short name" in place of "strucutred comment name" with CIG? I dont think we can entirely deprecate the use of "structured comment name" but we may be able to promote the use of "short name" in most instances.

short name would definitely be better - but I think key name would be a more precise word for it... it's the 'computerised' version to refer to that 'item'(?)

It's not really meant to be an 'alias' for humans

src/docs/slot_specifications.md

only1chunts · 2025-08-12T07:53:33Z

src/docs/slot_specifications.md

+
+## 4. Term data types
+
+### 4.1 Term data types must be valid LinkML types


I guess there is no direct MIxS equivelent to this? But I think it should be included in the table in preamble terminology table in the 'range' row. It just sort of jumped out of the blue here as a new concept. Maybe we want to change the header 4.1 to "The data types of a range must be valid LinkML types"

I'm not sure now - your comment above seemed to imply that expected value is the same as range, just range is much more restricted in the different types? Or is it not eqivalent then?

src/docs/slot_specifications.md

only1chunts · 2025-08-12T09:36:12Z

src/docs/slot_specifications.md

+### 10.2 Specifying units
+
+Terms (slots) that require the use of a measurement unit SHOULD specify the types of units through a dedicated structured string pattern component.
+


I'm not sure what this means? I thought we were encouraging the use of the 'preferred_unit:' linkml field for the unit requirements, which is also a MIxS word and should be included in the table at the top.

Is preferred_unit a LinkML thing:? It's not specified anywhere in the existing mixs.yaml 🤔

I also don't find a refernce to it in the linkml docs: https://linkml.io/linkml/search.html?q=preferred_unit&check_keywords=yes&area=default

if you search for the word "preferred_unit" in the mixs.yaml file you will see 238 instances of it. If you look in the old v6 excel spreadsheet there is a column for "Preferred unit". I dont know if its from the off-the-shelf linkml or something thats been added specificly for our use case, but its definately there.

yes, I'm aware of it in the MIxS Excel spreadsheet/original MIxS, but maybe I'm being crazy but I'm not finding it in the schema...:

Scratch that: it's spelt Preferred_unit (why the captial!?)

Updated, but I find it sort of unsatisfying (also the way the preferred units have been specified is very messy, with some having loads of different 'preferred' units... which sort of defeats the point...

e.g.

abs_air_humidity: annotations: Preferred_unit: gram per gram, kilogram per kilogram, kilogram, pound, gram per cubic meter, kilogram per cubic meter, percent

src/docs/slot_specifications.md

…ring

only1chunts · 2025-08-14T13:46:17Z

src/docs/slot_specifications.md

+- [`keywords`](https://linkml.io/linkml-model/latest/docs/keywords/).
+- [`slot_uri`](https://linkml.io/linkml-model/latest/docs/slot_uri/).
+- [`range`](https://linkml.io/linkml/schemas/slots.html#ranges).
+


two points on section 4.1:
a. Should hte structured comment name be included in the list of required attributes? technically I guess its not an attribute in LinkML speak because its the slot identifier, but it is required.
b. For completeness can we include the MIxS terminology in the list as well?

jfy133 added 2 commits April 28, 2025 21:56

Create slot_specifications.md

c2c5c26

Update slot_specifications.md

90c944f

jfy133 added a commit to jfy133/genomics-standards-consortium-mixs that referenced this pull request Apr 28, 2025

Remove files moved to PRs GenomicsStandardsConsortium#943 and Genomic…

129cb07

…sStandardsConsortium#944

jfy133 added 2 commits May 5, 2025 21:32

Complete all sections of an (unoffiical) metadata slot specification

faf5016

Additional tweaks

f3266b2

jfy133 marked this pull request as ready for review May 5, 2025 19:37

jfy133 added 4 commits May 12, 2025 20:41

Add point about multivalue examples

a7239d2

Tweak example of the multivalued slot

e592243

Experiment with preview building

7632c66

Delete .github/workflows/test_pages_build.yaml

9e86e3b

only1chunts reviewed Jun 19, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

only1chunts reviewed Jun 19, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

only1chunts reviewed Jun 19, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

only1chunts reviewed Jun 19, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

only1chunts reviewed Jun 19, 2025

View reviewed changes

src/docs/slot_specifications.md Show resolved Hide resolved

only1chunts reviewed Jun 19, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

jfy133 added 3 commits June 20, 2025 05:57

Update a couple of places based on feedback from @only1chunts

6687982

Merge branch 'docs-slot-specifications' of github.com:jfy133/genomics…

80c5e0a

…-standards-consortium-mixs into docs-slot-specifications

Second sentence tweak

224e17b

Add terminology mapping table, and start updating text (continue from…

2446be8

… definition)

jfy133 changed the title ~~Create a specifications document on how to write a MIxS LinkML slot~~ Documentation: create a specifications document on how to write a MIxS LinkML slot Jul 14, 2025

turbomam reviewed Jul 14, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

Complete text update for using both MIxS and LinkML terminology

464dc38

turbomam reviewed Jul 14, 2025

View reviewed changes

mslarae13 mentioned this pull request Jul 31, 2025

mapping GSC historical terminology and LinkML metaslots #1042

Open

jfy133 requested a review from lschriml July 31, 2025 15:05

jfy133 commented Aug 11, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

jfy133 added 3 commits August 11, 2025 22:04

Update src/docs/slot_specifications.md

2363e34

Reformat

9aef344

Addm issing MIxS ID reference in mapping table

a8475b6

jfy133 requested review from only1chunts and turbomam August 11, 2025 20:08

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

jfy133 commented Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

Update src/docs/slot_specifications.md

1fb3125

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Show resolved Hide resolved

only1chunts reviewed Aug 12, 2025

View reviewed changes

src/docs/slot_specifications.md Outdated Show resolved Hide resolved

jfy133 added 6 commits August 12, 2025 12:10

Add link to linkml model docs for see also

76031e9

Few more corrections after @only1chunts's review and fix header numbe…

86f1dd1

…ring

Add example mapping to terminolgoy table

80a2879

Fix environment subset guidance

9a8d932

Correct guidance for specifying units

b6b12d2

Improve definition

b579ab2

only1chunts reviewed Aug 14, 2025

View reviewed changes


		The description SHOULD NOT include basic examples of the data the term is intended to hold (this is covered by the `examples` attribute).

		The description MAY include examples when the information for the term requires different formatting depending on certain conditions. The description MAY also include examples when it requires additional understanding that cannot be inferred by looking purely at the `examples` section.


		### 8.1 Number of keywords

		All term (slots) MUST have at least one keyword.


		### 9.2 MIXS ID format

		The MIXS ID (slot_uri) must begin with the string `MIXS`, a colon, and followed by a 7 digit number.


		### 2.1 Term name length

		The term (slot) name must be a maximum of 20 characters in length as per INSDC guidelines ([https://www.insdc.org/submitting-standards/feature-table/#3.1](https://www.insdc.org/submitting-standards/feature-table/#3.1)).


		## 4. Term data types

		### 4.1 Term data types must be valid LinkML types

		### 10.2 Specifying units

		Terms (slots) that require the use of a measurement unit SHOULD specify the types of units through a dedicated structured string pattern component.

Documentation: create a specifications document on how to write a MIxS LinkML slot #944

Are you sure you want to change the base?

Documentation: create a specifications document on how to write a MIxS LinkML slot #944

Uh oh!

Conversation

jfy133 commented Apr 28, 2025

Uh oh!

turbomam commented May 6, 2025

Uh oh!

jfy133 commented May 7, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jfy133 commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

turbomam left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

only1chunts Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

turbomam commented Jul 14, 2025

Uh oh!

Uh oh!

jfy133 commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jfy133 commented Aug 11, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

only1chunts Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jfy133 commented Jun 20, 2025 •

edited

Loading

only1chunts Aug 12, 2025 •

edited

Loading

jfy133 commented Aug 11, 2025 •

edited

Loading

only1chunts Aug 12, 2025 •

edited

Loading

jfy133 Aug 12, 2025 •

edited

Loading