SubjectLog schemas
Entry schemas for subject logs: measurements and observations followed over time for one subject.
Table of contents
- How to use this family
- Quick type map
- Consumption Logs
- Deprivation Logs
- Experimental Preparation Logs
- Genetic Logs
- Housing Logs
- Observation Logs
- Physical and Health Logs
How to use this family
subjectlog:typeselects the type; each log entry added through the entry actions is validated against it.- Every version is published at
https://www.brainstem.org/schemas/SubjectLog/<Type>/<version>.jsonand never changes;https://www.brainstem.org/schemas/SubjectLog/<Type>.jsonis the current version andhttps://www.brainstem.org/schemas/SubjectLog/<Type>/lists the versions. See Public schemas. - Quantities are objects
{"value": <number>, "unit": "<code>"}. Property paths with[]are inside a repeatable list of rows. The server sets the schema version field itself.
Quick type map
| Type code | Title | Group | Version | Required properties | Schema |
|---|---|---|---|---|---|
FoodConsumption | Food consumption log | Consumption Logs | 1.1.1 | foodAmount | 1.1.1.json |
FoodDeprivation | Food deprivation log | Deprivation Logs | 1.0.1 | responsiblePerson | 1.0.1.json |
GenericObservation | Generic observation | Observation Logs | 2.0.1 | observationType, observation | 2.0.1.json |
Genotyping | Genotyping log | Genetic Logs | 1.0.2 | sample, result | 1.0.2.json |
Habituation | Habituation log | Experimental Preparation Logs | 1.0.1 | none | 1.0.1.json |
Handling | Handling log | Experimental Preparation Logs | 1.0.1 | none | 1.0.1.json |
HargreavesTest | Hargreaves thermal sensitivity test | Observation Logs | 2.0.2 | stimulusLocation, latency, responseScore | 2.0.2.json |
Housing | Housing log | Housing Logs | 1.0.1 | none | 1.0.1.json |
Monitoring | Monitoring log | Physical and Health Logs | 1.0.1 | none | 1.0.1.json |
TrainingSession | Training session log | Experimental Preparation Logs | 1.0.1 | none | 1.0.1.json |
VonFreyTest | Von Frey mechanical sensitivity test | Observation Logs | 2.0.2 | stimulusLocation, stimulusForce, responseScore | 2.0.2.json |
WaterConsumption | Water consumption log | Consumption Logs | 1.1.1 | waterAmount | 1.1.1.json |
WaterDeprivation | Water deprivation log | Deprivation Logs | 1.0.1 | responsiblePerson | 1.0.1.json |
Weighing | Weighing log | Physical and Health Logs | 1.1.1 | weight | 1.1.1.json |
WelfareCheck | Welfare check | Physical and Health Logs | 1.0.2 | demeanourScore, endpointCriteriaMet, actionsTaken | 1.0.2.json |
Wellness | Wellness log | Physical and Health Logs | 1.0.1 | wellness | 1.0.1.json |
Consumption Logs
Food consumption log
- type code
FoodConsumption· version 1.1.1 · schema
Logs the amount of food a subject consumed, for tracking intake over time, for example during food restriction.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
foodAmount | Food amount | quantity with unit | yes | units kg, g, mg, µg; default {"unit": "g"} | Food amount consumed. |
Illustrative payload:
{
"foodAmount": {
"value": 1,
"unit": "g"
}
}
Water consumption log
- type code
WaterConsumption· version 1.1.1 · schema
Logs the amount of water a subject consumed, for tracking intake over time, for example during water restriction.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
waterAmount | Water amount | quantity with unit | yes | units L, mL, µL, nL, pL; default {"unit": "mL"} | Water amount consumed. |
Illustrative payload:
{
"waterAmount": {
"value": 1,
"unit": "mL"
}
}
Deprivation Logs
Food deprivation log
- type code
FoodDeprivation· version 1.0.1 · schema
Logs periods of food restriction or deprivation, with the responsible person’s name and phone number and the protocol governing the deprivation.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
responsiblePerson | Responsible person (name and phone number) | text | yes | The name and contact number of the person responsible during the deprivation period. | |
protocol | Protocol | text | The approved or laboratory protocol governing this deprivation record. |
Illustrative payload:
{
"responsiblePerson": "text",
"protocol": "text"
}
Water deprivation log
- type code
WaterDeprivation· version 1.0.1 · schema
Logs periods of water restriction or deprivation, with the responsible person’s name and phone number and the protocol governing the deprivation.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
responsiblePerson | Responsible person (name and phone number) | text | yes | The name and contact number of the person responsible during the deprivation period. | |
protocol | Protocol | text | The approved or laboratory protocol governing this deprivation record. |
Illustrative payload:
{
"responsiblePerson": "text",
"protocol": "text"
}
Experimental Preparation Logs
Habituation log
- type code
Habituation· version 1.0.1 · schema
Logs sessions habituating a subject before experiments, with the method used, such as tail lift, cupping or glove.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
habituationMethod | Method of habituation | text | E.g., tail lift, cupping, glove. |
Illustrative payload:
{
"habituationMethod": "text"
}
Handling log
- type code
Handling· version 1.0.1 · schema
Logs handling sessions, with the method used, such as tail lift, cupping or glove.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
handlingMethod | Method of handling | text | E.g., tail lift, cupping, glove. |
Illustrative payload:
{
"handlingMethod": "text"
}
Training session log
- type code
TrainingSession· version 1.0.1 · schema
Logs a behavioral training session, with the task, setup, reinforcement type and performance level reached.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
task | Task of the training | text | The behavioral task practiced during this training session. | ||
setup | Setup of the training | text | The apparatus or setup configuration used for this training session. | ||
reinforcementType | Reinforcement type | text | The reinforcement type used during training (e.g. food, water, open-loop/closed loop. | ||
performance | The performance level | text | The performance level of the training. How well the subject performs the task |
Illustrative payload:
{
"task": "text",
"setup": "text"
}
Genetic Logs
Genotyping log
- type code
Genotyping· version 1.0.2 · schema
Logs a genotyping result for the subject, with the interpreted genotype, the sample used, assay or panel, confidence and per-locus calls.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
result | Genotype result | text | yes | Overall interpreted genotype for this subject (e.g., ‘PV-Cre/wt; Ai32/wt; Sex: F’ or ‘Negative for PV-Cre’). | |
sample | Sample | text | yes | Describe the biological sample used for the genotyping assay, including type and location (e.g., tail snip, ear punch, blood sample). | |
assayPanel | Assay / panel name | text | Which PCR/qPCR panel or service was used. | ||
qcConfidence | QC / confidence | choice | one of high, medium, low, ambiguous, failed | Confidence or quality of the genotyping result. | |
lociResults | Per-locus calls | table of rows | format table | Per-locus genotype calls reported for this genotyping event. | |
lociResults[].marker | Marker / transgene / allele | text | yes | The marker, transgene, or allele tested at this locus. | |
lociResults[].call | Call | text | yes | The reported genotype call for this marker or locus. | |
lociResults[].notes | Notes | text | default "" | A concise qualification of this locus-level genotype call. |
Illustrative payload:
{
"result": "text",
"sample": "text",
"assayPanel": "text",
"qcConfidence": "high"
}
Housing Logs
Housing log
- type code
Housing· version 1.0.1 · schema
Logs where and how a subject is housed, with location, cage ID and type, light cycle and enrichment.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
location | Location | text | The location the subject is housed, e.g. an animal housing unit with a specific status. | ||
cageId | Cage ID | text | The ID of the cage where the subject is housed. | ||
cageType | Cage type | text | The type of cage, e.g. an IVC cage with a specific model number, NexGen500 or NexGen1800. | ||
lightCycle | Light cycle | text | The light cycle of the housing unit, e.g. normal or reversed, or specific time points | ||
enrichment | Enrichment | text | Enrichment items in the cage such as nesting material, shelter, or something to gnaw. |
Illustrative payload:
{
"location": "text",
"cageId": "text"
}
Observation Logs
Generic observation
- type code
GenericObservation· version 2.0.1 · schema
Logs a behavioral or other observation that no specific log type covers, with its category, a description and the number of repetitions.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
observationType | Observation type | choice | yes | one of pain_score, grooming, exploration, freezing, facial_expression, unusual_behavior, other | The category or behavioral domain of the observation. |
observation | Observation | text | yes | Description of the observed behavior. | |
repetitions | Repetitions | integer | ≥ 1; default 1 | How many times this observation was recorded under the same condition. |
Illustrative payload:
{
"observationType": "pain_score",
"observation": "text",
"repetitions": 1
}
Hargreaves thermal sensitivity test
- type code
HargreavesTest· version 2.0.2 · schema
Logs Hargreaves tests of thermal sensitivity, with stimulus location, paw withdrawal latency, cutoff latency, a 0 to 3 response score and the number of trials.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
stimulusLocation | Stimulus location | choice | yes | one of left_hind_paw, right_hind_paw, left_forepaw, right_forepaw, left_face, right_face, tail, other | Anatomical location where the thermal stimulus was applied using the Hargreaves test. |
latency | Withdrawal latency | quantity with unit | yes | units µs, ms, s, min, h; default {"unit": "s"} | Time from stimulus onset to paw withdrawal. |
cutoffLatency | Cutoff latency | quantity with unit | units µs, ms, s, min, h; default {"unit": "s"} | Maximum allowable latency before automatic termination to prevent tissue damage. | |
responseScore | Response score (0–3) | choice | yes | one of 0, 1, 2, 3; ≥ 0 and ≤ 3 | Categorical assessment of behavioral response. 0: No response, 1: Delayed movement, 2: Normal withdrawal, 3: Exaggerated or escape behavior |
repetitions | Repetitions | integer | ≥ 1; default 3 | Number of repeated Hargreaves trials at the given location. |
Illustrative payload:
{
"stimulusLocation": "left_hind_paw",
"latency": {
"value": 1,
"unit": "s"
},
"responseScore": 0,
"cutoffLatency": {
"value": 1,
"unit": "s"
},
"repetitions": 3
}
Von Frey mechanical sensitivity test
- type code
VonFreyTest· version 2.0.2 · schema
Logs Von Frey tests of mechanical sensitivity, with stimulus location, filament force, a 0 to 3 response score and the number of repetitions.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
stimulusLocation | Stimulus location | choice | yes | one of left_hind_paw, right_hind_paw, left_forepaw, right_forepaw, left_face, right_face, tail, other | Anatomical location where the Von Frey filament was applied. |
stimulusForce | Stimulus force | quantity with unit | yes | units mg, g, kg; default {"unit": "g"} | Force of the Von Frey filament used for mechanical stimulation. |
responseScore | Response score (0–3) | choice | yes | one of 0, 1, 2, 3; ≥ 0 and ≤ 3 | Categorical assessment of behavioral response to stimulation. 0: No response, 1: Slight movement, 2: Strong withdrawal, 3: Flinching or escape |
repetitions | Repetitions | integer | ≥ 1; default 10 | Number of repetitions of Von Frey stimulation at the given location. |
Illustrative payload:
{
"stimulusLocation": "left_hind_paw",
"stimulusForce": {
"value": 1,
"unit": "g"
},
"responseScore": 0,
"repetitions": 10
}
Physical and Health Logs
Monitoring log
- type code
Monitoring· version 1.0.1 · schema
Logs routine monitoring of a subject, combining body weight, food and water consumed, body condition score and general health notes.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
weight | Weight | quantity with unit | units kg, g, mg; default {"unit": "g"} | Body weight of the subject. | |
foodAmount | Food consumed | quantity with unit | units kg, g, mg; default {"unit": "g"} | Amount of food consumed since last measurement. | |
waterAmount | Water consumed | quantity with unit | units L, mL, µL; default {"unit": "mL"} | Amount of water consumed since last measurement. | |
bodyConditionScore | Body condition score (1-5) | choice | one of 1, 2, 3, 4, 5 | Manual visual/palpation body condition score (Ullman-Cullere scale). Assessed by the observer independently of body weight — 1 = emaciated, 3 = ideal, 5 = obese. | |
healthObservations | Health observations | text (multi-line) | General health notes, appearance, and behaviour observations. |
Illustrative payload:
{
"weight": {
"value": 1,
"unit": "g"
},
"foodAmount": {
"value": 1,
"unit": "g"
}
}
Weighing log
- type code
Weighing· version 1.1.1 · schema
Logs the subject’s body weight. Use Monitoring to record weight together with consumption and health observations.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
weight | Weight | quantity with unit | yes | units kg, g, mg, µg; default {"unit": "g"} | Weight of subject. |
Illustrative payload:
{
"weight": {
"value": 1,
"unit": "g"
}
}
Welfare check
- type code
WelfareCheck· version 1.0.2 · schema
Logs a clinical welfare assessment, with abnormal signs, condition and pain scores, condition of wound or implant sites, actions taken, the monitoring plan and whether a humane endpoint was met.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
clinicalSigns | Clinical signs | multi-select | one of hunched_posture, poor_grooming, piloerection, discharge_or_porphyrin, dehydrated, reduced_food_water, reduced_mobility, labored_breathing, seizure, tremor, circling, ataxia, paresis_or_paralysis, head_tilt, self_injury, abnormal_vocalisation, other; format select2 | Tick all abnormal clinical signs observed. Neurological or motor signs (seizure, tremor, circling, ataxia, paresis, head tilt) may be model- or procedure-related. Leave empty if none observed. | |
actionsTaken | Actions taken | multi-select | yes | one of none, continue_monitoring, increase_monitoring, husbandry_support, food_or_water_support, clinical_treatment_given, analgesia_given, vet_notified, vet_assessment_requested, procedure_paused, withdrawn_from_study, humane_endpoint_applied, other; format select2 | Select all actions taken. Treatments, analgesia, antibiotics, fluids, or euthanasia should also be recorded as linked Procedure / ProcedureEpisode entries. |
demeanourScore | Condition & demeanour (0-4) | choice | yes | one of 0, 1, 2, 3, 4 | Overall clinical condition and demeanour on the BAR/QAR scale, scored 0 (normal) to 4 (worst). This is a demeanour score, not a Body Condition Score — record body weight and body condition in the Monitoring log. • 0: Bright, alert, responsive — normal behaviour and activity. • 1: Quiet but responsive — mildly subdued, still aware and reactive. • 2: Subdued, reduced activity — noticeably less active; may show early hunching. • 3: Lethargic, reluctant to move — markedly reduced activity, hunched/isolated; indicates distress. • 4: Moribund or non-responsive — humane endpoint; record the action taken and notify the named veterinary surgeon. |
monitoringPlan | Monitoring plan | text | Monitoring plan following this check (frequency and duration). | ||
painMethod | Pain scoring method | choice | one of not_assessed, clinical_nrs, mouse_grimace_scale, rat_grimace_scale, institutional_score_sheet, other | Pain / distress scoring instrument used. The scale range differs between instruments (shown in each option), so the method is recorded alongside the score to keep it interpretable. Grimace scales should be scored in awake animals. | |
painScore | Pain score | number | ≥ 0 | Pain / distress score on the selected scale (e.g. 4 on a Rat Grimace Scale of 0-8). | |
siteType | Procedure / wound site type | choice | one of not_applicable, surgical, implant, injection_infusion, sample_collection, other | Kind of procedure that created the site being assessed. Categories mirror the Procedure type groups. Use ‘Other’ for non-procedure lesions (e.g. barbering or fight wounds). | |
siteObservation | Site observation | text | Condition of the wound, surgical, implant, injection, or sample-collection site. | ||
endpointCriterion | Endpoint criterion | text | Which humane endpoint criterion was met, if any. These are protocol-defined and vary by study and species. | ||
endpointCriteriaMet | Humane endpoint criteria met | choice | yes | one of no, yes; default "no" | Whether predefined humane endpoint criteria were met at this check. If ‘Yes’, record the criterion and the action taken. |
Illustrative payload:
{
"actionsTaken": [
"none"
],
"demeanourScore": 0,
"endpointCriteriaMet": "no",
"clinicalSigns": [
"hunched_posture"
],
"monitoringPlan": "text"
}
Wellness log
- type code
Wellness· version 1.0.1 · schema
Logs a brief overall wellness status for the subject, such as good health, fair or poor.
| Property | Title | Shape | Required | Allowed values | Meaning |
|---|---|---|---|---|---|
wellness | Wellness | text | yes | The current wellness status of the subject, such as good health, fair, or poor. |
Illustrative payload:
{
"wellness": "text"
}