Working with Crop Zones 🌽

Overview

Crop Zones enable you to track field-specific agronomic data within production seasons, providing detailed temporal and spatial context for each field's usage.

Cardinality summary

• Workspace ➜ 1..* Organizations
• Organization ➜ 1..* Properties
• Property ➜ 1..* Fields
• Field ➜ 0..* Crop Zones (max 1 per Season)
• Season ➜ 0..* Crop Zones (max 1 per Field)
• (Field, Season) pair ➜ 0..1 Crop Zone (UNIQUE)

Workspace
└── Organization
    ├── Seasons 1..*
    └── Properties 1..*
      └── Fields 1..*
        └── Crop Zones (0..1 per Season)

The Crop Zone references:

• season_id (season period context; see Seasons Guide)
• field_id (land base unit; see Fields Guide)
• property_id (inferred from the field for permission scoping; see Properties Guide)

Key Concepts

Uniqueness & Integrity Rules

Attempting to create a second crop zone for the same Season + Field returns a conflict (409) or validation error. Query first or use idempotent logic.

Business Rules (Create & Update)

Permissions

• Caller must have create permission for every involved organization (derived from each property's company) or request is rejected.

Existence & Ownership

• All referenced properties, seasons, and fields must exist.
• Each field must belong to the referenced property; mismatches fail validation.
• Season and property must belong to the same company.
• Fields must be available (not archived / blocked).

Duplicate Handling & Soft-Deleted Reuse

• (season_id, field_id) uniqueness enforced; creation path reuses an existing (even soft-deleted) crop zone record (reactivates & overwrites data) instead of inserting a new row.

Geometry

• If payload includes geometry (no geometry_id) a new geometry is persisted; calculated area stored.
• Geometry MUST be a valid GeoJSON Polygon: WGS84 [longitude, latitude], first and last coordinate identical, no self-intersections, coordinates within [-180..180, -90..90].
• If geometry is omitted today no automatic derivation occurs (planned future enhancement: derive from field geometry when absent).
• On update, existing geometry reference retained unless a new one is supplied.
• Spatial & temporal overlap checks run at property level; field-level collision checks ensure no active overlapping zones for same field.

Varieties & Agronomic Info

• If season has a crop_id, any variety IDs must exist in the crop's catalog.

Temporal Adjustments

• On update the new period is applied before validations so overlap checks use incoming dates.
• After create/update, affected season start/end may be recomputed (aggregate across its crop zones / land scope).

Batch Transaction

• Each batch is atomic: any failure aborts all creates/updates.
• Preloads: existing crop zones (by property/field), previous versions (for update), seasons, properties, fields, geometries.

API Documentation

For complete API reference including request/response schemas, authentication, and interactive testing, visit:

📚 Crop Zones API Documentation - Interactive API documentation with request/response examples

Available Endpoints

Best Practices

Error Codes

Detailed (non-exhaustive) errors surfaced during create & update flows. Some codes listed for completeness though not always triggered in standard paths.

Permission / Auth

Property

Season

Crop Zone

Geometry & Spatial / Temporal

Generic / Other

Next Steps

• Seasons Overview →
• Fields Reference →
• Properties Reference →