OPDS v1.0

Overview

OPDS is a domain specialization of VODS (Veydrin Open Data Standard). Every OPDS document is also a valid VODS document. OPDS adds the opds_version field and the domain payload arrays on top of the VODS envelope. Four record types are defined: plantings (what was established, where, and in which layer), observations (protracted observation of guild state and succession), harvests (yield from the system), and guilds (the polyculture designs that group species by function). Refer to the VODS v1.0 specification for the envelope fields, the anonymization model, the extensions system, and the versioning contract. This document specifies only what OPDS adds.

Permaculture is a design discipline built on observation over time, on stacking plants into functional layers, and on guilds where each element serves many functions and supports its neighbours. OPDS is shaped to record that practice rather than a row-crop calendar: a guild is a first-class record, layer and succession are first-class fields, and observation is treated as data worth keeping, not a note in the margin.

Scope

OPDS covers the records a permaculture or food-forest practitioner keeps while designing and tending a living system: what was planted, what has been observed over time, what was harvested, and how species are grouped into guilds. It is intended for home-scale and community-scale sites, citizen-science sharing, and app-level interchange.

OPDS does not try to be: a farm-management platform, a species or cultivar catalogue, a mapping or GIS format, a soil-laboratory result format, or a design-drawing exchange. It records observations and events, not the design drawings themselves. Broadacre row-crop agriculture is served by ADAPT and ISOBUS; soilless and controlled-environment cultivation is served by OCEADS; beekeeping is served by OHDS. Water earthworks, sectors, and detailed soil chemistry are candidate extensions for a later version and are out of scope for v1.0.

The layer vocabulary

Several records use a layer field naming the vertical layer of a food-forest system. The permitted values are: canopy, understory, shrub, herbaceous, groundcover, root, vine, aquatic, fungal. Implementations MUST NOT invent layer values; a system element that does not fit is recorded without a layer.

Document Envelope

Every OPDS document begins with the VODS envelope (inherited) followed by the OPDS domain version field.

Minimum content rule

An OPDS export MUST contain at least one non-empty array from: plantings, observations, harvests, or guilds. An envelope with no record arrays is not a meaningful export and MUST be rejected.

Location and privacy

Records MAY carry an opt-in coordinates object, {"lat": number, "lon": number} in WGS 84. In anonymous mode, coordinates MUST be coarsened to at most one decimal degree (roughly a ten-kilometre cell), and free-text notes SHOULD be stripped. Home-site location is sensitive; see §9.

Planting Record

One record per planting event. The plantings array contains these records. A planting establishes a species at a location, in a layer, and optionally as part of a guild.

Observation Record

One record per observation event. The observations array contains these records. Protracted observation is the heart of permaculture practice, so an observation carries the state of a guild, its succession stage, and the functions seen at work, not just a note.

Harvest Record

One record per harvest event. The harvests array contains these records. Tracks yield from the system so that a design's productivity can be seen over time.

Guild Record

One record per plant guild. The guilds array contains these records. A guild is a group of species chosen so that each supports the others, and it is the design unit that distinguishes permaculture from a bed of monocultures. A guild record names the group and its members, and the functions each member serves.

Full Example

An anonymous export with one of each record type. It validates against the OPDS v1.0 schema.

{
  "vods_version": "1.0",
  "export_id": "a3f8c2e1-04b7-4d9e-b221-7f3a09cc1d82",
  "export_date": "2026-03-09T14:22:00Z",
  "export_mode": "anonymous",
  "opds_version": "1.0",
  "guilds": [
    { "guild_id": "g1", "name": "Apple guild",
      "functions": ["nitrogen_fixer", "pest_confuser", "pollinator_attractor"],
      "members": [
        { "species": "Malus domestica", "role": "canopy fruit", "layer": "canopy" },
        { "species": "Allium sativum", "role": "pest_confuser", "layer": "groundcover" },
        { "species": "Symphytum officinale", "role": "dynamic_accumulator", "layer": "herbaceous" }
      ] }
  ],
  "plantings": [
    { "planting_date": "2026-03-01", "species": "Malus domestica", "common_name": "Apple",
      "planting_ref": "p1", "layer": "canopy", "guild_ref": "g1", "zone": 2, "propagation": "transplant" }
  ],
  "observations": [
    { "observation_date": "2026-06-15", "subject": "guild", "guild_type": "apple guild",
      "layer": "canopy", "succession_state": "early_succession",
      "functions_observed": ["nitrogen_fixer", "pollinator_attractor"], "health": "thriving",
      "planting_ref": "p1" }
  ],
  "harvests": [
    { "harvest_date": "2026-09-20", "crop": "Apple", "quantity": 8.5, "unit": "kg",
      "planting_ref": "p1", "guild_ref": "g1" }
  ]
}

Conformance Rules

An application claims OPDS v1.0 conformance by satisfying all VODS v1.0 conformance rules (see VODS spec §6) and the following OPDS-specific rules. A machine-readable schema for automated validation is available at opds-v1.0.schema.json.

• O1
  Version field present. Every OPDS document MUST carry opds_version with a value whose major number the consumer recognises.
• O2
  Minimum content satisfied. Every export MUST contain at least one non-empty array from plantings, observations, harvests, or guilds.
• O3
  Controlled vocabularies honoured. The layer, propagation, subject, succession_state, health, and unit fields MUST use only their defined values. A value that does not fit is omitted, not invented.
• O4
  References resolve within the document. A guild_ref SHOULD match a guild_id, and a planting_ref on an observation or harvest SHOULD match a planting_ref on a planting, in the same export. A dangling reference MUST NOT cause a consumer to reject the document; it is retained and treated as unresolved.
• O5
  Anonymous mode floor. In anonymous mode, coordinates MUST be coarsened to at most one decimal degree, and an implementation MUST NOT emit a home-site identifier that a third party can resolve to an address.

Glossary

Security and Privacy Considerations

Home-site location

A permaculture site is usually someone's home. Precise coordinates, a resolvable site identifier, or a photograph with embedded location can disclose where a person lives. In anonymous mode, coordinates MUST be coarsened (§3, O5), site identifiers MUST be pseudonymous, and implementations SHOULD strip embedded location metadata from any referenced photo.

Free-text field sanitization

The notes, description, and name fields are free text and can carry personal information a user did not mean to publish. In anonymous mode these SHOULD be omitted; when retained they MUST be treated as untrusted input by any consumer that renders them.

Inference from records

A sequence of plantings, harvests, and observations can reveal a household's food supply, absences, and routines. Consumers aggregating OPDS data SHOULD avoid re-publishing record-level detail tied to a single pseudonymous site in a way that re-identifies it.

Known Limitations

• Design drawings are out of scope. OPDS records observations and events, not the map or the design plan. Two sites with identical records can have very different layouts.
• No water or earthworks records. Swales, ponds, and sector planning are not modelled in v1.0. They are candidate additions for a later version.
• Species identity is free text. OPDS does not bind to a taxonomic authority. A consumer that needs canonical taxa must resolve species strings against an external database.
• References are advisory. Cross-record references (O4) are checked only within a single export and are not required to resolve, so a partial export remains valid.

Normative References

Changelog