OCEADS v1.0

Overview

OCEADS is a domain specialization of VODS (Veydrin Open Data Standard). Every OCEADS document is a valid VODS document. OCEADS adds the oceads_version field and the domain payload — grow_cycles, environment_logs, nutrient_logs, harvests, and the optional aquatic_module — on top of the VODS envelope.

Refer to the VODS v1.0 specification for the authoritative definition of envelope fields, the anonymization model, the extensions system, and the versioning contract. This document specifies only what OCEADS adds.

Cultivation systems in scope

Document Envelope

Every OCEADS document carries the VODS envelope (inherited) plus the OCEADS domain version field. At least one payload array MUST be present and non-empty.

Minimum content rule

An OCEADS document must contain at least one of: grow_cycles, environment_logs, nutrient_logs, or harvests. Any present array must be non-empty. A document with only an aquatic_module and no other payload is not valid OCEADS.

Grow Cycle Record

One record per cultivation run from start to finish. The grow_cycles array contains these records. A grow cycle is the top-level container that links environment logs, nutrient logs, and harvests together. All other records reference a cycle_ref to associate with a cycle.

Environment Log Record

One record per environmental measurement event. The environment_logs array contains these records. May be logged automatically by sensors (high-frequency) or manually by the grower (low-frequency). All fields except cycle_ref and logged_at are optional — include what the system actually measures.

Nutrient Solution Log Record

One record per nutrient solution measurement or adjustment event. The nutrient_logs array contains these records. Covers solution chemistry for all liquid-feed systems (hydroponic, aeroponic, aquaponic). Not applicable for fungal-only or fully passive setups; omit the array in that case.

Harvest Record

One record per harvest event within a cycle. The harvests array contains these records. A cycle may have multiple harvests (cut-and-come-again, staggered, or partial). Final harvest should be accompanied by the end_date on the grow cycle record.

Aquatic Module

The aquatic_module object is optional and applies only to aquaponic systems where fish or other aquatic organisms are part of the cultivation loop. When present, it contains a system_ref linking it to a grow cycle's system, plus tank condition records.

Aquatic module object

7.1 Tank log record

Full Example

{
  // VODS envelope
  "vods_version":  "1.0",
  "export_id":    "b7e3a1f2-09c4-4d8b-a332-8e4b20dd1c93",
  "export_date":  "2026-03-09T14:22:00Z",
  "export_mode":  "anonymous",

  // OCEADS domain
  "oceads_version":  "1.0",

  "grow_cycles": [
    {
      "cycle_ref":          "C-4f91",
      "system_ref":         "S-a2c3",
      "system_type":        "hydroponic",
      "start_date":         "2026-02-01",
      "end_date":           "2026-03-05",
      "cultivar":           "Lactuca sativa 'Outredgeous'",
      "substrate":          "rockwool",
      "grow_area_sqcm":     2400,
      "plant_count":        24,
      "photoperiod_hours":  16,
      "light_spectrum":     ["red", "blue", "white"],
      "light_intensity_umol": 250
    }
  ],

  "environment_logs": [
    {
      "cycle_ref":         "C-4f91",
      "logged_at":         "2026-02-15T08:00:00Z",
      "air_temp_c":        22.4,
      "humidity_rh":       65,
      "co2_ppm":           1100,
      "par_umol":          238,
      "root_zone_temp_c":  20.1
    }
  ],

  "nutrient_logs": [
    {
      "cycle_ref":          "C-4f91",
      "logged_at":          "2026-02-15T08:05:00Z",
      "ec_ms":             1.4,
      "ph":                6.1,
      "water_temp_c":      20.3,
      "do_mg_l":           7.8,
      "nutrient_brand":    "General Hydroponics Flora Series",
      "adjustment_action": "none"
    }
  ],

  "harvests": [
    {
      "cycle_ref":       "C-4f91",
      "harvest_date":   "2026-03-05",
      "harvest_type":   "full",
      "fresh_weight_g": 1840,
      "days_to_harvest":32,
      "quality_rating": "excellent",
      "flavor_rating":  5
    }
  ]
}

