SubjectLog schemas

Entry schemas for subject logs: measurements and observations followed over time for one subject.

Table of contents

  1. How to use this family
  2. Quick type map
  3. Consumption Logs
    1. Food consumption log
    2. Water consumption log
  4. Deprivation Logs
    1. Food deprivation log
    2. Water deprivation log
  5. Experimental Preparation Logs
    1. Habituation log
    2. Handling log
    3. Training session log
  6. Genetic Logs
    1. Genotyping log
  7. Housing Logs
    1. Housing log
  8. Observation Logs
    1. Generic observation
    2. Hargreaves thermal sensitivity test
    3. Von Frey mechanical sensitivity test
  9. Physical and Health Logs
    1. Monitoring log
    2. Weighing log
    3. Welfare check
    4. Wellness log

How to use this family

  • subjectlog: type selects 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>.json and never changes; https://www.brainstem.org/schemas/SubjectLog/<Type>.json is the current version and https://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 codeTitleGroupVersionRequired propertiesSchema
FoodConsumptionFood consumption logConsumption Logs1.1.1foodAmount1.1.1.json
FoodDeprivationFood deprivation logDeprivation Logs1.0.1responsiblePerson1.0.1.json
GenericObservationGeneric observationObservation Logs2.0.1observationType, observation2.0.1.json
GenotypingGenotyping logGenetic Logs1.0.2sample, result1.0.2.json
HabituationHabituation logExperimental Preparation Logs1.0.1none1.0.1.json
HandlingHandling logExperimental Preparation Logs1.0.1none1.0.1.json
HargreavesTestHargreaves thermal sensitivity testObservation Logs2.0.2stimulusLocation, latency, responseScore2.0.2.json
HousingHousing logHousing Logs1.0.1none1.0.1.json
MonitoringMonitoring logPhysical and Health Logs1.0.1none1.0.1.json
TrainingSessionTraining session logExperimental Preparation Logs1.0.1none1.0.1.json
VonFreyTestVon Frey mechanical sensitivity testObservation Logs2.0.2stimulusLocation, stimulusForce, responseScore2.0.2.json
WaterConsumptionWater consumption logConsumption Logs1.1.1waterAmount1.1.1.json
WaterDeprivationWater deprivation logDeprivation Logs1.0.1responsiblePerson1.0.1.json
WeighingWeighing logPhysical and Health Logs1.1.1weight1.1.1.json
WelfareCheckWelfare checkPhysical and Health Logs1.0.2demeanourScore, endpointCriteriaMet, actionsTaken1.0.2.json
WellnessWellness logPhysical and Health Logs1.0.1wellness1.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.

PropertyTitleShapeRequiredAllowed valuesMeaning
foodAmountFood amountquantity with unityesunits 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
waterAmountWater amountquantity with unityesunits 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
responsiblePersonResponsible person (name and phone number)textyes The name and contact number of the person responsible during the deprivation period.
protocolProtocoltext  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.

PropertyTitleShapeRequiredAllowed valuesMeaning
responsiblePersonResponsible person (name and phone number)textyes The name and contact number of the person responsible during the deprivation period.
protocolProtocoltext  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.

PropertyTitleShapeRequiredAllowed valuesMeaning
habituationMethodMethod of habituationtext  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.

PropertyTitleShapeRequiredAllowed valuesMeaning
handlingMethodMethod of handlingtext  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.

