OHDS v1.1

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 arrays on top of the VODS envelope. Five payload types are defined: inspections (hive management), apiary_summary (seasonal colony counts), harvests (honey, wax, propolis, pollen), pollinator_observations (species sightings), and forage_observations (plant bloom and nectar flow). 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 — producers MUST 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.

Harvest Record

One record per harvest event. The harvests array contains these records. Tracks honey, wax, propolis, pollen, and other hive products.

Pollinator Observation

One record per sighting event. The pollinator_observations array contains these records. Records any pollinator species including honey bees observed as pollinators (distinct from hive management data in inspections).

Forage Observation

One record per plant bloom observation. The forage_observations array contains these records. Tracks what plants are blooming, their nectar flow quality, and bloom timing — critical data for forage mapping and pollinator habitat assessment.

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"
    }
  }
}

Annotations (//) are shown for readability. Valid JSON does not permit comments — omit them in production output.

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. A machine-readable schema for automated validation is available at ohds-v1.0.schema.json.

• O1
  OHDS version declared. Every export includes "ohds_version": "1.0".
• O2
  Minimum content satisfied. Every export contains at least one non-empty array from: inspections, apiary_summary, harvests, pollinator_observations, or forage_observations.
• 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. Each harvest record includes harvest_date, apiary_ref, product, quantity, and unit. Each pollinator observation includes observation_date and species. Each forage observation includes observation_date and plant_name.
• 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.

Glossary

Beekeeping terminology used in this specification. Implementers who are not beekeepers should reference this section when mapping field names to user interfaces or documentation.

Security and Privacy Considerations

OHDS inherits the security considerations defined in VODS §8. The following are specific to beekeeping data.

Location data and hive theft

GPS coordinates in OHDS documents can reveal the physical location of apiaries. Hive theft is a documented and growing problem worldwide — stolen colonies, equipment, and honey represent real financial loss for beekeepers. Coordinates MUST only be included with explicit user consent (O6). In anonymous mode, coordinates MUST be coarsened to ±0.1° minimum (roughly 11 km at the equator). Even in tracked mode, applications SHOULD warn users that sharing precise coordinates with external programs carries risk. Applications SHOULD default to omitting coordinates entirely.

Re-identification through pseudonyms

In tracked mode, stable apiary_ref and hive_ref pseudonyms allow longitudinal tracking across exports to the same program. Correlating pseudonyms with external datasets (public loss reports, regional survey results, operation size) could narrow down a beekeeper's identity. Implementers SHOULD default to anonymous mode when longitudinal tracking is not required for the destination program.

Free-text field sanitization

The notes and product fields accept arbitrary text. Consumers MUST sanitize these values before rendering them in web interfaces or passing them to other systems. In anonymous exports, applications SHOULD strip or redact notes fields that may contain identifying information such as names, addresses, or phone numbers.

Extending OHDS

OHDS is designed to grow. New fields and record types can be added through two mechanisms:

Adding fields to existing record types

New optional fields MAY be added to any existing record type (inspection, apiary summary, harvest, pollinator observation, forage observation) in a MINOR version bump. New fields MUST be optional — existing valid documents MUST remain valid under the new version. Consumers MUST ignore fields they do not recognize (must-ignore semantics).

Adding new record types

New top-level arrays MAY be added in a MINOR version bump. The minimum content rule is updated to include the new array. Existing documents that do not contain the new array remain valid — the rule requires at least one non-empty array, not all of them.

Proposing changes

Anyone may propose additions to OHDS by opening an issue on the protocols repository. Proposals SHOULD include: the field name, type, whether required or optional, a description, and a rationale explaining what research question or use case the field serves. Fields that serve a single organization's needs belong in the extensions namespace (see VODS §4), not in the core spec.

Normative References

OHDS inherits all normative references from VODS §9. The following additional references apply to OHDS domain fields.

Changelog