Field boundary replacement

Input

The API accepts an input payload in JSON format.

The JSON will contain the following data:

• A GeoJSON feature under the “boundary” key which represents the “boundary according to the source”. This object matches the input payload to POST /boundaries endpoint and it is not mandatory. It contains:

  • The unique identifier or ID that has been assigned to the boundary by the source. Please note that Varda do not use this ID when creating either a BoundaryID or FieldID;

  • Source-defined properties. Only number, string, boolean and null are supported. They will be stored along with the other provided data;

  • The geometry of the boundary. Two types are supported, Polygon and MultiPolygon;

  • Varda-defined optional metadata;

  • Varda-defined mandatory metadata:

    • Source name: it is a unique name used to indicate the source of the data. Creation of a source for your boundaries can be done upon request;

• “effective_from”: this is the date from which the new boundary is active. If empty, the default value is now. By default the field will be considered active indefinitely;

• “autoedit“: boolean parameter that allows you to specify whether the system, in case of overlaps with existing field boundaries, can modify your input geometry to make it fitting into the "Varda default layer of field boundaries." For further details, please refer to the section below. The default value is false.

Output

The API will return:

• “field_ID“: the Global FieldID assigned to the newly created field;

• “active_boundary_ID“: the Global BoundaryID of the active boundary of the field. It may be empty if the field is not currently active;

• “created_at“: the date when the field got created in the system;

• “effective_from”: the date from which the field is active;

• “effective_to“: the date until which the field is active;

• “boundaries“: the list of boundaries of the field. The list contains the boundaries that delineated the fields along its entire time range of validity.

Checks prior to update of field boundary

The API will carry out a number of checks before proceeding with the update of the field boundary, as described below.

Check on geometries similarity

For the update to be successful, the input boundary needs to be “similar” to the current field boundary. The evaluation of the similarity is based on the IoU (Intersection over Union) metric. If the IoU is below a certain threshold i.e. the input and the current field boundaries are too dissimilar, the update will fail because the system considers your request as a mayor change that can’t be achieved preserving the existing FieldID. (You can still accomplish your change using the POST /fields endpoint instead).

Check on the input geometry

The input geometry needs to pass all the validations in place for boundaries of fields i.e. it has to be a valid geometry with an area within the permitted range.

Check on the time range of validity of the field to be updated

• If the field is a “past field“ i.e. its effective_to date expired in the past, the field can’t be subject to any update;

• if the field is a “current field“ i.e. its time interval of validity includes the current timestamp, then:

  • the current active boundary can be replaced from now onwards i.e. the active boundary is set to expire now and the new active boundary will become the one in input from now till infinity;

  • timeline of a field can be extended to infinity by providing the current active boundary in input;

• If the field is a “future field“ i.e. its time range of validity starts in the future, then:

  • its “effective_from” date can be brought either:

    • backward (up until now);

    • forward (to another date in the future);

  • new boundaries can be defined in the future but without generating gaps in timeline i.e. the new boundary validity starts when the last boundary in timeline expires.

Check on effective_from in input

• The input effective_from date must be bigger than current timestamp.

Check on the overlaps of the input geometry with existing surrounding fields

• If the input boundary overlaps with any of the surrounding fields above threshold, the update will not take place as the “zero-overlaps” constraint of the “Varda default layer of field boundaries” would be violated;

• If the overlap(s) with surrounding field(s) is below threshold, the update will be successful only if the “autoedit“ input parameter is set to true, thus allowing the system to cut out from the input geometry, the parts that cause the overlaps.

Other checks

• The input geometry cannot be already associated to another field;

• If the field has been modified by another request concurrently, the client needs to retrieve latest field before proceeding with update.

How the updating of a field boundary works

If any of the above constraints is not satisfied, the update of the field boundary fails and the endpoint returns an explanatory error.

If the constraints are satisfied:

• A boundary gets created and a Global BoundaryID is assigned to it. The geometry of this boundary is either exactly what the client provided in input or the modified version of it to make it overlap-free. If the system contains a boundary with an exact match to the input geometry, this point is skipped;

• A boundary reference gets created and a UUID is assigned to it. The boundary reference is linked to the boundary. Except for the Varda-defined mandatory metadata, all the input properties will be stored in GFID system as part of the boundary reference;

• The field and the boundary are linked and their relationship is set to start from the “effective_from“ date defined in input and to last until infinity, while the existing boundary will be set to represent the field until the new boundary becomes the representative one.