README.md

README.md is the user-facing document for an IDS in Tetra: a Tetra Data user reads it to understand what the schema covers, how to get their data into it, and how raw fields map to IDS properties. READMEs may also be used with agentic tools, for example to automatically onboard instruments to Tetra, or to automate downstream usage of IDS data. So write with that usage in mind: use clear prose plus structured, explicitly labeled content rather than free-form notes.

The structure described below should be used for all common and client- namespace IDS READMEs. It is also recommended for self-service (private- namespace) IDS READMEs.

Note

Use the section headings below verbatim — don’t rename or renumber them. An empty section gets filled in or removed before v1, not renamed.

Structure

Section order, top to bottom:

Section	Required?
## Version	yes
## Table of Contents	yes
## Summary	yes
## Getting Started	yes (holds subsections below)
### Related Protocols and Agents	yes
### Supported File Formats	yes
### Supported Techniques	required if more than one technique/mode; otherwise omit
### Export Settings	optional
## Sample Inputs & Outputs	optional
## Schema Design and Mapping	yes (holds subsections below)
### Assumptions	yes
### Limitations	yes
### Schema Design Details	optional — see below
### Raw to IDS Mapping	yes — generated, see ### Raw to IDS Mapping
## Using the Data	optional
## Changelog	yes, always last — see Changelog and versioning

Title

# <Name> Tetra Data Schema — derive <Name> from the artifact naming @idsType/slug; avoid duplicating the word “Schema” (e.g. don’t write “Plate Reader Schema Tetra Data Schema”).

## Version

Just the version, v prefix: v1.0.0. Must match @idsVersion in manifest.json.

## Table of Contents

Links to every ##/### heading in the document (excluding Version and the Table of Contents itself), in document order, with GitHub-style anchors (lowercase, spaces → hyphens, punctuation stripped). Regenerate the Table of Contents whenever you edit a heading — a stale entry or broken anchor is worse than none. (VS Code’s “Markdown All in One” extension can auto-generate/update this.)

## Summary

One or two sentences: what instrument/software/vendor this models, what type of data (e.g. “plate reader measurements”, “chromatography results”), and the key use case. Don’t document how the instrument works here — that’s out of scope for a schema README.

Example: “This Tetra Data schema is designed to model the data produced by Mettler Toledo, LabX software.”

## Getting Started

Goes right after Summary — a user wants to know how to start ingesting data before they care about modeling details. Nothing here should go into schema/mapping detail; that belongs under “Schema Design and Mapping”.

### Related Protocols and Agents

Bullet list of compatible Protocol/Agent versions for this IDS version. No need to name the task script.

The compatible agent/protocol bundles are:

- Tetra Empower Agent v5.1.0 & Protocol 7.0.1 (recommended)
- Tetra Empower Agent v5.1.0 & Protocol 7.0.0

If only one bundle is relevant, a single “Use protocol common/<slug>” line is fine.

### Supported File Formats

List every accepted input format and how to obtain it — including any easy-to-miss precondition (an extra module or license, a required export option, report template, or format setting).

- `.json` files produced by TetraScience Mettler Toledo LabX Agent
- `.csv` files exported from the Mettler Toledo LabX Software

If there are multiple paths with tradeoffs (e.g. agent-collected vs. manually exported), spell out each option and its limitations — don’t just list formats.

### Export Settings

Optional. Step-by-step export instructions when the format alone isn’t enough to reproduce a working export (screenshots of the software UI where useful).

### Supported Techniques

Required whenever the instrument/software supports more than one technique or mode; omit if there’s only one. Use a matrix table when coverage varies by model:

|  | Instrument A | Instrument B |
| --- | --- | --- |
| Mode A | Yes | No |
| Mode B | Not possible | Yes |

## Sample Inputs & Outputs

Optional. Link to a docs/ folder if you want users to see example raw input and IDS output files.

Note

Files in docs/ are visible to users — sanitize them before they land there. If you’re not sure whether to include sample files, put them in example-files/ instead (internal-only) and document them in CONTRIBUTING.md.

## Schema Design and Mapping

Modeling detail goes here, not in Getting Started.

### Assumptions

Every assumption made when parsing/mapping the raw data.

- Assume there can never be more than 1 experiment run per file
- Assume raw files always have greater than 0 rows

### Limitations

Every known limitation of the IDS or its parser.

- Supports only certain measuring modes for certain instruments
- Chooses to support X because of reason Y

### Schema Design Details

A complement to the mapping table, not a restatement of it — add detail only where the mapping isn’t field-to-field obvious. Skip this subsection (or keep it terse) when mapping a JSON/XML field or a CSV/Excel table column straight across to an IDS field. Write it out when: the value is buried in unstructured text and needs a locating description; the IDS value is derived from multiple raw fields via business logic; or there’s a non-obvious dedup/identity rule (e.g. how you decide two result blocks belong to the same samples[*] entry). Screenshots, small code/text excerpts illustrating the raw pattern, and short worked examples are appropriate here.

### Raw to IDS Mapping

Generated — never hand-edit the table in README.md. It’s produced from mapping_table.json via pytest --snapshot-update, using ts-ids-core’s mapping table tools. Edit mapping_table.json and regenerate instead.