{
  // VODS envelope
  "vods_version":  "1.0",
  "export_id":    "c8f1b2a3-14d5-4e9c-b443-9f5c31ee2d04",
  "export_date":  "2026-03-09T14:22:00Z",
  "export_mode":  "anonymous",

  "oceads_version":  "1.0",

  "grow_cycles": [
    {
      "cycle_ref":    "C-8b02",
      "system_ref":   "S-f3d1",
      "system_type":  "fungal",
      "start_date":   "2026-02-10",
      "end_date":     "2026-03-01",
      "cultivar":     "Pleurotus ostreatus",
      "substrate":    "straw",
      "plant_count":  4   // inoculation blocks
    }
  ],

  "environment_logs": [
    {
      "cycle_ref":   "C-8b02",
      "logged_at":   "2026-02-18T09:00:00Z",
      "air_temp_c":  18.5,
      "humidity_rh": 92,
      "co2_ppm":     800
    }
  ],

  "harvests": [
    {
      "cycle_ref":       "C-8b02",
      "harvest_date":   "2026-02-28",
      "harvest_type":   "partial",
      "fresh_weight_g": 620,
      "days_to_harvest": 18,
      "quality_rating": "good"
    },
    {
      "cycle_ref":       "C-8b02",
      "harvest_date":   "2026-03-01",
      "harvest_type":   "full",
      "fresh_weight_g": 480,
      "days_to_harvest": 19
    }
  ]
}

{
  // VODS envelope
  "vods_version":  "1.0",
  "export_id":    "d9a2c3b4-25e6-4f0d-c554-0g6d42ff3e15",
  "export_date":  "2026-03-09T14:22:00Z",
  "export_mode":  "tracked",

  "oceads_version":  "1.0",

  "grow_cycles": [
    {
      "cycle_ref":    "C-aq-3e72",
      "system_ref":   "S-aq-b81f",
      "system_type":  "aquaponic",
      "start_date":   "2026-01-15",
      "cultivar":     "Beta vulgaris 'Bull's Blood'",
      "substrate":    "clay_pebbles",
      "plant_count":  32
    }
  ],

  "nutrient_logs": [
    {
      "cycle_ref":   "C-aq-3e72",
      "logged_at":   "2026-03-01T07:00:00Z",
      "ec_ms":       0.9,
      "ph":          7.2,
      "water_temp_c":24.1
    }
  ],

  "aquatic_module": {
    "system_ref":               "S-aq-b81f",
    "species":                  "Oreochromis niloticus",
    "tank_volume_l":           380,
    "stocking_density_kg_m3":  12.4,
    "tank_logs": [
      {
        "logged_at":    "2026-03-01T07:05:00Z",
        "water_temp_c": 24.0,
        "ph":           7.1,
        "do_mg_l":      6.4,
        "ammonia_ppm":  0.25,
        "nitrite_ppm":  0.05,
        "nitrate_ppm":  18.0,
        "fish_count":   45,
        "feed_g":       120
      }
    ]
  }
}

Conformance Rules

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

• A1
  OCEADS version declared. Every export includes "oceads_version": "1.0".
• A2
  Minimum content satisfied. Every export contains at least one non-empty array from: grow_cycles, environment_logs, nutrient_logs, or harvests.
• A3
  Cycle linking consistent. Every record in environment_logs, nutrient_logs, and harvests carries a cycle_ref that matches a cycle_ref present in grow_cycles within the same export. Orphaned records are not permitted.
• A4
  System linking consistent. If aquatic_module is present, its system_ref MUST match a system_ref present in grow_cycles within the same export.
• A5
  No null optional fields. Optional fields with no value are omitted entirely, not serialized as null.
• A6
  Anonymization honoured in payload. cycle_ref and system_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. Internal IDs are never exposed.
• A7
  Units are as specified. Temperature in °C, weight in grams, volume in liters or mL as specified per field, EC in mS/cm, PAR in µmol/m²/s. Do not substitute alternative units — convert before export.

Glossary

Controlled environment agriculture terminology used in this specification. Implementers who are not growers should reference this section when mapping field names to user interfaces.

Security and Privacy Considerations

OCEADS inherits the security considerations defined in VODS §8. The following are specific to controlled environment agriculture data.

Free-text field sanitization

The cultivar, nutrient_brand, nutrient_ratio, cycle_notes, harvest_notes, and log_notes fields accept arbitrary text. Consumers MUST sanitize these values before rendering them in web interfaces or passing them to other systems.

Operational inference from sensor data

High-frequency environment and nutrient logs can reveal operational patterns — facility operating hours, growth schedules, equipment capabilities, and production scale. In anonymous mode, applications SHOULD consider reducing log frequency or binning timestamps to limit facility fingerprinting.

Resource exhaustion

The environment_logs and nutrient_logs arrays may contain thousands of records from high-frequency sensor logging. Consumers SHOULD enforce reasonable limits on incoming document size and array length to prevent memory exhaustion.

Normative References

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

Changelog