Documentation: MIxS Term (linkML slot) specification documentation by jfy133 · Pull Request #944 · GenomicsStandardsConsortium/mixs

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

…ring

src/docs/slot_specifications.md

…tions

Woolly-at-EBI

This is really useful.
Most of my comments are minor

src/docs/slot_specifications.md

Woolly-at-EBI · 2025-09-09T16:41:19Z

src/docs/slot_specifications.md

+
+### 8.2 All extension terms must be assigned the environment subset
+
+A term (slot) defined in an extension (rather than a core checklist term) MUST be assigned to the 'Environment' section (subset).


clarification sought: as well as "core terms" there will be some terms that occur in both environmental and non-environmental use cases, but not in all use cases so it is it correct to say "must"?
For example at ENA we are working on an "laboratory animal checklist", yes a laboratory is obviously an environment, but it is not quite like a pond or even a building, when the subject is a mouse, okay the mouse is a kind of environment too. Umm my head is hurting.

I never actually understood why some terms were repeated in the extensions (it seems), e.g. samp_name is in all the extensions, but it is in the 'core' checklists? Unless this is an error @turbomam or @mslarae13 would you happen to know?

Originally we had core terms. These were terms we anticipated being used across many (genomic) checklists.
Currently we have genomic checklists and environmental extensions. With the idea that sample metadata that is being submitted, e.g., to INSDC, would include terms from a checklist and one or more environmental extensions. However, the submission could be using just a 'genomic checklist'. Thus 'sample name' is the key term to have in any reported metadata submission.

Woolly-at-EBI · 2025-09-09T16:47:43Z

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.
+


Agree preferred_unit ought to be snake_case and lower case.
The preferred_unit's do serve a useful purpose in that theoretically an implementor can validate them. Many systems do hold the unit and the value separately to reduce complexity, but I get that people are worried about losing the units. (It would be a major and unwelcome short term change for many implementors)

src/docs/slot_specifications.md

…to mkdocs

…reation/updating

Woolly-at-EBI

Agree with the changed following my suggestions. Thank you.

lschriml

Would be useful to combine sections of this document that are similar.
And to separate the MIxS specific and LinkML specific sections.

src/docs/slot_specifications.md

lschriml · 2025-11-25T17:55:21Z

src/docs/slot_specifications.md

