Field Operations Shape

ESRI Shapefile is a generic geospatial vector data format.

Field operation is a recorded operation on a field, e.g., a seeding, fertilizing, spraying or harvesting operation.

This documentation is a reference for agricultural-specific shapefile bundles recommended to use for agrirouter-connected applications when passing field operations (aka work records).

Data Format

Bundle layout

The bundle is a zip archive describing one field operation. It holds up to two layers, each an ordinary ESRI shapefile — a set of four files sharing a basename:

<operation-id>.shp    # point-level layer — geometry
<operation-id>.shx    # point-level layer — shape index
<operation-id>.dbf    # point-level layer — attribute table
<operation-id>.prj    # point-level layer — coordinate reference system
summary.shp           # summary layer — field boundary geometry
summary.shx           # summary layer — shape index
summary.dbf           # summary layer — attribute table
summary.prj           # summary layer — coordinate reference system

A real bundle, for an application operation would look like this:

dd67f8c0-632c-43c1-8183-5f095b6bd699.dbf
dd67f8c0-632c-43c1-8183-5f095b6bd699.shp
dd67f8c0-632c-43c1-8183-5f095b6bd699.shx
dd67f8c0-632c-43c1-8183-5f095b6bd699.prj
summary.dbf
summary.shp
summary.shx
summary.prj

• Point-level layer — one feature per recorded sample, carrying the as-applied detail of the operation. Its basename is the field operation id, sanitized to ASCII. Always present.
• Summary layer — always named summary; one polygon feature per product/component, carrying field-level aggregate attributes. Present only when a usable field boundary is available for the operation; without one the bundle carries just the point-level layer's four files.

The two layers can be read independently, and the entry order within the zip is not significant.

Flat archive. All files sit at the root of the zip — there is no enclosing directory.

Column naming. DBF column names are uppercase in every layer, so the published schema uses one consistent casing throughout the bundle.

Summary layer

The summary layer carries the field boundary polygon together with a row of field-level summary attributes aggregated from the operation's measurements. There is one row per applied product/component: a single-product operation yields one row, while a tank mix repeats the same boundary geometry once per component. Operation-level columns (field, areas, speed, fuel, …) repeat across rows; the per-product material columns differ from row to row.

Conventions:

• All numeric values are metric, and each *_U column carries the unit of the value next to it (e.g. kg1ha-1, l1ha-1, seeds1ha-1).
• PRODUCT and CROP are mutually exclusive on a row: an applied input fills PRODUCT, while a seeding/harvest cultivar fills CROP.

The Example column shows one plausible value per column; the examples are illustrative per cell, not a single coherent row (some columns are Application-only, others Harvest-only, and PRODUCT/CROP never appear together).

The Enumeration column lists the complete set of values a column can take when that set is known in advance, and is left empty otherwise. Note that enumerations by design are not always exhaustive: a value may be provided by exporting system that does not appear in the list of this specification yet, in which case it is up to consumer to handle this gracefully.

* A unit token outside the listed set is possible but not expected; see Unit tokens below.

Unit tokens

Units are written as compact tokens rather than symbols: a token is a product of factors, where 1 separates factors and a trailing negative exponent marks a denominator. So kg1ha-1 is kilograms per hectare, l1ha-1 litres per hectare, km1hr-1 kilometres per hour, kg1m3-1 kilograms per cubic metre, ml1kg-1 millilitres per kilogram.

The bundle is metric: every unit token names a metric unit, and every numeric value is expressed in the unit its token names. The vocabulary is

Like the column enumerations, this vocabulary is not closed. A producer that cannot express a value in metric may emit it in its original unit, carrying that unit's token verbatim — so a consumer may encounter a token outside the table, and a value that is not metric. This is the one case where the "all values are metric" rule does not hold, and it is not expected in practice. A consumer should read the unit token rather than assume one and handle an unknown token gracefully.

Point-level layer

The point-level layer is the as-applied detail of the operation: one feature per sample recorded as the machine moved through the field, with a row of attributes describing what happened at that spot. The geometry is a point, or a small polygon for area-based machines. This is the operation's main shapefile, named after the operation id; the summary layer sits beside it in the same zip.

Unlike the summary layer, this layer has no fixed column set. Which columns are present depends on the operation type — Application, Seeding, Harvest or Tillage — and on the machine that recorded the operation. The tables below list every column that can appear, grouped by the operation type it belongs to. Treat the set as open: select columns by name, and expect neither every listed column to be present nor the listed ones to be all there are.

Rules that hold for the whole layer:

• Uppercase names. Column names are uppercase.
• Metric values. Every numeric value is in the metric unit given for its column in the tables below.
• Timestamp. TIME is the first attribute of every record, RFC3339 in UTC (see Timestamp below).
• Crop. For Seeding/Harvest, CROP holds the crop name as text (see Crop name below).
• Product width. PRODUCT is at least C(64) wide, matching the summary layer (see Product width below).

In the tables, Unit is the unit of the published value; — marks a column that carries no unit (text, id, timestamp). Type is the column's nominal type, which is not always the DBF field definition emitted — see below.

Column types

The Type in the tables below is nominal: it tells you what kind of value the column holds and roughly how big — text of some width, a small integer, a decimal number of a given precision. It is not a guarantee of the exact DBF field definition on disk, which may differ in width and decimal count.

What does hold:

• A column's kind is as stated: a column typed Character(n) holds text, and a column typed Number(n,d) or Double holds a number. Only widths and decimal counts may differ.
• Numeric columns are emitted as DBF numeric (N) or float (F) fields; both hold a decimal number written as text, and both should be parsed the same way.
• Character widths are floors, not fixed sizes: a column may be emitted wider than its nominal type, never narrower. PRODUCT is at least C(64) (see Product width below).

