> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/in-vivo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/in-vivo/_mcp/server.

# Data model

These diagrams show the entities in the In Vivo API and how they link. Each diagram covers one area, so some entities,
such as Study and Animal, appear in more than one.

## Studies

A study is split into study groups. Treatments are defined on the study and assigned to its groups, so a group can
have several treatments and a treatment can be assigned to several groups. A study can also have a study code, a
measurement preset that sets the calculations made from its measurements, cages, and requests raised by one user and
assigned to another.

```mermaid
erDiagram
    StudyCode |o--o{ Study : "labels"
    Study ||--o| StudyPreset : "uses"
    Study |o--o{ Cage : "has"
    Study |o--o{ StudyGroup : "has"
    Study |o--o{ Treatment : "defines"
    StudyGroup ||--o{ StudyGroupTreatment : "is assigned"
    Treatment ||--o{ StudyGroupTreatment : "is assigned to"
    Study ||--o{ Request : "has"
    User ||--o{ Request : "raises"
    User |o--o{ Request : "is assigned"
```

## Animals

An animal can be in a study, a study group and a cage, and its strain sets its species. A planned animal is an animal
a study expects to enrol, and a registered animal is assigned to it once one is enrolled.

```mermaid
erDiagram
    Study |o--o{ Animal : "enrols"
    StudyGroup |o--o{ Animal : "contains"
    Cage |o--o{ Animal : "houses"
    Species ||--o{ Strain : "has"
    Strain |o--o{ Animal : "is the strain of"
    Study |o--o{ PlannedAnimal : "plans"
    StudyGroup |o--o{ PlannedAnimal : "contains"
    PlannedAnimal |o--o| Animal : "is assigned"
```

## Recorded data

Observations, measurements, samples and dosages are recorded against an animal by a user. A dosage records one dose
of a treatment. When the dose was scaled to the animal's weight, the dosage links to the measurement that recorded
that weight.

```mermaid
erDiagram
    Animal ||--o{ Observation : "has"
    Animal ||--o{ Measurement : "has"
    Animal ||--o{ Sample : "has"
    Animal ||--o{ Dosage : "has"
    Treatment ||--o{ Dosage : "is given in"
    Measurement |o--o{ Dosage : "sets the weight for"
```

## Sampling

A sample plan sets the sample type to collect in a study and when to collect it. It can target study groups, planned
animals or registered animals, or have no target. Samples collected for a plan link to it, and a sample can also be
attached to a request.

```mermaid
erDiagram
    Study ||--o{ SamplePlan : "plans"
    SamplePlan ||--o{ SamplePlanTarget : "has"
    StudyGroup |o--o{ SamplePlanTarget : "is targeted by"
    PlannedAnimal |o--o{ SamplePlanTarget : "is targeted by"
    Animal |o--o{ SamplePlanTarget : "is targeted by"
    SamplePlan |o--o{ Sample : "defines"
    Request |o--o{ Sample : "requests"
```

## Tasks

A task spec is a measurement, sample, observation, dosing or other task on a study. It runs once, on a repeating
schedule, or when a condition is met, and is assigned to users and can target specific study groups. A dosing task
lists the treatments to give, and an observation or sampling task lists the types to record from the team glossary.

```mermaid
erDiagram
    Study ||--o{ TaskSpec : "schedules"
    TaskSpec ||--o{ TaskTarget : "has"
    StudyGroup ||--o{ TaskTarget : "is targeted by"
    TaskSpec ||--o{ TaskAssignee : "has"
    User ||--o{ TaskAssignee : "is"
```

## Glossaries

The team glossary holds the observation and sample types your team has set up. Observation types can have an allowed
numeric range, and sample types list the details to record, such as weight or volume. The shared glossary holds
entries that are the same for every team, such as euthanize reasons, and is where an animal's termination reason comes
from.

```mermaid
erDiagram
    TeamObservationGlossary |o--o{ Observation : "is the type of"
    TeamSampleGlossary ||--o{ SamplePlan : "is the sample type of"
    Glossary |o--o{ Observation : "is the type of"
    Glossary |o--o{ Animal : "is the termination reason of"
```

## Metadata

Metadata adds your own fields to entities such as studies, animals and cages. Each metadata glossary entry defines one
field, and entities store their values in `metadata`, keyed by the entry's `slug`. `select` and `multi_select` fields
list their values in the entry's `options`. Only `lookup_select` and `lookup_multi_select` fields have metadata
options, which you manage with the metadata option endpoints. See [Metadata glossary](/in-vivo/overview/metadata-glossary)
for the field types.

```mermaid
erDiagram
    MetadataGlossary ||--o{ MetadataOption : "has (lookup fields only)"
    MetadataGlossary {
        string slug
        string type
        string field_type
        list options "select and multi_select only"
    }
    MetadataOption {
        string value
    }
```

## Projects

A study can belong to a project, and a project user role gives a user a role on a project. A study's team lists the
users who can access it, and a study can have an author and an owner.

```mermaid
erDiagram
    User ||--o{ ProjectUserRole : "is assigned"
    ProjectRole ||--o{ ProjectUserRole : "grants"
    Project ||--o{ ProjectUserRole : "has"
    Project |o--o{ Study : "contains"
    User ||--o{ StudyUser : "is"
    Study ||--o{ StudyUser : "has team member"
    User |o--o{ Study : "is the author of"
    User |o--o{ Study : "is the owner of"
```