Study Metadata & MIxS

MIxS — Minimum Information about any Sequence — is the Genomic Standards Consortium’s family of checklists that define the minimum contextual metadata a sequence needs to be reusable. A read file without a collection date, a location and an environmental context is data nobody else can interpret.

ENA implements the checklists as numbered specifications (ERC0000nn). SeqDesk ships the ENA catalog offline, presents it as an Environment Type picker when you create a study, and stores your answers per sample.

Choosing an environment type

The picker is driven by the checklist registry (GET /api/mixs-checklists), so it shows whatever your installation currently has available rather than a fixed list. On a stock install that is all seventeen shipped checklists.

Thirteen of them are the GSC MIxS environment packages and have a canonical short id in SeqDesk:

The remaining four have no slug and are stored by accession:

What the numbers mean in practice

GSC MIxS water asks for 130 fields. Nine are mandatory; the other 121 are optional and exist so that a study can be exhaustively described, not so that every study must be.

The Metadata Fields panel that appears once you pick an environment lets you choose which optional fields to collect. Mandatory fields are always included and cannot be switched off. Everything you enable becomes a column in the sample metadata table, so a careless selection turns a 24-sample study into a 24 × 130 grid nobody will finish.

A reasonable default is: take the mandatory set, then add the handful of fields your analysis or your funder actually needs.

Example — the ten mandatory fields of GSC MIxS soil

Where metadata is stored

How writes merge

Who you are changes how a metadata save behaves:

• A facility admin writing per-sample metadata replaces checklistData with exactly what was submitted.
• A researcher’s write is merged field-by-field, and only for the fields the questionnaire currently exposes. A partial post, or one made after an admin shrank the questionnaire, will not wipe answers you captured earlier. Clearing a value therefore means submitting it empty — omitting it leaves the old value in place.

The same asymmetry applies to studyMetadata on PUT /api/studies/[id].

Version pinning

The checklist catalog is not frozen. It ships as JSON under data/field-templates/mixs-full/ and can be refreshed from a remote registry, at which point the active version number increases.

To stop a refresh from retroactively changing a study’s fields:

1. When a study is created with a checklist, SeqDesk records the currently active registry version in Study.mixsVersion.
2. Before an update is applied, the outgoing configuration is snapshotted under its version number.
3. Resolving a checklist for a study tries, in order: the snapshot for the pinned version, then the active checklists, then checklists marked deprecated, then the committed baseline files.

The last 5 versions are retained as snapshots. A study pinned to something older falls through to the active or baseline definition, which may differ from what it was authored against.

Changing the checklist afterwards

PUT /api/studies/[id] accepts checklistType, so the environment type can be changed at any time — including after submission, which the API does not block.

It is almost always the wrong thing to do. The answers already in checklistData are keyed by field name; switching from soil to water leaves soil-only answers orphaned and water-only mandatory fields empty, with no warning and no migration. If you must change it, expect to re-enter the per-sample metadata.

What ENA checks

Before a submission is accepted:

• The study needs a non-empty title, and a description is expected.
• Every sample needs a valid NCBI taxId — see Organism & Taxonomy.
• The mandatory fields of the selected checklist must be filled for every sample.
• Values must satisfy the checklist’s own type and unit constraints — ISO dates, decimal degrees for latitude and longitude, and so on.

SeqDesk’s own wizard is more forgiving than ENA: missing required per-sample values are raised as warnings you can dismiss, not as hard errors. That is deliberate — you can create the study and complete metadata later — but it means a study can look finished and still fail at ENA. The Preparing a Submission surface runs the real checks.

Customising the study form

Facility admins can add institution-specific study-level and per-sample fields through the Study Form Builder. Study fields are normalised into two fixed sections — Study Information and Metadata — plus an Additional Details bucket for ungrouped fields, in the same way order fields are.

With the dynamic-studies module enabled, each study carries its own questionnaire instead of sharing the global one.

Troubleshooting

Next

• Study Workflow — marking a study ready and getting it registered.
• Samples & Metadata — the same checklist catalog seen from the order side.