Installation

Typed SDKs

OVF provides generated type definitions for type-safe development — no manual typing needed.

TypeScript

npm install @vetformat/ovf-types

import type { OvfDocument, Patient, Encounter } from "@vetformat/ovf-types";

const doc: OvfDocument = JSON.parse(rawJson);
console.log(doc.patient.name);    // string
console.log(doc.patient.species); // "dog" | "cat" | "bird" | ...

Python

pip install ovf_types

from ovf_types import OvfDocument, Patient, Encounter

doc = OvfDocument.model_validate(data)
print(doc.patient.name)
print(doc.patient.species)

Tip

The Python models are Pydantic v2 BaseModels — you get validation, serialization, and IDE autocomplete out of the box.

JSON Schemas

If you need the raw schemas (e.g. for validation or code generation in other languages):

npm install @vetformat/ovf

This installs all JSON Schema files and the ovf-validate CLI tool.

CLI validation

Validate any OVF JSON file from the command line:

npx ovf-validate <file.json>

Examples:

npx ovf-validate patient-record.json
npx ovf-validate ./exports/*.json

Programmatic validation (TypeScript)

Use ajv with JSON Schema Draft 2020-12 support:

import Ajv2020 from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
import { readFileSync } from "node:fs";

const ajv = new Ajv2020({ allErrors: true, strict: false });
addFormats(ajv);

// Load all resource schemas first so $ref resolution works
const schemas = [
  "patient",
  "encounter",
  "condition",
  "observation",
  "immunization",
  "procedure",
  "allergy-intolerance",
  "medication-statement",
  "document-reference",
];
for (const name of schemas) {
  ajv.addSchema(
    JSON.parse(
      readFileSync(
        `node_modules/@vetformat/ovf/schemas/v1/${name}.schema.json`,
        "utf-8"
      )
    )
  );
}

// Compile the root OVF document schema
const rootSchema = JSON.parse(
  readFileSync(
    "node_modules/@vetformat/ovf/schemas/v1/ovf.schema.json",
    "utf-8"
  )
);
const validate = ajv.compile(rootSchema);

// Validate a document
const doc = JSON.parse(readFileSync("my-record.json", "utf-8"));
if (validate(doc)) {
  console.log("Valid OVF document!");
} else {
  console.error(validate.errors);
}

Note

You must add all resource schemas to the ajv instance before compiling the root schema, because the root schema uses $ref to reference them.

Programmatic validation (Python)

Use jsonschema with Draft 2020-12 support, or simply use the typed models for validation:

from ovf_types import OvfDocument
import json

with open("my-record.json") as f:
    data = json.load(f)

# Pydantic validates the structure automatically
doc = OvfDocument.model_validate(data)
print(f"Patient: {doc.patient.name}")
print(f"Encounters: {len(doc.encounters or [])}")

For schema-level validation without Pydantic:

import json
from pathlib import Path
from jsonschema import Draft202012Validator, FormatChecker

schemas_dir = Path("schemas/v1")  # or wherever your schemas are

patient_schema = json.loads(
    (schemas_dir / "patient.schema.json").read_text()
)

validator = Draft202012Validator(
    patient_schema, format_checker=FormatChecker()
)

patient = {
    "resource_type": "Patient",
    "id": "pet-001",
    "name": "Burek",
    "species": "dog",
}

errors = list(validator.iter_errors(patient))
if not errors:
    print("Patient is valid")
else:
    for error in errors:
        print(f"Validation error: {error.message}")

Next steps

• Quick Start — create your first OVF document
• Schema Reference — detailed field definitions for all resource types
• Extensions — add custom fields with the x_ prefix