Protocols

Versioned, forkable standard operating procedures with structured equipment and materials tracking.

What is a protocol?

Protocols (also called procedures or SOPs) are detailed instructions for carrying out a specific laboratory or computational procedure. On Libre Biotech, protocols are versioned documents that combine step-by-step instructions with structured metadata: free-text sections, catalog-linked equipment and materials, and citable references.

Protocols serve two purposes:

• Reproducibility — Every process references the exact protocol version that was followed, including the equipment types and materials required
• Community knowledge — Published protocols can be forked, improved, and reviewed by others

Browsing protocols

The protocol library is accessible from Protocols in the main navigation, or from the public-facing Explore page (for public protocols). Protocols are organised by category:

• Sample Preparation
• Measurement & QC
• Data Transformation
• Sequencing
• Management

Creating a protocol

Navigate to Protocols → New Protocol. The form is laid out in sections, all on a single page:

1. Procedure details — Title (required), description, category, URL, visibility, and license (default CC-BY-4.0)
2. Initial version — Version number (default 1.0), effective date, and changelog
3. Protocol sections — Four optional free-text sections: Safety & Hazards, Preparation Notes, Timing, and Completion Notes (see below)
4. Equipment from Catalog — Dynamic rows for generic equipment types with specifications and notes
5. Materials from Catalog — Dynamic rows with cascading type → product selects, quantity, unit, and notes
6. References — Citations with optional DOI, URL, and type (paper, manual, protocol, book, or website)
7. Procedure steps — Numbered instructions; add, remove, and reorder as needed

All dynamic sections (equipment, materials, references, steps) support adding and removing rows with + and trash buttons. Click Create Procedure when finished.

Structured sections

Protocols support four optional free-text sections that appear alongside the procedure steps. These sections complement the structured Equipment & Materials Catalog links — use the catalog for structured, cross-referenceable equipment and material data, and the text sections for narrative detail. All sections support Markdown formatting.

Pre-step sections

These appear above the procedure steps, providing context a researcher needs before starting:

Section	Purpose	Example content
Safety & Hazards	PPE requirements, chemical hazards, disposal instructions	“CT Conversion Reagent is corrosive. Wear gloves and eye protection. Dispose via chemical waste.”
Preparation Notes	Narrative detail about reagent preparation, equipment setup, sample requirements, or any other pre-procedure context that doesn’t fit in the catalog’s structured fields	Buffer reconstitution steps, instrument calibration, input sample specs (“200–500 ng gDNA in ≤20 µL water, OD 260/280 ≥ 1.8”)
Timing	Estimated duration, time-sensitive steps, scheduling notes	“Total time: ~3.5 hours. Desulphonation incubation: 15–20 min (do not exceed 20 min).”

Post-step section

Section	Purpose	Example content
Completion Notes	Expected results, storage conditions, troubleshooting tips, and any other post-procedure information	Use Markdown headings to organise, e.g. ## Expected Results, ## Storage, ## Troubleshooting

Equipment & Materials from Catalog

Protocols link to the shared Equipment & Materials Catalog for structured, cross-referenceable tracking. Two catalog sections appear on the protocol form:

Equipment

Click + Add Equipment to add a row. Select a generic equipment type from the dropdown (e.g., “Microcentrifuge”), then optionally add specifications (e.g., “≥10,000 × g”) and notes. Add as many rows as needed; remove any row with the trash button.

Materials

Click + Add Material to add a row. Each row has:

1. Material type — Select a generic type (e.g., “Bisulfite conversion kit”)
2. Product — A cascading select that automatically filters to show only products registered under the chosen type. Select a specific product (e.g., “EZ DNA Methylation-Gold Kit (Zymo Research) #D5005”) or leave as “generic (any)” if the protocol is vendor-independent
3. Quantity and Unit — How much is needed (e.g., “1” / “kit”)
4. Notes — Variant details, size constraints, or other context (e.g., “1.5 mL” for a microcentrifuge tube, “Aerosol-resistant filter tips” for pipette tips)
5. Alternative products — Click + Alternative beneath a material row to add interchangeable products. For example, a bisulfite conversion protocol that works with either the 50-reaction kit (D5005) or the 200-reaction kit (D5006) would list D5005 as the primary product and D5006 as an alternative with a note like “Larger pack size (200 rxn)”. Each alternative has its own product select (filtered to the same type) and an optional note

How catalog items are displayed

On the protocol view page, equipment and materials appear as collapsible cards:

• Equipment — Each item shows the type name as a link to the catalog type page, with specifications and notes
• Materials (product specified) — The product name is shown as the primary link (to the product detail page), with vendor and catalog number. The generic type appears as a small badge for context
• Materials (generic only) — The type name is shown as the primary link (to the catalog type page), with the category as a badge
• Alternative products — Listed beneath the primary product as an “Alternatives” sub-list, each linking to its own product detail page with any notes shown

This enables cross-protocol queries like “show me all protocols that require a microcentrifuge.” See the full catalog documentation for details on the type/product hierarchy, kit components, SDS links, and process-level tracking.

References

Each protocol version can include structured references to papers, manuals, other protocols, books, or websites. Each reference has:

• Citation — Free-text citation (required)
• DOI — Digital Object Identifier, automatically linked to https://doi.org/...
• URL — Direct link to the resource, or upload a PDF (max 10 MB) which is stored locally on the server. Uploaded files take precedence over the URL field
• Type — One of: paper, manual, protocol, book, or website

References are displayed as a numbered list on the protocol page, with clickable DOI and Link badges. Uploaded PDFs are served directly from the platform, ensuring references remain accessible even if the original vendor URL changes.

Versioning

Protocols are versioned. When you update a protocol, a new version is created while previous versions remain accessible. This ensures that processes linked to older versions still reference the exact instructions that were followed.

1. Navigate to the protocol page
2. Click Edit (New Version)
3. Make your changes — the edit form is pre-filled from the previous version:
   • All four protocol sections (Safety, Preparation Notes, Timing, Completion Notes)
   • Equipment rows with selected types, specifications, and notes
   • Material rows with selected types, products (auto-restored in the cascading select), quantities, units, notes, and any alternative products
   • References and procedure steps
4. Add a changelog note describing what changed (required)
5. Click Create New Version

Each version is immutable once created. Catalog links are stored per-version, so adding a new equipment requirement in version 2.0 does not alter version 1.0.

Forking

Forking creates a copy of a protocol under your name, which you can then modify independently. This is how the community improves protocols collaboratively.

1. Navigate to the protocol you want to fork
2. Click Fork
3. The forked protocol appears in your protocol list with a link back to the original
4. Edit and version it as your own

The fork tree (visible on the protocol page) shows all forks and their lineage.

Community features

• Star — Mark protocols you use frequently for quick access
• Suggest improvements — Propose changes to protocols you don't own
• Review suggestions — Protocol owners can accept or reject improvement suggestions

Linking protocols to processes

When creating or editing a process, select a protocol from the library. The process records which protocol version was used, creating a traceable link between the instructions and the actual work performed. At the process level, you can additionally record the specific equipment products and material products used (with lot numbers and expiry dates), complementing the generic type requirements defined in the protocol.

Schema reference

For API consumers and self-hosted deployments. Describes the public API response shape and the underlying relational model. See the API Reference for endpoints and authentication.

Public API response

GET /api/v1/protocols — list endpoint; returns an array of abbreviated rows in data[]:

{
  "data": [
    {
      "id": 12,
      "title": "ZymoBIOMICS DNA Miniprep",
      "description": "...",
      "category": "sample_prep",
      "star_count": 3,
      "fork_count": 1,
      "created_at": "2026-03-10 14:22:05"
    }
  ],
  "meta": { "total": 47, "page": 1, "per_page": 20 }
}

GET /api/v1/protocol/{id} — detail endpoint; returns the full procedures row joined with the latest version and its steps. Only visibility = 'public' rows are returned (otherwise 404).

{
  "data": {
    "id": 12,
    "title": "ZymoBIOMICS DNA Miniprep",
    "description": "...",
    "category": "sample_prep",
    "parser_engine": null,
    "visibility": "public",
    "license": "CC-BY-4.0",
    "owner_group_id": 1,
    "created_by": 4,
    "forked_from_id": null,
    "fork_count": 1,
    "star_count": 3,
    "created_at": "2026-03-10 14:22:05",
    "author_name": "Jane Doe",
    "current_version": {
      "id": 15,
      "procedure_id": 12,
      "version_number": "1.0",
      "person_id": 4,
      "effective_date": "2026-03-10 14:22:05",
      "change_log": "Initial version",
      "safety_text": "...",
      "preparation_notes_text": "...",
      "timing_text": "...",
      "completion_notes_text": "...",
      "steps": [
        { "step_number": 1, "content": "Add 750 µL of BashingBead Buffer..." }
      ],
      "parameters": [
        {
          "id": 7,
          "name": "annealing_temperature",
          "description": "Per-cycle annealing temperature",
          "data_type": "number",
          "required": true,
          "display_order": 0,
          "default_value": "58",
          "unit_term": { "label": "degree celsius", "curie": "UO:0000027" }
        }
      ]
    }
  }
}

Equipment, materials, material alternatives, and references are not currently included in the public API response. Use the underlying tables (below) or a self-hosted deployment if you need them. Protocol parameters are included so external consumers can see what runtime inputs the protocol declares.

Data model

A protocol spans seven tables. Foreign keys cascade on delete from procedures → procedure_versions → the per-version tables.

procedures — the protocol header

Column	Type	Notes
id	INT PK	AUTO_INCREMENT
title	VARCHAR(255) NOT NULL
description	TEXT	Long-form summary, rendered above the version sections
category	VARCHAR(100)	See category values
parser_engine	VARCHAR(50)	Auto-parser for instrument output. NULL = manual entry. Known: fragment_analyzer
visibility	ENUM	private | group | public. Default private
license	VARCHAR(100)	SPDX identifier. Form default is CC-BY-4.0
url	VARCHAR	Optional external link
owner_group_id	INT FK	→ groups.id, ON DELETE SET NULL
created_by	INT FK	→ users.id, ON DELETE SET NULL
forked_from_id	INT FK	→ procedures.id. Self-reference for fork lineage
fork_count	INT UNSIGNED	Denormalised counter, default 0
star_count	INT UNSIGNED	Denormalised counter, default 0
created_at	TIMESTAMP	CURRENT_TIMESTAMP

procedure_versions — immutable versions

Column	Type	Notes
id	INT PK
procedure_id	INT FK	→ procedures.id, ON DELETE CASCADE
version_number	VARCHAR(20) NOT NULL	Free-form label: "1.0", "2.1", "2024-05", etc.
person_id	INT FK	→ people.id (version author)
is_locked	TINYINT(1) NOT NULL	Default 0. Flips to 1 the moment any processes row references this version — the run freezes the protocol’s contents as the historical record. Once locked, steps, parameters, equipment, materials, and default_annotations for this version are immutable; to change them, cut a new version. If an in-progress process needs the new version, the web UI offers atomic fork-and-retarget (creates a new version and repoints the process in one transaction, allowed only while the process has zero assays).
effective_date	DATETIME NOT NULL	Default CURRENT_TIMESTAMP
change_log	TEXT	Free-text changelog entry
safety_text	TEXT	Structured narrative section — “Safety & Hazards” in the UI (Markdown)
preparation_notes_text	TEXT	Structured narrative section — “Preparation Notes” in the UI
timing_text	TEXT	Structured narrative section — “Timing” in the UI
completion_notes_text	TEXT	Post-procedure notes (“Completion Notes”: expected results, storage, troubleshooting)
measurement_type_term_id	INT FK NULL	→ ontology_terms.id, ON DELETE SET NULL. ISA Study Assay Measurement Type (typically an OBI term, e.g. OBI:0000424 “transcription profiling assay”). Together with technology_type_term_id, declares which ISA Assay Table this procedure version contributes to at export time. Null for sample-prep / non-measurement procedures.
technology_type_term_id	INT FK NULL	→ ontology_terms.id, ON DELETE SET NULL. ISA Study Assay Technology Type (e.g. Sanger sequencing, mass spectrometry, NGS).

Referenced from processes.procedure_version_id — a processes row records which procedure version was executed. The moment any processes row points at a version, is_locked flips to 1. Exporter use: the ISA-Tab exporter derives a Study’s ISA Assay Tables by taking DISTINCT (measurement_type_term_id, technology_type_term_id) across all procedure_versions used by that Study’s processes.

procedure_steps — ordered instructions

Column	Type	Notes
id	INT PK
procedure_version_id	INT FK	→ procedure_versions.id, ON DELETE CASCADE
step_number	INT NOT NULL	1-based order within the version
content	TEXT NOT NULL	Markdown-allowed instruction body

procedure_version_equipment — catalog equipment links

Column	Type	Notes
id	INT PK
procedure_version_id	INT FK	→ procedure_versions.id, CASCADE
equipment_type_id	INT FK	→ equipment_types.id, CASCADE
specifications	TEXT	e.g. “≥10,000 × g”
notes	TEXT

procedure_version_materials — catalog material links

Column	Type	Notes
id	INT PK
procedure_version_id	INT FK	→ procedure_versions.id, CASCADE
material_type_id	INT FK NOT NULL	→ material_types.id, CASCADE. Generic type (required)
material_product_id	INT FK NULL	→ material_products.id, ON DELETE SET NULL. NULL = “any product of this type”
quantity	VARCHAR(100)	Free-text (supports ranges: “1–5”)
unit	VARCHAR(50)	e.g. µL, kit, mL
notes	TEXT	Variant details, substitutions, etc.

procedure_version_material_alternatives — interchangeable products

Column	Type	Notes
id	INT PK
version_material_id	INT FK NOT NULL	→ procedure_version_materials.id, CASCADE
material_product_id	INT FK NOT NULL	→ material_products.id, CASCADE
notes	VARCHAR(255)

Unique on (version_material_id, material_product_id).

procedure_references — citations

Column	Type	Notes
id	INT PK
procedure_version_id	INT FK NOT NULL	→ procedure_versions.id, CASCADE
citation	TEXT NOT NULL	Free-text citation
doi	VARCHAR(255)	Auto-linked to https://doi.org/{doi}
url	VARCHAR(512)	Direct link, or an uploaded PDF stored locally
ref_type	ENUM	manual | paper | protocol | book | website. Default paper

protocol_parameters — runtime parameter definitions

Declared inputs whose per-run values are captured against the resulting assays (e.g. annealing temperature, cycle count). Exported as ISA-Tab Parameter Value[name] columns on the Assay Table.

Column	Type	Notes
id	INT PK
procedure_version_id	INT FK NOT NULL	→ procedure_versions.id, CASCADE
name	VARCHAR(255) NOT NULL	e.g. annealing_temperature
description	TEXT
data_type	ENUM	text | number | date | ontology_term | boolean. Default text
required	TINYINT(1)	Default 0
default_value	VARCHAR(255)	Pre-fill for the capture UI
display_order	SMALLINT	Column ordering in the capture UI and ISA-Tab export
unit_term_id	INT FK	→ ontology_terms.id, ON DELETE SET NULL. Typically a UO (Units of Measurement) term
term_id	INT FK	→ ontology_terms.id. Optional semantic annotation of the parameter itself
parameter_type_term_id	INT FK	→ ontology_terms.id. Optional typing term

Runtime values per assay live in assay_parameter_values(assay_id, parameter_id, value, value_term_id) with UNIQUE(assay_id, parameter_id).

Enumerated values

Field	Values
procedures.visibility	private, group, public
procedures.category	sample_prep, measurement, data_transformation, sequencing, management, other. VARCHAR — not DB-enforced; these are the UI-labelled values.
procedures.parser_engine	NULL (manual entry) or fragment_analyzer. VARCHAR — additional engines may exist in extensions.
procedure_references.ref_type	manual, paper, protocol, book, website
protocol_parameters.data_type	text, number, date, ontology_term, boolean