> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wiseyield.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Land hierarchy

> Farm → Field → Block → Tree/Plant — the four-level model behind every operational endpoint.

WiseYield models real farms as a **four-level hierarchy**. Each level corresponds to a different physical or economic invariant, and every operational endpoint attaches at the level it semantically belongs to — not "as deep as possible."

## The four levels

| Level            | Required?                                     | What it represents                        | Real-world example                             | Schema         |
| ---------------- | --------------------------------------------- | ----------------------------------------- | ---------------------------------------------- | -------------- |
| **Farm**         | Yes                                           | Top-level account boundary                | "Green Valley Farm"                            | `farms`        |
| **Field**        | Yes (since 2026-05-05)                        | Pump-/valve-bounded land area             | "North field, 4.2 ha, drip-irrigated"          | `fields`       |
| **Block**        | When variability inside a field exceeds noise | Variety / age cohort / management group   | "60 Medjool palms, 10×10 m grid, planted 2019" | `blocks`       |
| **Tree / Plant** | When asset value per plant ≥ tracking cost    | QR-tagged trunk for high-value perennials | "Date palm #P-0247, last pruned 2025-12-03"    | `block_plants` |

The UX uses **"Tree"** for orchards and **"Plant"** for non-tree crops; the schema name is `block_plants` in both cases.

## Why four levels

* A **field** is the smallest unit at which **infrastructure** is uniform — one pump, one solenoid, one drip line, one boundary fence.
* A **block** is the smallest unit at which **biology and management decisions** are uniform — same variety, same age, same fertigation program.
* A **tree** is the smallest unit at which **economics** are uniform — perennials worth €200–€2,000 each justify per-asset tracking; row-crop seedlings don't.

These are three different physical/economic invariants. Collapsing them produces wrong decisions: a single field-wide fertigation dose across heterogeneous soils either over-flushes the upslope (waste) or under-flushes the downslope (yield loss).

## When to use each level

### Field-level only is sufficient when

* Annual row crops with uniform variety across the field (wheat, corn, soy, cotton).
* Leafy greens and vegetables on irrigation-uniform beds.
* Smallholder farms where the field is the smallest practical decision unit.

### Use blocks when

* A field holds **multiple varieties** (e.g., Medjool + Barhi + Khalas date palms).
* Different **planting dates or age cohorts** in one field.
* **Soil or salinity variability** inside a field exceeds ±15%.
* **Intercropping**, alley cropping, or strip cropping — each strip is a block.
* Different **fertigation programs** even with the same variety.

### Use per-tree tracking when

* High-value perennials: date palms, avocado, mango, premium olive, citrus on rootstock blocks.
* **Pollination tracking** (date palm — one male tree services 40–50 females).
* **Disease quarantine** (red palm weevil, citrus greening — individual-tree decisions).
* **Insurance or asset registers** demand per-tree audits.
* **GAP-certified export operations** where traceability per tree drives price premium.

> Rule of thumb — per-tree tracking is justified when **(asset value × loss probability) > (tracking cost per tree per year, ≈ €0.10 with QR + mobile)**.

## The Operations Attachment Principle

Every operational record attaches at the level that owns it physically or biologically:

| Operation         | Attaches to                  | Why                                            |
| ----------------- | ---------------------------- | ---------------------------------------------- |
| Irrigation event  | Field                        | Pump / valve granularity                       |
| Fertigation event | Block                        | Variety / program granularity                  |
| Soil sample       | Field (Block if variability) | Soil moves with infrastructure boundaries      |
| Leaf sample       | Block                        | Tissue chemistry tracks variety + canopy stage |
| Vision analysis   | Block OR Tree                | Spatial reference must match decision unit     |
| Crop expense      | Crop or Field                | Inputs tied to a specific planting             |
| Farm overhead     | Farm                         | Cost spans every field equally                 |
| Income            | Crop or Field                | Revenue tied to a specific harvest             |

Endpoints accept and require `farmId`, `fieldId`, `blockId`, or `cropId` according to this principle. Passing an attachment at the wrong level returns `400 VALIDATION_ERROR`.

## "Zone" is reserved

WiseYield deliberately does not use **"Zone"** for the block layer. "Zone" has reserved meanings in agriculture:

* **Irrigation zone** — a hydraulic control unit.
* **Management zone** — a precision-ag / VRT prescription region (NDVI, EC, yield zones).
* **Climatic zone** — USDA Plant Hardiness Zone, agro-ecological zone.

When WiseYield ships variable-rate technology (VRT) and prescription maps, the prescription regions will be called **Zones** — distinct from Blocks. This separation is intentional.

## The principle in one line

> **Field is the unit of infrastructure. Block is the unit of agronomy. Tree/Plant is the unit of asset value. Manage at the level where variability lives — never higher.**

## See also

* [Trust badges](/concepts/trust-badges) — how recommendations are scoped to the level whose data backs them
* [Error reference](/concepts/errors) — codes returned when attachment level is invalid