Repo structure

Overview

Unlike a task script, a protocol has no code — it’s declarative YAML plus a small identity file. This page covers repo naming, namespace choice, and the file layout a TetraScience-maintained protocol repo follows.

Namespace

Everything in the common namespace should be client-agnostic — the data model doesn’t vary between customers. A protocol whose behavior depends on customer-specific configuration or a vendor tool whose output format varies by installation belongs in client-<name> instead. Self-serve protocols always use private-<org>.

Slug

Situation	Slug template	Example
Vendor-specific instrument model	<vendor>-<model>-raw-to-ids	bruker-sierra-raw-to-ids
Vendor-specific software	<vendor>-<software>-raw-to-ids	mettler-toledo-labx-raw-to-ids
Industry-standard file type	<file-type>-raw-to-ids	fcs-raw-to-ids

Repo naming and layout

Protocol repo name: ts[-client-<client-name>]-protocol-<slug>.

ts[-client-<client-name>]-protocol-<slug>/
  protocol.yml
  manifest.json
  README.md
  e2e_test_configuration.json
  docs/
  images/

File or folder	Description
protocol.yml	See protocol.yml field reference
manifest.json	Identity fields (type, namespace, slug, version, labels, requirements) — see the manifest fields table in protocol.yml field reference
README.md	Customer-facing documentation — see README conventions
e2e_test_configuration.json	See Testing
docs/	Optional. Files linked from README.md for users to download — typically sample input files so users can compare their own files against a known-good example
images/	Optional. Images referenced from README.md; must live in this folder to be resolved

A self-service protocol (scaffolded via ts-cli init protocol) is a bare tree alongside a sibling task-script directory, with only protocol.yml and manifest.json — no README.md, docs/, or e2e_test_configuration.json are required, and repo-name validation is skipped entirely:

protocol/
  protocol.yml
  manifest.json

Either way, there is no Python, no pyproject.toml, no requirements.txt, and no package directory — a protocol is pure declarative configuration.

manifest.json

Field	Required	Notes
type	yes	Must be "protocol"
namespace	yes	common, client-<name>, or private-<org> (self-serve)
slug	yes	See the slug table above
version	yes	vMAJOR.MINOR.PATCH; manifest.json is the source of truth for version
name	no	Display title; conventionally matches the README’s title
description	no	—
labels	no	[{name, value}]; catalog_key, instrument_type, instrument_model, vendor, software, and software_version are reserved names and cannot be used
icon	no	Must be exactly images/icon.png; the file must exist and be ≤ 512000 bytes
include / exclude	no	Glob patterns; exclude wins on conflict
requirements	no	Catalog applicability — populate with registered Tetra Catalog terms; an unregistered term fails the release build
catalog_keys	no	Deprecated in favor of requirements; still accepted

For a self-serve protocol, only type, namespace, slug, and version are required.

Values duplicated between manifest.json and protocol.yml (namespace, slug, version, etc.) must agree — the build only warns, it does not fail, on a mismatch.