OHDS v1.0

Overview

OHDS is a domain specialization of VODS (Veydrin Open Data Standard). Every OHDS document is also a valid VODS document. OHDS adds the ohds_version field and the domain payload — inspections and apiary_summary arrays — on top of the VODS envelope. Refer to the VODS v1.0 specification for the full definition of envelope fields, the anonymization model, the extensions system, and the versioning contract. This document specifies only what OHDS adds.

An OHDS file is a single .ohds.json file. Applications export it; converters transform it into program-specific formats. No SDK or library is required. Any developer who can write JSON can implement the standard in an afternoon.

Document Envelope

Every OHDS document begins with the VODS envelope (inherited) followed by the OHDS domain version field. Together these five fields identify the document and its conformance claims.

Minimum content rule

An OHDS document must contain at least one of inspections or apiary_summary, and whichever arrays are present must be non-empty. A document with neither array, or with both arrays empty, is not valid OHDS.

Inspection Record

One record per hive visit. The inspections array contains these records. Fields marked optional may be omitted entirely — do not include a field with a null value.

3.1 Treatment record

3.2 Feeding record

Apiary Summary Record

One record per apiary per season. Used for loss surveys (BIP, COLOSS). The apiary_summary array contains these records.

Full Example

{
  // VODS envelope
  "vods_version":  "1.0",
  "export_id":    "a3f8c2e1-04b7-4d9e-b221-7f3a09cc1d82",
  "export_date":  "2026-03-09T14:22:00Z",
  "export_mode":  "anonymous",

  // OHDS domain fields
  "ohds_version":  "1.0",

  "inspections": [
    {
      "inspection_date": "2026-03-01",
      "apiary_ref":      "A-9f4c",   // randomized this export
      "hive_ref":        "H-2a71",   // randomized this export
      "colony_status":   "alive",
      "hive_type":       "langstroth",
      "bee_race":        "italian",
      "frames_of_bees":  8,
      "varroa_count":    1.4,
      "varroa_method":   "alcohol_wash",
      "treatments": [
        {
          "product":    "oxalic acid",
          "method":     "vaporization",
          "date_start": "2026-02-15"
        }
      ]
    }
  ],

  "apiary_summary": [
    {
      "apiary_ref":      "A-9f4c",
      "season":          "winter",
      "year":            "2025-2026",
      "season_start":    "2025-10-01",
      "season_end":      "2026-04-01",
      "colonies_start":  12,
      "colonies_end":    10,
      "lost_dead":       1,
      "lost_queen":      1,
      "new_splits":      2,
      "operation_size":  "backyard",
      "region":          "US-TX"
    }
  ]
}

{
  // VODS envelope — tracked mode for longitudinal program
  "vods_version":  "1.0",
  "export_id":    "d91cc3f4-88ab-4e02-a301-0f2b17dc5e41",
  "export_date":  "2026-03-09T14:22:00Z",
  "export_mode":  "tracked",

  "ohds_version":  "1.0",

  "inspections": [
    {
      "inspection_date": "2026-03-01",
      "apiary_ref":      "A-bip-7c3d",  // stable for BIP program
      "hive_ref":        "H-bip-4f19",  // stable for BIP program
      "colony_status":   "alive",
      "frames_of_bees":  9,
      "varroa_count":    0.8,
      "varroa_method":   "alcohol_wash"
    }
  ],

  "extensions": {
    "hfh": {
      "program_cohort": "Spring 2026",
      "mentor_id":      "M-42"
    }
  }
}

Reference Converters

These snippets transform an OHDS document into the format expected by major citizen science programs. They are reference implementations — not the only valid approach.

BIP format (Python)

def ohds_to_bip(ohds: dict) -> list[dict]:
    """Convert OHDS apiary_summary records to BIP loss survey rows."""
    rows = []
    for s in ohds.get("apiary_summary", []):
        start     = s["colonies_start"]
        purchased = s.get("new_purchased", 0)
        splits    = s.get("new_splits", 0)
        at_risk   = start + purchased + splits
        lost      = start - s["colonies_end"]

        rows.append({
            "apiary_id":      s["apiary_ref"],
            "season":         s["season"],
            "year":           s["year"],
            "colonies_oct1":  start,
            "colonies_april": s["colonies_end"],
            "total_lost":     lost,
            "loss_rate":      round(lost / at_risk, 4) if at_risk else None,
            "operation_size": s.get("operation_size"),
            "region":         s.get("region"),
        })
    return rows

COLOSS format (Python)

def ohds_to_coloss(ohds: dict) -> list[dict]:
    """Convert OHDS apiary_summary to COLOSS questionnaire rows."""
    rows = []
    for s in ohds.get("apiary_summary", []):
        rows.append({
            "apiary_ref":         s["apiary_ref"],
            "country_region":     s.get("region", ""),
            "season":             s.get("season"),
            "year":               s["year"],
            "season_start":       s.get("season_start"),
            "season_end":         s.get("season_end"),
            "colonies_managed":   s["colonies_start"],
            "colonies_lost":      s["colonies_start"] - s["colonies_end"],
            "colonies_survived":  s["colonies_end"],
            "loss_causes":        ",".join(s.get("perceived_loss_causes", [])),
            "operation_type":     s.get("operation_size"),
            "migratory":          s.get("migratory"),
        })
    return rows

Conformance Rules

An application claims OHDS v1.0 conformance by satisfying all VODS v1.0 conformance rules (see VODS spec §6) and the following OHDS-specific rules.

• O1
  OHDS version declared. Every export includes "ohds_version": "1.0".
• O2
  Minimum content satisfied. Every export contains at least one non-empty inspections or apiary_summary array.
• O3
  Required fields present. Each inspection record includes inspection_date, apiary_ref, hive_ref, and colony_status. Each apiary summary includes apiary_ref, season, year, colonies_start, and colonies_end.
• O4
  No null optional fields. Optional fields that have no value are omitted from the document entirely, not serialized as null.
• O5
  Anonymization honoured in payload. apiary_ref and hive_ref values are generated per the active export_mode. In anonymous mode all refs are randomized per export. In tracked mode refs are stable per-program pseudonyms derived without exposing internal IDs.
• O6
  Coordinates opt-in and coarsened. Location data is included only with explicit user consent. In anonymous mode, coordinates are coarsened to ±0.1° minimum before export.