• New IDS repo, no mapping_table.json yet: bootstrap with ts-ids mapping-table convert-readme if a hand-written table already exists, otherwise let pytest --snapshot-update create it fresh from schema.json.

• If a schema field is never populated by the task script, set "visible": false in mapping_table.json rather than removing it — keeps the table in sync with the schema without cluttering the user-facing view.

• Array indices: use [*] when any number of elements can occur; use [0], [1], … when the index is meaningful or the array is capped at one element.

• A RawValueUnit field must list all three subfields (raw_value, value, unit) in the table, not a single collapsed row.

• Don’t hand-format the table with padding spaces — it breaks diffs when a longer property name changes column widths; let the generator produce it as-is.

• Column set is normally IDS property name | Raw file location | Notes; add “Raw File Line Number” or “Raw File Sheet Name” columns if the raw format makes them useful for tracing.

• Property naming follows field naming.

## Using the Data

Optional. A short example of how a user might use the resulting Tetra Data (e.g. “you can calculate the average sensor reading for a tag over a time range to detect anomalies”).

Changelog and versioning

The ## Changelog section is always last — a summary of what changed in every version.

Changelog authoring rules

• Descending order — start from the newest version.

• Each version is a ### subheader: ### v2.0.0.

• Capitalize the first letter of each bullet; do not end the subject line with a period.

• Imperative mood — “Add results[*].experiment_id”, not “Added” or “Adds”.

• Use Add / Update / Remove for field changes, and order the bullets so all Adds come first, then Updates, then Removes.

• When using Update, state clearly what changed from and to.

• Give a reason for the change — especially for breaking changes (Update, Remove).

• If a whole new object or array of objects is introduced, list just the parent field — you don’t need to enumerate every sub-field.

• Separate field changes introduced by ts-ids-core/ts-ids-components (unrelated to the specific business need) from business-driven changes, so the business-relevant part is easy to spot.

• List all the differences between versions — don’t summarize away a change because it seems minor.

• ts-ids schema-diff changelog can generate a first draft of the field-level differences between two schemas as a Markdown list; edit its output into changelog entries following the rules above rather than pasting it verbatim.

## Changelog

### v2.0.0

- Support v2.0.1 Agent + v1.1.1 Protocol
- Schema changes:
  - Add `results[*].experiment_id` to link the result to experiment ID
  - Update `methods[].method_id` to `methods[].id` because the prefix is repeated
  - Remove `related_files[*].random` because this field is not allowed in `related_files`

### v1.0.0

- Initial version

A doc-only release (task script or protocol fixed a bug, IDS itself unchanged) still gets an entry — list the new agent/protocol compatibility and note “no IDS changes.”

Version-bump situations

Which sections need updating depends on the IDS/task-script/protocol relationship for this bump.

Situation 1 — 1:1:1, all three bump together. Likely when: refactoring IDS design, adding new modality support, moving to new shared components.

Current:  IDS v1.0.0 / Task Script v1.0.0 / Protocol v1.0.0
Updating: IDS v2.0.0 / Task Script v2.0.0 / Protocol v2.0.0

Update “Related Protocols and Agents” to the new recommended Protocol version; remove any (supported from Protocol vX.X.X) qualifiers — the new Protocol version supersedes them; update the rest of the README with the changes introduced in this version.

Situation 2 — 1:1:1, task script + protocol bump, IDS unchanged. Likely when: fixing a bug, refactoring code logic, or (less commonly) adding modality support without touching the IDS.

Current:  IDS v1.0.0 / Task Script v1.0.0 / Protocol v1.0.0
Updating: IDS v1.0.0 / Task Script v1.1.0 / Protocol v1.1.0

Update “Related Protocols and Agents” to the new recommended Protocol version; if modality support changed, update the modality/technique table to add (supported from Protocol vX.X.X).

Situation 3 — 1:many, one IDS shared by more than one task script. Likely when: updating an IDS and its Task Script/Protocol for one instrument, while another Task Script/Protocol also targets this IDS and isn’t being touched right now.

Current:  IDS v1.0.0 / Task Script A v1.0.0 / Protocol A v1.0.0 / Task Script B v1.0.0 / Protocol B v1.0.0
Updating: IDS v2.0.0 / Task Script A v2.0.0 / Protocol A v2.0.0 / Task Script B (untouched) / Protocol B (untouched)

For Task Script A / Protocol A: follow Situation 1. For Task Script B / Protocol B: update “Getting Started” to point users of Protocol B at IDS v1.0.0 specifically; remove any documentation for Task Script B / Protocol B from the rest of the README; hide the mapping table’s column for Protocol B if the tooling supports it, rather than deleting it.

Deprecation banners

Placed directly below the title — top of the file, before any other content.

Superseded by another artifact:

> ⚠️ WARNING
>
> This IDS is superseded by **`<IDS namespace>/<IDS slug>`**

Compatibility limit (not just Agent version — adapt the wording to whatever the constraint is):

> ⚠️ WARNING
>
> This version of the IDS only supports <Agent Name> vX and older. For <Agent Name> vY and newer,
> please use a newer version.

Fully deprecated version:

> ⚠️ WARNING
>
> This version of the IDS is no longer supported. Please use a newer version.