A consumer should read field definitions from the DBF header rather than hardcode them from these tables, and should not assume a column's width is stable across bundles.

Common columns

Present across operation types (exact membership still depends on the machine and operation):

Timestamp

TIME is the first attribute of every record and holds the sample timestamp as RFC3339 in UTC (e.g. 2021-04-28T11:49:31.714Z). Parse it as RFC3339. Where no timestamp is available for a sample, TIME is blank.

Optional weather/operating columns

Any of these may be present on any operation type:

Application columns

Nutrient-constituent columns, present based on the application type — applied/total/target/prescription rate and concentration of nitrogen (N), phosphorus (P₂O₅), potassium (K₂O) and ammonium (NH₄N):

Product width

PRODUCT names the same thing in both layers and carries it at the same width in both: at least C(64). One product name therefore fits identically wherever it appears in the bundle, and a consumer sizing a field for it needs only one number.

The width is a floor, not a fixed size: a PRODUCT column wider than 64 keeps its width. This is the only column with a width floor of its own; every other column takes the width its nominal type implies.

Seeding columns

Harvest columns

Constituent/quality columns, present based on the harvest type:

Crop name

For Seeding and Harvest, CROP holds the crop name as text (e.g. Corn). It is Character(64), the same type and width as the summary layer's CROP, so the column reads identically in both layers.

The crop is an operation-level value — one crop per field operation — so every sample in the layer carries the same name. The variety or hybrid is a separate value and has its own column, VARIETY. Where no crop name is available, CROP is blank.

Tillage columns

John Deere export implementation details

How the bundle above is produced from a John Deere Operations Center (JDOC) field operation.

Source material

For one JDOC field operation, John Deere provides a shapefile export together with a .json metadata sidecar. The sidecar carries, among other things, each column's original unit, the operation's crop as a top-level CropId/CropName pair, and the mapping from the machine index to machine/operator ids.

The two published layers have different origins:

• The summary layer is composed here. Its columns, types and metric units are defined by this document; its values are aggregated from the operation's measurements as reported by JDOC.
• The point-level layer is John Deere's own shapefile export, republished with the transformations below. Its column set and types are John Deere's and depend on the operation type. The point-level column tables list every column John Deere documents, and their Type column is John Deere's documented source type.

Source archive layout

John Deere's download nests the shapefile under a doc/ directory, names it with spaces and other special characters, and ships a {base}-Deere-Metadata.json sidecar alongside it. Restructuring it into the flat bundle described under Bundle layout means:

• taking the first complete .shp/.dbf pair, sorted by basename;
• renaming the layer to the field operation id, sanitized to ASCII;
• flattening the four layer files to the zip root, with no enclosing directory;
• dropping the metadata sidecar, after its units and crop name have been read;
• carrying over John Deere's .prj when the download has one, and otherwise writing the default WGS-84 WKT.

Geometry is copied verbatim; John Deere's coordinates are WGS-84 degrees.

Transformations applied to the John Deere export

A sample whose id does not match the sidecar's CropId — or an operation whose sidecar carries no crop name — yields a blank CROP.

Everything else is left alone: non-numeric columns and columns already in metric pass through untouched apart from the uppercasing, and a numeric column whose unit is not recognized is passed through unconverted.

Emitted DBF types

Each column is emitted in one of two ways.

Pass-through — every non-numeric column, every numeric column already in metric, and every numeric column whose unit is not recognized. John Deere's DBF field definition is re-emitted intact (same type, width and decimal count) and only the name is uppercased. PRODUCT is the exception: its width is raised to 64 when John Deere ships it narrower.

Converted — the numeric columns scaled to metric. Each is emitted as a DBF float (F), its width recomputed to fit the converted values and capped at 19, its decimal precision taken from John Deere's source precision with a floor of 3. A source Number(18,8) becomes F(w,8) with w ≤ 19; a source column that declared no decimals becomes F(w,3).

Timestamp precision. IsoTime carries millisecond precision, so the point-level TIME carries milliseconds; the summary layer's STARTDATE/ENDDATE are second-precision. Both are RFC3339 in UTC, as the data format above specifies.

Known unit normalization

Values are requested from John Deere in metric where possible; whatever comes back in another unit is converted on publish. Each column's incoming unit is read from the .json sidecar.

Recognized John Deere unit tokens and the metric token published in their place; the value is scaled by the same conversion. Note the spellings [m3], kg11000gal-1 and floz1ton-1:

Tokens that are already metric (e.g. m, kg, l, ha, kg1ha-1, l1ha-1, km1hr-1, seeds1ha-1, kpa, kg1m3-1, ml1kg-1) are typically passed through unchanged, and their columns count as pass-through for the purposes of Emitted DBF types. Note that cm is converted to m - one case where a metric unit is rescaled so that we have a consistent unit for the same dimension. John Deere sends cm for tillage depth measurements.

If John Deere sends a unit in neither set — not metric, not in the table above — the value is published unconverted and its original token passes through verbatim. Such a value may be non-metric, and its token falls outside the vocabulary in Unit tokens. It is expected that clients would handle this situation depending on the needs of their application.

Verified coverage

All four operations were test exported from a testing organization — Application, Seeding, Harvest and Tillage. A column marked verified below has been published from that real data; every other column in the format tables rests on John Deere's documentation alone, as at this time we were unable to simulate an operation that would produce it.

In all four captures both layers came out as shape type 5 (Polygon), the point-level layer included, and every bundle held all eight files.

Summary-layer row model

A JDOC single-product operation produces one summary row; a tank mix produces one row per component, repeating the boundary geometry and the operation-level columns. Application fills PRODUCT per component; Seeding and Harvest fill CROP from the operation's crop.