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.

Why a new standard

Existing open data formats either target enterprise and institutional use cases, focus on semantic web interoperability, or define packaging without built-in privacy guarantees. VODS fills a different gap: a minimal, privacy-first data envelope designed for individuals, communities, and citizen science — where the person who generates the data controls how it is identified, shared, and used.

The anonymization model is not optional. Internal identifiers never leave the device. And because every Veydrin domain specification inherits the VODS envelope, these protections extend automatically to beekeeping data (OHDS), controlled environment agriculture (OCEADS), household financial data (VFDS), and any future domain built on this base.

The Envelope

A VODS-conforming document is a JSON object encoded as UTF-8 per RFC 8259. 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
}

VODS envelope with attribution

{
  "vods_version":        "1.0",
  "export_id":          "a3f8c2e1-04b7-4d9e-b221-7f3a09cc1d82",
  "export_date":        "2026-03-09T14:22:00Z",
  "export_mode":        "anonymous",
  "source_app":         "org.veydrin.apiara",
  "source_app_version": "2.0.0",
  "contributor_org":    "honey-for-humanity"
  // domain payload fields follow here
}

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

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 MUST NOT be produced.

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.

Deprecation policy

When a field, enum value, or behavior is scheduled for removal, it MUST first be marked deprecated in a MINOR version release. Deprecated features continue to function, but implementers SHOULD begin migrating to the replacement. Deprecated features MUST NOT be removed earlier than the next MAJOR version. Each deprecation notice MUST identify what replaces the deprecated feature.

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.
• MUST NOT reject a document solely because it contains fields, enum values, or extension namespaces 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. A machine-readable schema for automated validation is available at vods-v1.0.schema.json.

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

Security Considerations

VODS is a data format specification, not a transport protocol. It does not define wire-level security, authentication, or encryption. The following considerations apply to implementations producing or consuming VODS-conforming documents.

Transport and storage security

VODS does not include built-in integrity verification such as checksums or digital signatures. Applications requiring tamper detection or authenticity guarantees MUST implement these at the transport or application layer. Documents containing sensitive data SHOULD be transmitted over encrypted channels and encrypted at rest.

Extension field injection

The extensions object permits arbitrary nested values under namespace keys. Consumers MUST sanitize extension values before rendering them in user interfaces or passing them to interpreters. Unsanitized string values from extensions could enable cross-site scripting or injection attacks in downstream systems.

Pseudonym reversibility

In tracked mode, pseudonyms derived from weak or predictable salts may be reversible through brute-force or dictionary attacks, particularly when the space of internal identifiers is small. Implementations SHOULD use cryptographically random salts of at least 32 bytes. The anonymization model protects against casual re-identification but is not designed to resist a motivated adversary with access to auxiliary datasets. Applications handling high-sensitivity data SHOULD layer additional protections beyond what VODS requires.

Resource exhaustion

The VODS envelope places no size limits on the extensions object or on domain payload fields. Consumers SHOULD enforce reasonable limits on incoming document size, nesting depth, and array length to prevent memory exhaustion from malformed or adversarial input.

Identifier leakage

Conformance rule C4 prohibits raw internal identifiers in exported documents. However, VODS cannot enforce this at the format level — enforcement is the producing application's responsibility. Implementers SHOULD audit their export pipelines to verify that no internal database IDs, user account identifiers, device identifiers, or filesystem paths leak into exported documents.

Normative References

Changelog