PropertyTitleShapeRequiredAllowed valuesMeaning
taskTask of the trainingtext  The behavioral task practiced during this training session.
setupSetup of the trainingtext  The apparatus or setup configuration used for this training session.
reinforcementTypeReinforcement typetext  The reinforcement type used during training (e.g. food, water, open-loop/closed loop.
performanceThe performance leveltext  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.

PropertyTitleShapeRequiredAllowed valuesMeaning
resultGenotype resulttextyes Overall interpreted genotype for this subject (e.g., ‘PV-Cre/wt; Ai32/wt; Sex: F’ or ‘Negative for PV-Cre’).
sampleSampletextyes Describe the biological sample used for the genotyping assay, including type and location (e.g., tail snip, ear punch, blood sample).
assayPanelAssay / panel nametext  Which PCR/qPCR panel or service was used.
qcConfidenceQC / confidencechoice one of high, medium, low, ambiguous, failedConfidence or quality of the genotyping result.
lociResultsPer-locus callstable of rows format tablePer-locus genotype calls reported for this genotyping event.
lociResults[].markerMarker / transgene / alleletextyes The marker, transgene, or allele tested at this locus.
lociResults[].callCalltextyes The reported genotype call for this marker or locus.
lociResults[].notesNotestext 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
locationLocationtext  The location the subject is housed, e.g. an animal housing unit with a specific status.
cageIdCage IDtext  The ID of the cage where the subject is housed.
cageTypeCage typetext  The type of cage, e.g. an IVC cage with a specific model number, NexGen500 or NexGen1800.
lightCycleLight cycletext  The light cycle of the housing unit, e.g. normal or reversed, or specific time points
enrichmentEnrichmenttext  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.

PropertyTitleShapeRequiredAllowed valuesMeaning
observationTypeObservation typechoiceyesone of pain_score, grooming, exploration, freezing, facial_expression, unusual_behavior, otherThe category or behavioral domain of the observation.
observationObservationtextyes Description of the observed behavior.
repetitionsRepetitionsinteger ≥ 1; default 1How 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
stimulusLocationStimulus locationchoiceyesone of left_hind_paw, right_hind_paw, left_forepaw, right_forepaw, left_face, right_face, tail, otherAnatomical location where the thermal stimulus was applied using the Hargreaves test.
latencyWithdrawal latencyquantity with unityesunits µs, ms, s, min, h; default {"unit": "s"}Time from stimulus onset to paw withdrawal.
cutoffLatencyCutoff latencyquantity with unit units µs, ms, s, min, h; default {"unit": "s"}Maximum allowable latency before automatic termination to prevent tissue damage.
responseScoreResponse score (0–3)choiceyesone of 0, 1, 2, 3; ≥ 0 and ≤ 3Categorical assessment of behavioral response. 0: No response, 1: Delayed movement, 2: Normal withdrawal, 3: Exaggerated or escape behavior
repetitionsRepetitionsinteger ≥ 1; default 3Number 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
stimulusLocationStimulus locationchoiceyesone of left_hind_paw, right_hind_paw, left_forepaw, right_forepaw, left_face, right_face, tail, otherAnatomical location where the Von Frey filament was applied.
stimulusForceStimulus forcequantity with unityesunits mg, g, kg; default {"unit": "g"}Force of the Von Frey filament used for mechanical stimulation.
responseScoreResponse score (0–3)choiceyesone of 0, 1, 2, 3; ≥ 0 and ≤ 3Categorical assessment of behavioral response to stimulation. 0: No response, 1: Slight movement, 2: Strong withdrawal, 3: Flinching or escape
repetitionsRepetitionsinteger ≥ 1; default 10Number 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
weightWeightquantity with unit units kg, g, mg; default {"unit": "g"}Body weight of the subject.
foodAmountFood consumedquantity with unit units kg, g, mg; default {"unit": "g"}Amount of food consumed since last measurement.
waterAmountWater consumedquantity with unit units L, mL, µL; default {"unit": "mL"}Amount of water consumed since last measurement.
bodyConditionScoreBody condition score (1-5)choice one of 1, 2, 3, 4, 5Manual visual/palpation body condition score (Ullman-Cullere scale). Assessed by the observer independently of body weight — 1 = emaciated, 3 = ideal, 5 = obese.
healthObservationsHealth observationstext (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.

PropertyTitleShapeRequiredAllowed valuesMeaning
weightWeightquantity with unityesunits 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
clinicalSignsClinical signsmulti-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 select2Tick 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.
actionsTakenActions takenmulti-selectyesone 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 select2Select all actions taken. Treatments, analgesia, antibiotics, fluids, or euthanasia should also be recorded as linked Procedure / ProcedureEpisode entries.
demeanourScoreCondition & demeanour (0-4)choiceyesone of 0, 1, 2, 3, 4Overall 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.
monitoringPlanMonitoring plantext  Monitoring plan following this check (frequency and duration).
painMethodPain scoring methodchoice one of not_assessed, clinical_nrs, mouse_grimace_scale, rat_grimace_scale, institutional_score_sheet, otherPain / 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.
painScorePain scorenumber ≥ 0Pain / distress score on the selected scale (e.g. 4 on a Rat Grimace Scale of 0-8).
siteTypeProcedure / wound site typechoice one of not_applicable, surgical, implant, injection_infusion, sample_collection, otherKind 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).
siteObservationSite observationtext  Condition of the wound, surgical, implant, injection, or sample-collection site.
endpointCriterionEndpoint criteriontext  Which humane endpoint criterion was met, if any. These are protocol-defined and vary by study and species.
endpointCriteriaMetHumane endpoint criteria metchoiceyesone 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.

PropertyTitleShapeRequiredAllowed valuesMeaning
wellnessWellnesstextyes The current wellness status of the subject, such as good health, fair, or poor.

Illustrative payload:

{
    "wellness": "text"
}