VODS v1.0

Overview

VODS defines the common contract that all Veydrin-family data exports share. It does not specify what data a particular domain exports — that is the responsibility of domain specs like OHDS (Open Hive Data Standard) or OCEADS. VODS specifies the envelope: the identity, mode, privacy model, and extension system that every conforming export carries regardless of domain.

Any VODS-conforming document can be processed by a generic VODS parser without knowing anything about the domain payload. Domain-specific parsers receive a VODS-valid document and additionally interpret the payload according to their own spec.

The Envelope

A VODS-conforming document is a JSON object. The following root-level fields constitute the VODS envelope. All required fields must be present. Domain specs add their own required and optional fields alongside these.

Minimal valid VODS envelope

{
  "vods_version": "1.0",
  "export_id":   "a3f8c2e1-04b7-4d9e-b221-7f3a09cc1d82",
  "export_date": "2026-03-09T14:22:00Z",
  "export_mode": "anonymous"
  // domain payload fields follow here
}

Anonymization Model

VODS defines two privacy modes for data exports. Every domain spec must honour these modes in how it generates and handles any identifiers in the payload. The export_mode field declares which mode applies to the entire document — mixed-mode documents are not permitted.

Tracked mode — pseudonym derivation

Applications implementing tracked mode must derive stable pseudonyms using a cryptographic approach that satisfies the following properties:

• Deterministic — the same input always produces the same output for the same program.
• Program-isolated — different destination programs produce different pseudonyms for the same entity.
• Non-reversible — the internal ID cannot be recovered from the pseudonym without the application's private salt.

The recommended approach is HMAC-SHA256 keyed with a per-program salt stored in the application's private data, never included in the export. The specific algorithm is left to the implementing application as long as the three properties above are satisfied.

Extensions

The extensions object provides a standardized namespace for organization-specific fields that fall outside the VODS envelope and outside the applicable domain spec. Extensions allow organizations to attach custom data to exports without polluting the core field space and without breaking conforming parsers that don't understand them.

Namespace convention

Each key in the extensions object is a namespace identifier chosen by the organization. The value is a JSON object containing that organization's custom fields. There is no central registry — organizations choose their own namespace keys. Short, lowercase, collision-resistant names are recommended.

{
  "vods_version": "1.0",
  "export_id":   "...",
  "export_date": "2026-03-09T14:22:00Z",
  "export_mode": "tracked",

  // domain payload here...

  "extensions": {
    "hfh": {                          // Hives for Heroes namespace
      "program_cohort": "Spring 2026",
      "mentor_id": "M-42"
    },
    "acme_research": {              // Another org's namespace
      "study_arm": "control"
    }
  }
}

Consumer requirements

• R1
  Ignore unknown namespaces. A conforming consumer must not reject a document because it contains extension namespaces the consumer does not recognize. Unknown namespaces are silently ignored.
• R2
  Do not modify extensions. When forwarding or transforming a VODS document, a processor must preserve extension data it does not understand. Stripping unknown extensions is not permitted unless the consumer explicitly declares itself a lossy transformer.
• R3
  Extensions do not override core fields. An extension namespace must not redefine any field defined in the VODS envelope or the applicable domain spec. Conflicts are resolved in favor of the core field.

Versioning Contract

VODS uses semantic versioning (MAJOR.MINOR) for the vods_version field. The contract governing what each version increment means is part of the standard itself.

Consumer version compatibility rule

A consumer that implements VODS vN.x must:

• Accept any document where the major version matches (e.g., a VODS 1.0 consumer must accept VODS 1.3 documents).
• Reject documents with a different major version and report the version mismatch clearly.
• Never reject a document solely because it contains fields the consumer does not recognize.

Conformance Rules

A document or application claims VODS v1.0 conformance by meeting all of the following rules. Partial conformance is not recognized.

• C1
  Envelope completeness. Every export document contains all four required envelope fields: vods_version, export_id, export_date, export_mode.
• C2
  Valid export_id. The export_id is a valid UUID v4, generated fresh for each export, and is never reused across exports from the same application.
• C3
  Valid export_date. The export_date is a valid ISO 8601 datetime string including timezone information. Date-only strings are not acceptable.
• C4
  Anonymization model honoured. The application correctly implements the anonymization behavior corresponding to the declared export_mode. No raw internal identifiers appear in any exported document regardless of mode.
• C5
  Extensions are namespaced. Any organization-specific fields appear under a named namespace key within the extensions object, not at the document root.
• C6
  Unknown fields tolerated. A conforming consumer does not reject a valid VODS document because it contains fields, enum values, or extension namespaces not defined in the version of the spec the consumer implements.
• C7
  Domain spec conformance is separate. VODS conformance does not imply conformance to any domain spec. Applications claiming conformance to OHDS v1.0, for example, must separately satisfy OHDS conformance rules in addition to these.

Building on VODS — Guidance for Domain Specs

This section is informational. It describes the expected pattern for domain specifications that build on VODS. It does not impose additional conformance requirements on VODS itself.

What a domain spec adds

• Its own version field (e.g., ohds_version, oceads_version).
• One or more payload arrays or objects containing the domain data.
• A minimum content rule — the conditions under which a document is considered non-empty and valid for the domain.
• Domain-specific field definitions, enum values, required vs optional field distinctions, and validation rules.
• Domain-specific guidance on how the anonymization modes apply to identifiers in the payload.

What a domain spec must not do

• Redefine or alter the meaning of any VODS envelope field.
• Change or add permitted values to export_mode.
• Place organization-specific or domain-specific optional fields outside of the extensions namespace.
• Require a VODS major version other than the one the domain spec declares itself to build on.

Example — OHDS v1.0 on VODS v1.0

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

  // OHDS domain fields (required by OHDS)
  "ohds_version":  "1.0",
  "inspections": [
    {
      "inspection_date": "2026-03-01",
      "apiary_ref":      "A-9f4c",
      "hive_ref":        "H-2a71",
      "colony_status":   "alive"
    }
  ],

  // Optional extension data
  "extensions": {
    "hfh": { "program_cohort": "Spring 2026" }
  }
}