MIxS: Minimum Information about any (X) Sequence

This repository contains the source material for the Genomic Standards Consortium (GSC) Minimum Information about any (X) Sequence (MIxS) standard.

MIxS, or the Minimum Information about any (X) Sequence is a standard for describing the contextual information about the sampling and sequencing of any genomic sequence. The standard has Terms that describe characteristics of a sample that addresses:

• What is the source of the sequence?
• In what kind of environment was the sample collected?
• What methods were utilized to process the sample?

Following the release of MIxS v6.0, subsequent releases (e.g. MIxS 6.1) are represented in and maintained using the LinkML framework. LinkML uses YAML to define schemas. The user-focused/developer-focused sections of the repository structure provide details on where to find these YAML files that are defining the standard.

The MIxS standards are found at: https://genomicsstandardsconsortium.github.io/mixs/

Terms The individual metadata terms are provided in the table: here. These Terms are attributes or properties that describe samples and their sequence-associated metadata. Broadly, MIxS metadata Terms are represented in genomic Checklists, environmental Extensions, and Combinations (of Checklists and Extensions).

Checklists Checklists include the required, recommended and optional metadata fields (Terms) for a specific type of genomic sequence (e.g. genome, metagenome, microbiome, marker gene, MAG or single cell genome). The MIGS genomic sequences checklist, for example, supports taxa or subcellular structure specific checklists (Eukaryotes, Bacteria, Viruses, Organelle, Plants).

Extensions Extensions include Terms that describe specific environments from which a sample was collected. For example, the Agriculture Extension (MIxS-Ag) includes terms to describe agricultural environments.

Combinations MIxS Checklists and Extensions are designed to be modular, supporting mix and match combinations of any genomic checklist with terms from any environmental extension, to create MIxS Combinations. For example, a Combination of the MIMS Checklist and Agriculture Extension, called MIMSAgriculture.

Repository Structure

Below are descriptions for the various user-facing directories in this repository.

• examples/ - examples of different kinds of data files in different data formats in different (JSON, YAML) containing data conformant with MIxS standard
• mixs-templates/ - MIxS schema metadata collection templates in the Excel spreadsheet (.xlsx) format. These templates can be utilized for organizing a project's metadata in prepartion for submission to a sequence data archive.
• project/ - artifacts autogenerated by the suite of generators in the linkml library. Artifacts include JSON-LD, OWL, JSON Schema, spreadsheet, etc. representations of the schema
• src/
  • src/data/examples/ - valid and invalid data examples
  • The folder structure (valid and invalid folders), and the corresponding YAML data examples in this directory need to follow guidelines in accordance with the linkml-run-examples testing framework
  • src/mixs/
    • src/mixs/schema/
      • src/mixs/schema/mixs.yaml - LinkML YAML schema representing the MIxS standard
  • src/docs - markdown files that can be converted to HTML and included in the web documentation pages

Local setup

To build and work with the schema locally:

1. Clone this repository:

   git clone https://github.com/GenomicsStandardsConsortium/mixs.git
   cd mixs

2. Use Python 3.13. That is the version CI runs and the one MIxS is developed against. Older versions back to 3.10 still satisfy the dependency constraints, but they are not tested; 3.10 reaches end of life in October 2026. Some dependencies do not yet resolve on 3.14. If you do not have 3.13 installed, install it first (for example with pyenv or Homebrew), then point Poetry at it:

   poetry env use python3.13

3. Install the project and its dependencies:

   poetry install

That gives you the environment used by the make targets and the scripts in src/scripts/. For comparing two versions of the schema, see src/docs/SCHEMA_DIFFING.md.

Developer Documentation

Note: Developer documention is specifically included here for the use of members of the GSC's CIG and TWG committees.

Prerequisites

Building and testing MIxS locally requires these tools on your PATH:

• Python 3.13 and Poetry for the Python dependencies. make install runs poetry install --all-extras.
• yq v4, the Go implementation by mikefarah. The build uses yq extensively to transform the schema (the contrib/ pipeline and the TSV round-trip test). This is not the Python yq (pip install yq, the kislyuk wrapper); the two have incompatible syntax, and the Python one causes build errors. Install with brew install yq (macOS) or see the yq install docs.
• make and bash.

npm/node are needed only for the experimental make create-data-harmonizer target, not for the normal build. As of this writing, CI does not install yq itself; it relies on the yq v4 that ships preinstalled on the GitHub ubuntu-latest runner. That is an assumption about the current runner image, not a guarantee: if a future image drops or changes yq, the workflows will need to install a pinned version (see #1242).

Details

Use the `make` command to generate project artefacts:

• make all: make everything
• make deploy: deploys site

Documentation about the contents of the developer-focussed folders/directories in this repository.

• assets/ - files consumed by, or generated by maintenance scripts in src/scripts
• src/
  • src/mixs/
    • src/mixs/datamodel/ - Python dataclasses artifact generated by running the LinkML Python generator on MIxS schema file
    • src/mixs/schema/
      • src/mixs/schema/mixs.yaml - LinkML YAML schema representing the MIxS standard
  • src/doc-templates/ - jinja2 files that are responsible for the customization of layout and content of web documentation pages
  • src/scripts - Python scripts for specific discovery/exploration/inference based on the MIxS YAML schema
• tests/ - test data files
• project-generator-config.yaml - configuration file specifying the arguments passed to the LinkML project generator
• Makefile - Makefile containing pre-defined linkml-project-cookiecutter targets/rules
• contrib.Makefile - file that can be modified to extend pre-defined rules in Makefile

LinkML:

The MIxS utilizes LinkML, see: linkml-project-cookiecutter.