+- [`modified_by`](https://linkml.io/linkml-model/latest/docs/modified_by/)
+- [`last_updated_on`](https://linkml.io/linkml-model/latest/docs/last_updated_on/)
+
+### 15.2 Terms should record original author


This is LinkML, not MIxS

lschriml · 2025-11-25T17:55:37Z

src/docs/slot_specifications.md

+created_by: orcid:0000-1234-1234-1234 # Erika Mustermann
+```
+
+### 15.3. Term creation date should be recorded


This is LinkML, not MIxS

also for the sections below.

lschriml · 2025-11-25T17:56:16Z

src/docs/slot_specifications.md

+
+The date in which the term (slot) was updated or modified SHOULD be recorded using the LinkML [`last_updated_on`](https://linkml.io/linkml-model/latest/docs/last_updated_on/) attribute.
+
+## 16 Importing terms from other standards


this is covered earlier

these sections should be merged, reviewed.

lschriml · 2025-11-25T17:57:13Z

src/docs/slot_specifications.md

+
+- [Darwin Core (DwC)](https://dwc.tdwg.org/)
+
+### 16.2 Imported external standards terms requirements


to be reviewed

lschriml · 2025-11-25T17:57:37Z

src/docs/slot_specifications.md

+
+Minor modifications to the term (slot) structured comment (name) MAY BE made to ensure compliance with MIxS naming conventions.
+
+## References


not part of MIxS

Co-authored-by: lschriml <[email protected]>

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

Copilot

Pull request overview

Adds a new reference-style specification document describing how MIxS metadata terms (“slots”) should be designed in the LinkML schema, and updates MkDocs configuration to support footnotes used by the new document.

Changes:

Add src/docs/slot_specifications.md with detailed guidance for MIxS slot design (naming, ranges, examples, provenance, etc.).
Enable Markdown footnotes in mkdocs.yml to render the new document correctly.
Minor cleanup in mkdocs.yml (removal of an extraneous line).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 16 comments.

File	Description
src/docs/slot_specifications.md	Introduces a comprehensive slot/term specification guide (new documentation page).
mkdocs.yml	Enables `footnotes` extension and cleans YAML to support rendering the new doc.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-11T00:33:59Z

src/docs/slot_specifications.md

+
+### 11.1 Range options should be valid LinkML types
+
+See section [4](#4-data-types).


Broken internal reference: "See section 4" points to an anchor that doesn't exist in this document (section 4 is "Attributes for MIxS terms"). Update the link target/text to the intended section (likely section 3 on range types).

Suggested change

See section [4](#4-data-types).

See section [3](#3-data-types).

Copilot · 2026-03-11T00:34:00Z

src/docs/slot_specifications.md

+
+A term that requires a specific value syntax or a structured string layout SHOULD use the `structured_pattern` slot attribute, where the pattern components SHOULD be predefined in the `settings:` section of the schema when theoretically could be used more than once.
+
+A slot MAY use `pattern:` attribute when XYZ <!-- TODO -->.


This section still contains a placeholder ("when XYZ "). If this is intended to be merged as a reference specification, the TODO should be resolved or converted into an explicit "TBD" note with a tracking issue/link so readers don't treat it as normative guidance.

Suggested change

A slot MAY use `pattern:` attribute when XYZ .

> [!NOTE]

> TBD: The specific conditions under which a slot MAY use the `pattern:` attribute instead of `structured_pattern` are under discussion and will be documented in a future revision of this specification. See the project issue tracker for the latest status.

Copilot · 2026-03-11T00:34:00Z

src/docs/slot_specifications.md

+| `culture`   | `cult_`      | `cult_result_org`                |
+| `culture`   | `cult_`      | `cult_root_med`                  |
+| `dissolved` | `diss_`      | `diss_carb_dioxide`              |
+| `dissovled` | `diss_`      | `diss_hydrogen`                  |


Copilot · 2026-03-11T00:34:00Z

src/docs/slot_specifications.md

+- `integer`
+- `float`
+- `boolean`
+- An '[enumeration](#145-enumerations)' (i.e., controlled vocabulary') predefined by MIxS (see top of the [schema](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/mixs/schema/mixs.yaml#L28)).


This bullet has mismatched quotes/parentheses ("An '[enumeration]...'" and "controlled vocabulary'") which renders oddly and may confuse readers. Clean up the quoting so the sentence reads unambiguously.

Suggested change

- An '[enumeration](#145-enumerations)' (i.e., controlled vocabulary') predefined by MIxS (see top of the [schema](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/mixs/schema/mixs.yaml#L28)).

- An [enumeration](#145-enumerations) (i.e., controlled vocabulary) predefined by MIxS (see top of the [schema](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/mixs/schema/mixs.yaml#L28)).

Copilot · 2026-03-11T00:34:00Z

src/docs/slot_specifications.md

+
+### 11.4 Preferred units
+
+Terms (slots) that record a measurement SHOULD specify the preferred unit of measurement for the term (slot) within a LinkmL `annotation` slot sub-attribute called `Preferred_unit:`.


LinkML attribute name: this refers to a LinkML annotation slot attribute, but LinkML uses annotations (plural) and MIxS uses an annotations: map with a Preferred_unit key. Also "LinkmL" capitalization looks accidental; fixing this prevents readers from copying invalid YAML.

Suggested change

Terms (slots) that record a measurement SHOULD specify the preferred unit of measurement for the term (slot) within a LinkmL `annotation` slot sub-attribute called `Preferred_unit:`.

Terms (slots) that record a measurement SHOULD specify the preferred unit of measurement for the term (slot) within a LinkML `annotations` slot attribute using a `Preferred_unit` key.

Copilot · 2026-03-11T00:34:02Z

src/docs/slot_specifications.md

+- Valid example: `library size`.
+- Invalid examples:
+  - `Library size` (capitalisation of first character).
+  - `Library Size` (capitalisation of of all words).


Typo: "capitalisation of of all words" has a duplicated "of".

Suggested change

- `Library Size` (capitalisation of of all words).

- `Library Size` (capitalisation of all words).

Copilot · 2026-03-11T00:34:02Z

src/docs/slot_specifications.md

+
+### 7.1 Minimum number of examples
+
+There MUST have minimum of 1 examples for a term (slot).


Grammar/pluralization: "There MUST have minimum of 1 examples" should be rewritten (e.g., "There MUST be a minimum of 1 example"). As written it's ungrammatical and mixes singular/plural.

Suggested change

There MUST have minimum of 1 examples for a term (slot).

There MUST be a minimum of 1 example for a term (slot).

Copilot · 2026-03-11T00:34:02Z

src/docs/slot_specifications.md

+> The guidance in this section regarding `subset`s may be replaced with the use of `slot-group` in the future.
+
+### 8.1 All core terms must be assigned a subset
+
+All core checklist terms (slot) MUST be assigned to a section (subset).
+
+### 8.2 All extension terms must be assigned the environment subset
+
+A term (slot) defined in an extension (rather than a core checklist term) MUST be assigned to the 'Environment' section (subset).


LinkML terminology mismatch: this section refers to assigning a slot to a "subset", but in the MIxS schema slots use the in_subset attribute (and subsets: defines subset objects). Consider updating wording to explicitly instruct using in_subset on the slot to avoid implementers looking for a non-existent subset slot attribute.

Suggested change

> The guidance in this section regarding `subset`s may be replaced with the use of `slot-group` in the future.

### 8.1 All core terms must be assigned a subset

All core checklist terms (slot) MUST be assigned to a section (subset).

### 8.2 All extension terms must be assigned the environment subset

A term (slot) defined in an extension (rather than a core checklist term) MUST be assigned to the 'Environment' section (subset).

> The guidance in this section currently assumes that term (slot) membership in a section is modelled using the LinkML `in_subset` attribute on the slot, pointing to subset identifiers defined under the schema's top-level `subsets:` section. This mechanism MAY be replaced with the use of `slot_group` in the future.

### 8.1 All core terms must be assigned to a subset via `in_subset`

All core checklist terms (slots) MUST be assigned to a section subset via the slot's `in_subset` attribute, referring to an appropriate subset defined under `subsets:`.

### 8.2 All extension terms must be assigned the environment subset via `in_subset`

A term (slot) defined in an extension (rather than a core checklist term) MUST have its slot `in_subset` attribute include the 'Environment' section subset (as defined under `subsets:`).

Copilot · 2026-03-11T00:34:02Z

src/docs/slot_specifications.md

+  syntax: ^{particulate_matter_name};{float} {unit}$
+```
+
+### 11.4 Preferred units


Section numbering: this heading is labeled "### 11.4" but there is already a previous "### 11.4" above (Specifying units). Renumbering will avoid confusing cross-references/anchors.

Suggested change

### 11.4 Preferred units

### 11.5 Preferred units

Copilot · 2026-03-11T00:34:02Z

src/docs/slot_specifications.md

+Original author or contributors SHOULD be referred to by a stable ID such as an [ORCID](https://orcid.org/), with the persons name included as a comment.
+
+```yaml
+created_by: orcid:0000-1234-1234-1234 # Erika Mustermann


The example for recording the modification author uses created_by, but this section is describing modified_by. This looks like a copy/paste error and could lead to incorrect provenance fields being added to terms.

Suggested change

created_by: orcid:0000-1234-1234-1234 # Erika Mustermann

modified_by: orcid:0000-1234-1234-1234 # Erika Mustermann

turbomam · 2026-03-11T00:46:13Z

I requested Copilot reviews here because I’m helping triage/review MIxS PRs, not because I authored them. If you have the same GitHub permissions and Copilot access, you can do the same on any PR. You’ll know you’re enabled if you can see the Copilot review option in the PR review UI or related actions; if not, you likely need org/repo access and a Copilot seat or feature enablement from the repo or GitHub org admins.

turbomam · 2026-03-11T02:21:23Z

We've requested a GitHub Copilot review on this PR as part of a pass across all open MixS PRs. Copilot catches things like unused imports, resource leaks, and naming inconsistencies — it's a lightweight first pass, not a substitute for human review. No action needed from you unless Copilot flags something you agree with.

jfy133 added 15 commits May 24, 2023 09:02

Create TERM-REQUEST.yml

59364ba

Fix syntax error

84f980a

Update TERM-REQUEST.yml

94a9861

Syncronise with latest LinkML schema

0debbe4

Fix wrong term for extension

7c8c212

Update TERM-REQUEST.yml

b1653a4

Try removing dropdown

e1b76b5

Fix duplicated name

f7cb46c

Try re0adding multi-valuted

8eac2f2

Remove options

ab7f57d

Fix Indenting

0c7b1bb

Hardcode options in multivalued to strings

3231fff

Merge branch 'GenomicsStandardsConsortium:main' into main

f288b54

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

jfy133 added 5 commits August 12, 2025 12:16

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

src/docs/slot_specifications.md Show resolved Hide resolved

jfy133 added 5 commits September 8, 2025 20:47

Last correction from @only1chunts comments

bbbc51f

Merge branch 'main' into docs-slot-specifications

fe34a17

Merge remote-tracking branch 'upstream/main' into docs-slot-specifica…

ad734c4

…tions

Add more examples of useful ontologyies

8f8f754

Remove unused file

c85a24e

Woolly-at-EBI requested changes Sep 9, 2025

View reviewed changes

jfy133 changed the title ~~Documentation: create a specifications document on how to write a MIxS LinkML slot~~ Documentation: MIxS Term (linkML slot) specification documentation Sep 15, 2025

jfy133 added 3 commits September 15, 2025 21:09

Address @Woolly-at-EBI comments, and add footnote markdown extension …

3311dde

…to mkdocs

Add specifications for importing terms from other standards

5c8fc8d

Add specifications for recording authors/contributions and dates of c…

4e43c0a

…reation/updating

jfy133 requested a review from Woolly-at-EBI September 16, 2025 12:13

Woolly-at-EBI approved these changes Sep 16, 2025

View reviewed changes

lschriml reviewed Nov 25, 2025

View reviewed changes

jfy133 and others added 5 commits February 2, 2026 21:18

Update src/docs/slot_specifications.md

d62ceed

Co-authored-by: lschriml <[email protected]>

Apply suggestions from code review

e5d0231

Co-authored-by: lschriml <[email protected]>

A few minor prhasing changes

957202f

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

5e65051

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

First set of changes after review by @lschriml

783710a

turbomam mentioned this pull request Mar 10, 2026

Rebase stale open PRs onto main #1178

Open

turbomam requested a review from Copilot March 11, 2026 00:30

Copilot started reviewing on behalf of turbomam March 11, 2026 00:30 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes


		### 8.2 All extension terms must be assigned the environment subset

		A term (slot) defined in an extension (rather than a core checklist term) MUST be assigned to the 'Environment' section (subset).

		### 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.


		The date in which the term (slot) was updated or modified SHOULD be recorded using the LinkML [`last_updated_on`](https://linkml.io/linkml-model/latest/docs/last_updated_on/) attribute.

		## 16 Importing terms from other standards


		- [Darwin Core (DwC)](https://dwc.tdwg.org/)

		### 16.2 Imported external standards terms requirements


		Minor modifications to the term (slot) structured comment (name) MAY BE made to ensure compliance with MIxS naming conventions.

		## References


		### 11.1 Range options should be valid LinkML types

		See section [4](#4-data-types).

	See section [4](#4-data-types).
	See section [3](#3-data-types).


		A term that requires a specific value syntax or a structured string layout SHOULD use the `structured_pattern` slot attribute, where the pattern components SHOULD be predefined in the `settings:` section of the schema when theoretically could be used more than once.

		A slot MAY use `pattern:` attribute when XYZ <!-- TODO -->.

	A slot MAY use `pattern:` attribute when XYZ <!-- TODO -->.
	> [!NOTE]
	> TBD: The specific conditions under which a slot MAY use the `pattern:` attribute instead of `structured_pattern` are under discussion and will be documented in a future revision of this specification. See the project issue tracker for the latest status.

	\| `dissovled` \| `diss_` \| `diss_hydrogen` \|
	\| `dissolved` \| `diss_` \| `diss_hydrogen` \|

	- An '[enumeration](#145-enumerations)' (i.e., controlled vocabulary') predefined by MIxS (see top of the [schema](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/mixs/schema/mixs.yaml#L28)).
	- An [enumeration](#145-enumerations) (i.e., controlled vocabulary) predefined by MIxS (see top of the [schema](https://github.com/GenomicsStandardsConsortium/mixs/blob/main/src/mixs/schema/mixs.yaml#L28)).


		### 11.4 Preferred units

		Terms (slots) that record a measurement SHOULD specify the preferred unit of measurement for the term (slot) within a LinkmL `annotation` slot sub-attribute called `Preferred_unit:`.

	- `Library Size` (capitalisation of of all words).
	- `Library Size` (capitalisation of all words).


		### 7.1 Minimum number of examples

		There MUST have minimum of 1 examples for a term (slot).

	There MUST have minimum of 1 examples for a term (slot).
	There MUST be a minimum of 1 example for a term (slot).

	created_by: orcid:0000-1234-1234-1234 # Erika Mustermann
	modified_by: orcid:0000-1234-1234-1234 # Erika Mustermann

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!

Woolly-at-EBI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Woolly-at-EBI left a comment

Choose a reason for hiding this comment

Uh oh!

lschriml left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!