> For the complete documentation index, see [llms.txt](https://docs.omics.ai/products/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omics.ai/products/workbench/instruments/adding-sample-metadata.md).

# Adding sample metadata

Sample metadata (pedigrees, phenotypes, and custom attributes) is added from the storage account's samples page with the **Add Metadata** dialog. You can upload individual files, or add metadata for many samples at once with a single `.zip` archive.

{% hint style="info" %}
Adding metadata requires the **Manage Samples** capability.
{% endhint %}

## What you can upload

The file's name and extension decide how it's read:

| File                            | Read as                                                                                                                                |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `*.ped`                         | A pedigree. See [Family Based Analysis with Pedigree Information](/products/workbench/instruments/adding-pedigrees.md) for the format. |
| Any other `*.json` or `*.jsonl` | A phenopacket (phenotype terms and other clinical metadata).                                                                           |
| `*.attributes.json`             | Custom attributes, keyed by sample ID.                                                                                                 |
| `*.zip`                         | An archive containing any of the files above.                                                                                          |

Click **Download Templates** in the dialog for example files.

### Custom attributes

A custom attributes file maps each sample ID to the attributes you want to store for it. Values can be text, numbers, lists, or nested objects. For example, `lab.attributes.json`:

```json
{
  "HG002": { "kit_lot": "A7-2291" }
}
```

The sample must already exist in Workbench. Custom attributes appear on the [sample details page](/products/workbench/instruments/sample-details.md#custom-attributes).

{% hint style="warning" %}
Uploading overwrites the metadata of every sample named in the file, and replaces its attributes outright: anything you leave out of the file is removed. This can't be undone.
{% endhint %}

## Uploading individual files

1. Click **Data** in the left navigation and select the storage account.
2. Click **Add Metadata** in the page header.
3. Select up to 50 `.ped`, `.json`, `.jsonl` or `.attributes.json` files.
4. Click **Next** to open the **Preview**. Step through the files one at a time. Each is marked **Valid** or **Issues Found**; a file with issues shows the line number and error in a **Validation Issue** panel.
5. Click **Save**. If the upload replaces existing metadata, confirm in the **Update Metadata** dialog.
6. Review the results and click **Close**.

## Uploading a .zip archive

A `.zip` archive lets you add metadata for many samples in one step.

1. Click **Add Metadata** in the samples page header.
2. Select a single `.zip` file. An archive must be uploaded on its own, not mixed with individual files.
3. Click **Upload**. Archives skip the preview; each file's result is reported after the upload.
4. Review the results and click **Close**.

## Upload results

When the upload finishes, the **Upload complete** screen reports how many samples received metadata, for example "Metadata added for 12 samples from 3 files". Any file that needs attention is listed under **Needs attention**, marked either **not added** or **added, some entries skipped**, with the reason for each problem.

## Limits

* Up to 50 individual files per upload.
* Each file must be within the per-file size limit (5 MB by default). Files that are too large, of an unsupported type, or beyond the 50-file limit aren't added, and the dialog tells you how many were skipped and why.
* A `.zip` archive must be uploaded on its own.

{% hint style="info" %}
You can also upload metadata and manage custom attributes from the command line. See [samples metadata upload](/products/command-line-interface/reference/workbench/samples-metadata-upload.md) and [samples attributes set](/products/command-line-interface/reference/workbench/samples-attributes-set.md).
{% endhint %}

{% hint style="danger" %}
Maintain patient privacy. Never include identifying information in metadata files.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.omics.ai/products/workbench/instruments/adding-sample-metadata.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.