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

# Fields Overview

> How Leaf organizes field data using the Grower/Farm/Field hierarchy, how boundaries work, and how fields sync from John Deere, Climate FieldView, and CNHi.

Leaf organizes agricultural land data into a three-level hierarchy: Grower → Farm → Field. Fields carry the boundary polygons that drive everything else in Leaf, from field operations to satellite imagery.

## The Grower / Farm / Field hierarchy

Leaf uses a Grower/Farm/Field structure borrowed from how providers like John Deere organize data:

* **Grower** — Represents the data owner. In Leaf, a grower maps to a Leaf user (the entity that holds provider credentials). When you connect a John Deere account, Leaf imports the "Client" entities as growers.
* **Farm** — A grouping of fields under a grower. Farms are optional in Leaf. You can create fields without assigning them to a farm.
* **Field** — A single parcel of land, identified by a field ID. Each field has one active boundary at any time. Machine files that Leaf merges into field operations are tied to fields through their boundaries.

Growers and farms are primarily organizational. The field boundary is where the real work happens: it defines the geographic extent used for clipping operations, triggering satellite imagery, and calculating area.

## How boundaries work

Every field can have zero or more boundaries, but only one is active at a time. The active boundary is the one Leaf uses for spatial operations.

When you update a boundary, the previous one is not deleted. It becomes inactive, and Leaf keeps a full history of all boundaries ever associated with a field. Boundaries are GeoJSON `MultiPolygon` geometries.

Each boundary has a `status` that tracks its lifecycle:

| Status                 | Meaning                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `ACTIVE`               | Current boundary in use                                                            |
| `INACTIVE`             | Replaced by a newer boundary                                                       |
| `OUTDATED_ON_PROVIDER` | Was edited on the provider side; Leaf created a new boundary to reflect the change |
| `DELETED_ON_PROVIDER`  | Was deleted on the provider; Leaf keeps the historical record                      |

Leaf validates boundary geometry on creation. If a provider sends an invalid geometry (self-intersections, too few points, etc.), the boundary is stored with a `validity` flag indicating the issue. You can enable `automaticFixBoundary` in your configuration to have Leaf attempt automatic geometry repair.

## How fields sync from providers

When you connect a provider to a Leaf user, Leaf automatically pulls the grower, farm, and field structure from that provider. This happens on the first sync and at least every 24 hours afterward.

Each synced field carries metadata from the provider: `providerName`, `providerFieldId`, `providerFieldName`, and `organizationId`. If the same physical field exists in multiple providers, Leaf detects the overlap and creates a merged field that links back to the originals.

Field types:

* `ORIGINAL` — A field that came from a single provider or was manually created.
* `MERGED` — A field Leaf created by detecting overlap between two or more original fields.

If `fieldsAutoSync` is enabled (the default), syncing happens automatically. You can disable it and trigger syncs manually via `POST /users/{leafUserId}/fields/sync`.

If `customDataSync` is enabled, Leaf initially fetches fields in `PREVIEW` mode: metadata only, no boundary geometry. You then selectively enable fields for full processing using the enable sync endpoint.

## Common use cases

* **Import field boundaries from a provider**: Connect John Deere Operations Center, Climate FieldView, or CNHi and let Leaf auto-sync field boundaries for each grower.
* **Create field boundaries manually**: Upload shapefiles, GeoJSON, or KML through the field upload service when growers don't use a cloud provider.
* **Detect field overlaps**: Use the intersection endpoint to find which fields overlap a given geometry — useful for matching uploaded data to existing fields.
* **Control sync scope**: Enable `customDataSync` to preview fields before committing to full boundary processing, keeping billing predictable.

## What to do next

* [Managing Fields](/fields/managing-fields) — Create, update, delete, and sync fields.
* [Uploading Boundaries](/fields/uploading-boundaries) — Create field boundaries from shapefiles, GeoJSON, or KML.
* [Growers](/fields/growers) — Manage the grower layer of the hierarchy.
* [API Reference: Fields](/api-reference/fields) — Full endpoint reference for fields, boundaries, and farms.