SDRF Templates Guide

base                         Infrastructure (identifiers, data files, versioning)     [internal]
  sample-metadata            Shared sample biology (organism, tissue, disease)        [internal]
    technology templates     MS or affinity proteomics columns                        [layer: technology]
    organism templates       Species-specific metadata (human, vertebrates, etc.)     [layer: sample]
    clinical templates       Clinical/oncology metadata                               [layer: sample]
    experiment templates     Technique-specific columns (DIA, crosslinking, etc.)     [layer: experiment]

base (construction artifact - not user-facing)
 ├── sample-metadata (intermediate - sample columns shared by most templates)
 │    ├── ms-proteomics (technology)
 │    │    ├── dia-acquisition (experiment)
 │    │    ├── crosslinking (experiment)
 │    │    ├── immunopeptidomics (experiment)
 │    │    └── single-cell (experiment)
 │    ├── affinity-proteomics (technology)
 │    │    ├── olink (experiment)
 │    │    └── somascan (experiment)
 │    ├── human (sample)
 │    ├── vertebrates (sample)
 │    ├── invertebrates (sample)
 │    ├── plants (sample)
 │    ├── cell-lines (experiment)
 │    ├── clinical-metadata (sample)
 │    │    └── oncology-metadata (sample)
 │    └── (columns: organism, organism part, cell type, disease, biological replicate...)
 └── metaproteomics (sample - MIxS-aligned, excludes sample-metadata when combined)
      ├── human-gut (sample)
      ├── soil (sample)
      └── water (sample)

# single-cell inherits from ms-proteomics >=1.1.0
extends: ms-proteomics@>=1.1.0

# If ms-proteomics is bumped to 1.2.0: single-cell automatically inherits 1.2.0 ✓
# If ms-proteomics is bumped to 2.0.0: single-cell inherits 2.0.0 (review needed)
#   → If incompatible, add upper bound: extends: ms-proteomics@>=1.1.0,<2.0.0

NT={name};AC={accession}

1. Look up the column name in the active YAML template(s)
2. Retrieve the declared list of validators for that column
3. Validate the cell value against each declared validator
4. If no validators are declared, the value is accepted as free text

# =============================================================================
# TEMPLATE METADATA (required)
# =============================================================================
name: human                        # Unique template identifier (used in --template flag)
description: Human SDRF template   # Human-readable description
version: 1.1.0                     # Semantic version (major.minor.patch)

# =============================================================================
# INHERITANCE AND RELATIONSHIPS (optional)
# =============================================================================
extends: sample-metadata@>=1.0.0           # Parent template with version constraint
usable_alone: false                # Can this template be used without others?
layer: sample                      # Layer: base, sample-metadata, technology, sample, experiment

# Mutual exclusivity - templates that cannot be combined with this one
mutually_exclusive_with:
  - vertebrates
  - invertebrates
  - plants

# Required layers - for templates that need specific layer types
requires:
  - layer: technology              # Requires a technology template
  - layer: sample                  # Requires a sample template

# =============================================================================
# TEMPLATE-LEVEL VALIDATORS (optional)
# =============================================================================
validators:
  - validator_name: min_columns
    params:
      min_columns: 12
  - validator_name: trailing_whitespace_validator
    params: {}

# =============================================================================
# COLUMN DEFINITIONS (required)
# =============================================================================
columns:
  - name: characteristics[disease]
    description: Disease state of the sample
    requirement: required          # required | recommended | optional
    type: string                   # string | integer (default: string)
    cardinality: single            # single | multiple (default: single)
    allow_not_applicable: true     # Allow "not applicable" value
    allow_not_available: true      # Allow "not available" value
    allow_pooled: false            # Allow "pooled" value (for replicates)
    validators:
      - validator_name: ontology
        params:
          ontologies:
            - mondo
            - efo
            - doid
            - pato
          error_level: warning     # error | warning
          description: The disease should be a valid ontology term
          examples:
            - normal
            - breast cancer
            - diabetes mellitus

excludes:
  # Strategy 1: Exclude all columns inherited from a named template
  templates:
    - sample-metadata              # Remove all columns that originated from sample-metadata

  # Strategy 2: Exclude columns by prefix category
  categories:
    - characteristics              # Remove all characteristics[...] columns from other templates
    - comment                      # Remove all comment[...] columns from other templates

  # Strategy 3: Exclude specific columns by name
  columns:
    - characteristics[organism]
    - characteristics[disease]
    - characteristics[cell type]

ms-proteomics + human + dia-acquisition + cell-lines
     ↓             ↓           ↓              ↓
 technology    sample    experiment     experiment

sdrf-templates/
└── top-down/
    └── 1.0.0-dev/
        ├── top-down.yaml         # Template schema (required)
        └── top-down.sdrf.tsv     # Example SDRF file (required)

# ===========================================================================
# TEMPLATE METADATA
# ===========================================================================
name: top-down
description: >
  SDRF template for top-down proteomics experiments where intact proteins
  are analyzed without prior enzymatic digestion. Extends ms-proteomics
  with top-down-specific columns for intact mass analysis.
version: 1.0.0-dev
extends: ms-proteomics@>=1.1.0
usable_alone: false
layer: experiment

# ===========================================================================
# COLUMN DEFINITIONS — only columns new or changed from parent
# ===========================================================================
columns:

  # --- New column: protein separation method ---
  - name: comment[protein separation method]
    description: >
      Method used to separate intact proteins before MS analysis
      (e.g., GELFrEE, SEC, RPLC, CZE). Use "not applicable" if no
      separation was performed (direct infusion).
    requirement: recommended
    allow_not_applicable: true
    allow_not_available: true
    validators:
      - validator_name: ontology
        params:
          ontologies:
            - ms
            - pride
          error_level: warning
          description: >
            Protein separation method should be a valid PSI-MS or PRIDE
            ontology term.
          examples:
            - size exclusion chromatography
            - gel electrophoresis
            - capillary zone electrophoresis
            - reversed-phase liquid chromatography
            - not applicable

  # --- New column: intact mass range ---
  - name: comment[precursor mass range]
    description: >
      The mass range of intact protein precursors analyzed, in Daltons.
      Format: "min-max Da" (e.g., "5000-50000 Da").
    requirement: optional
    allow_not_available: true
    validators:
      - validator_name: pattern
        params:
          pattern: ^(\d+-\d+\s*Da|not available)$
          case_sensitive: false
          description: >
            Precursor mass range in format "min-max Da".
          examples:
            - 5000-50000 Da
            - 10000-100000 Da
            - not available

  # --- Override inherited column: make cleavage agent "not applicable" ---
  # In top-down experiments, proteins are not digested, so the cleavage
  # agent column should always be "not applicable". We override the
  # inherited column to make this explicit.
  - name: comment[cleavage agent details]
    description: >
      Cleavage agent is not applicable for top-down experiments where
      intact proteins are analyzed. Use "not applicable".
    requirement: required
    allow_not_applicable: true
    allow_not_available: false
    validators:
      - validator_name: values
        params:
          values:
            - not applicable
          error_level: warning
          description: >
            Top-down experiments analyze intact proteins. Cleavage agent
            should be "not applicable".

# Install or upgrade the validator
pip install sdrf-pipelines

# Validate the example SDRF file with the new template
parse_sdrf validate-sdrf \
  --sdrf_file top-down/1.0.0-dev/top-down.sdrf.tsv \
  --template ms-proteomics \
  --custom_template top-down/1.0.0-dev/top-down.yaml

NT=ms-proteomics;VV=v1.1.0    NT=human;VV=v1.1.0