Observation

Represents a clinical observation or measurement for a patient, including vital signs, lab results, imaging findings, and clinical notes.

Schema ID: https://vetformat.org/schemas/v1/observation.schema.json

Fields

Field	Type	Required	Description
resource_type	"Observation"	Yes	Fixed resource type identifier for this schema.
id	string	Yes	Unique identifier for the observation record. UUID recommended.
patient_id	string	Yes	Reference to the patient this observation belongs to.
encounter_id	string	No	Reference to the encounter during which this observation was recorded.
category	enum	Yes	The high-level category of the observation.
code	[code]	No
name	string	Yes	Human-readable name of the observation.
effective_date	string (date-time)	Yes	Date and time when the observation was clinically effective or measured.
value	number | string | boolean | object	No	The observed value. Can be a number, string, boolean, or structured object depending on the observation type.
value_type	enum	No	Hint for the semantic type of the value field. Helps LLMs and parsers interpret the value correctly without type inference. ‘quantity’ = numeric with unit, ‘text’ = free text or narrative, ‘boolean’ = yes/no result, ‘ratio’ = e.g. titer 1:128, ‘range’ = value expressed as a range, ‘coded’ = value from a controlled vocabulary, ‘attachment’ = reference to external data.
unit	string	No	Unit of measurement for the observed value.
reference_range	[reference_range]	No
interpretation	enum	No	Clinical interpretation of the observation value relative to reference ranges.
notes	string	No	Additional notes or context about the observation.

category values

• vital-signs
• laboratory
• imaging
• clinical-note
• other

value_type values

• quantity
• text
• boolean
• ratio
• range
• coded
• attachment

interpretation values

• normal
• abnormal
• low
• high
• critical

Sub-objects

code object

Coded representation of the observation type using a terminology system.

Field	Type	Required	Description
system	string	Yes	The coding system used (e.g., LOINC, SNOMED, internal).
value	string	Yes	The code value within the specified system.
display	string	Yes	Human-readable display text for the code.

reference_range object

The normal or expected range for this observation value.

Field	Type	Required	Description
low	number	No	Lower bound of the reference range.
high	number	No	Upper bound of the reference range.
text	string	No	Human-readable description of the reference range.

Full Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://vetformat.org/schemas/v1/observation.schema.json",
  "title": "Observation",
  "description": "Represents a clinical observation or measurement for a patient, including vital signs, lab results, imaging findings, and clinical notes.",
  "type": "object",
  "required": [
    "resource_type",
    "id",
    "patient_id",
    "category",
    "name",
    "effective_date"
  ],
  "additionalProperties": true,
  "$defs": {
    "code": {
      "type": "object",
      "description": "Coded representation of the observation type using a terminology system.",
      "properties": {
        "system": {
          "type": "string",
          "description": "The coding system used (e.g., LOINC, SNOMED, internal).",
          "examples": [
            "loinc"
          ]
        },
        "value": {
          "type": "string",
          "description": "The code value within the specified system.",
          "examples": [
            "2339-0"
          ]
        },
        "display": {
          "type": "string",
          "description": "Human-readable display text for the code.",
          "examples": [
            "Blood Glucose"
          ]
        }
      },
      "required": [
        "system",
        "value",
        "display"
      ],
      "additionalProperties": true
    },
    "reference_range": {
      "type": "object",
      "description": "The normal or expected range for this observation value.",
      "properties": {
        "low": {
          "type": "number",
          "description": "Lower bound of the reference range.",
          "examples": [
            70
          ]
        },
        "high": {
          "type": "number",
          "description": "Upper bound of the reference range.",
          "examples": [
            140
          ]
        },
        "text": {
          "type": "string",
          "description": "Human-readable description of the reference range.",
          "examples": [
            "70-140 mg/dL"
          ]
        }
      },
      "additionalProperties": true
    }
  },
  "properties": {
    "resource_type": {
      "const": "Observation",
      "description": "Fixed resource type identifier for this schema.",
      "examples": [
        "Observation"
      ]
    },
    "id": {
      "type": "string",
      "description": "Unique identifier for the observation record. UUID recommended.",
      "examples": [
        "obs-550e8400-e29b-41d4-a716-446655440000"
      ]
    },
    "patient_id": {
      "type": "string",
      "description": "Reference to the patient this observation belongs to.",
      "examples": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    },
    "encounter_id": {
      "type": "string",
      "description": "Reference to the encounter during which this observation was recorded.",
      "examples": [
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      ]
    },
    "category": {
      "type": "string",
      "enum": [
        "vital-signs",
        "laboratory",
        "imaging",
        "clinical-note",
        "other"
      ],
      "description": "The high-level category of the observation.",
      "examples": [
        "laboratory"
      ]
    },
    "code": {
      "$ref": "#/$defs/code"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name of the observation.",
      "examples": [
        "Blood Glucose"
      ]
    },
    "effective_date": {
      "type": "string",
      "format": "date-time",
      "description": "Date and time when the observation was clinically effective or measured.",
      "examples": [
        "2025-06-15T10:45:00Z"
      ]
    },
    "value": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ],
      "description": "The observed value. Can be a number, string, boolean, or structured object depending on the observation type.",
      "examples": [
        95.5,
        "Positive",
        true
      ]
    },
    "value_type": {
      "type": "string",
      "enum": [
        "quantity",
        "text",
        "boolean",
        "ratio",
        "range",
        "coded",
        "attachment"
      ],
      "description": "Hint for the semantic type of the value field. Helps LLMs and parsers interpret the value correctly without type inference. 'quantity' = numeric with unit, 'text' = free text or narrative, 'boolean' = yes/no result, 'ratio' = e.g. titer 1:128, 'range' = value expressed as a range, 'coded' = value from a controlled vocabulary, 'attachment' = reference to external data.",
      "examples": [
        "quantity"
      ]
    },
    "unit": {
      "type": "string",
      "description": "Unit of measurement for the observed value.",
      "examples": [
        "mg/dL"
      ]
    },
    "reference_range": {
      "$ref": "#/$defs/reference_range"
    },
    "interpretation": {
      "type": "string",
      "enum": [
        "normal",
        "abnormal",
        "low",
        "high",
        "critical"
      ],
      "description": "Clinical interpretation of the observation value relative to reference ranges.",
      "examples": [
        "normal"
      ]
    },
    "notes": {
      "type": "string",
      "description": "Additional notes or context about the observation.",
      "examples": [
        "Fasting sample collected at 8:00 AM."
      ]
    }
  }
}