Field creation and replacement

Using this endpoint, client applications can enable users to create canonical FieldIDs for their own fields by providing the geometry. This is intended to be used in a few scenarios:

1. the system does not yet already have the field registered
2. the layout of the land has changed (e.g. what was two fields is now one, or vice versa)
3. to overwrite erroneous fields with new ones

Users receive a canonical ID, in exchange for specifying the field's geometry. The new/updated geometry is made available to all Global FieldID users.

Please note: this endpoint is used to register fields only, editing the public layer of stable field identifiers, whose geometries do not overlap. To instead make minor updates to a field or to register other types of boundary such as farms, cadastral plots, proprietary areas of interest etc, see these other endpoints:

• POST /boundaries: see registering custom shapes
• PATCH /fields/{id}: see field boundary updates
• DELETE /fields/{id}: see removing fields

The Global FieldID system maintains a consistent non-overlapping map of fields which authorized client applications can edit. The API enforces that new fields do not create spatiotemporal overlaps with existing fields, and by default will reject such requests. There are several ways client applications can deal with overlaps:

• Correct the input boundary (e.g. ask the user to edit/redraw it)
• Adjust or remove overlapping fields before resubmitting
• The autoedit option will make minor edits to the input boundary to make sure it 'fits' into the existing map. This is useful for fixing accidental overlaps along the edges of neighbouring fields.
• The autoreplace option 'expires' existing overlapping fields, overwriting the map with a new field. This is equivalent to performing DELETE on each existing field in a single atomic action. It is useful for correcting erroneous data, or major boundary changes such as merging or splitting fields.

The autoedit and autoreplace parameters can be used together. The logic is explained in more detail below.

Prerequisites

Please note: write access to the API is available on request. Creating and updating fields is intended only for client applications with end users, who are able to confirm that the input data is a valid representation of a canonical field boundary.

Before granting access we will discuss with you how to ensure your users understand the implications of updating the Global FieldID map of fields. We will also assign you a unique source name to be used in input to the write endpoints, which identifies your application as the origin system of the boundary.

Limitations

At present this endpoint is intended for operating on individual fields, i.e. creating a single field or splitting a single field into a few smaller ones. The ability to register large datasets is not yet public; in the meantime please contact us if your use case involves registering large numbers of fields.

Input

Requests to this endpoint must contain a JWT Token containing the create:fields scope.

The API accepts an input payload in JSON format, containing an object or array of objects for each field. Each object should contain the following data:

• A GeoJSON Feature under the active boundary key, which represents the “boundary according to the source”. This object matches the input payload to POST /boundaries endpoint. It contains:

  • An id property for the identifier that has been assigned to the boundary by the source. Please note that this identifier is only used as a reference (i.e. what the source calls the boundary, not its canonical ID. The API will deduplicate and assign its own unique IDs to fields, geometries and features (see GFID identifiers);

  • Any custom source-defined properties the client wishes to register with the geometry. Only number, string, boolean and null values are supported. They will be stored along with the other provided data and may be used to search for boundaries/fields;

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

  • GFID-defined optional metadata;

  • GFID-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;

• Optional field metadata:

  • Name and description of the field;

  • effective_from: this is the date from which the field is active. If empty, the default value is now. Creation of fields is supported even when setting an "effective_from" date in the past, or in the future. 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 canonical "default layer" of field boundaries. For further details, please refer to the section below. The default value is false.

  • autoreplace: boolean parameter that enables you to specify whether the system should set to expire the existing field boundaries that would otherwise overlap with the field boundary about to be created, thus causing the creation process to fail. The default value is false.

Output

The API will return a JSON object (or array of objects if the input was also an array). Each object contains these properties:

• global_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 at least one boundary or even multiple if the field is represented by different boundaries along its time range of validity.

How the logic for field creation works

The API will carry out a number of checks, before creating both a boundary (if one doesn’t exist already for the input geometry) and a field.

Basic checks and corrections are performed to ensure that the input geometry is a valid.

After this, the geometry of the input boundary i.e., the “boundary according to the source”, is checked against surrounding field boundaries to identify and quantify possible overlaps and ensure that the creation of the new field does not violate the “zero-overlaps” constraint of the canonical “default layer" of field boundaries:

• If the input boundary geometry does not overlap with any of the surrounding fields, the creation of the field will be successful;

• If the input boundary geometry overlaps with any of the surrounding fields, the outcome (success or failure) of the field creation depends on the extent of overlap(s) - if they are above or below threshold -and on the input values of the “autoreplace” and “autoedit” parameters. The below table describes all the possible scenarios:

In case of success:

• A “boundary according to GFID” is created and assigned a Global BoundaryID. 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;

• The “boundary according to the source”, as provided in input with its untouched geometry, is stored as a boundary reference and linked to the “boundary according to GFID”. This linkage allows to keep track of the fact that the “boundary according to GFID” exists also in the source premises. Except for the GFID-defined mandatory metadata, all the input data representing the “boundary according to the source” will be stored in GFID system as part of the “boundary according to GFID“;

• A field is created and assigned a Global FieldID;

• Field and “boundary according to GFID” are linked and their relationship is set to start from the “effective_to“ date defined in input and to last until infinity;

In case of failure:

• The endpoint returns an error that explains why the creation of the field was unsuccessful.

Additional considerations for a successful creation of a field

As mentioned, the creation of fields is supported even when setting an "effective_from" date in the past or in the future. Indeed, the above-described logic to check overlaps works on a spatiotemporal basis - it is applied considering the overlaps that the input boundary has with the fields existing from the time when the new field would start to be active. The design principle followed is to support registering a historical view of fields (i.e. you can publish fields as they were in the past) and changing a future view that has not yet come to pass, but not changing the history of an existing field. This is because it would create conflicts for other users. If there exists already a field, it can only be invalidated 'as of now'.

Timeline rules for a successful creation of a field are the following:

• “Past can’t be updated but can be created from scratch“

  • If the effective_from date of the input field is in the past (before now) and ahead of the effective_from date of another field existing in the same area, then the creation of the field will fail even when “autoreplace” is set to true.
    
    
    
  • On the other hand, if there is not already a field active during the period between the effective_from and effective_to dates, a field will be created.
    
    
    

• “Present/future can be updated“

  • If the effective_from date of the input field is now or in the future and the existing field has an active boundary dur, then the active field will be trimmed and set to expire as of this date, while the new field will have validity starting from the effective_from until infinity.
    
    
    
  • This also implies that any existing field that would start to get active after the effective_from date will be set to expire i.e. field C in the picture is deleted.
    
    
    
    
    

Contextual considerations

• The boundary provided as input to this endpoint becomes part of the “default layer of field boundaries”, updating the primary record of the field for all users. The geometry of boundaries used in this way are always made available, and cannot be removed - it is not possible to update or create a field and keep it hidden from other users at the same time. It is therefore important that applications ensure end users are aware of these implications and have the legal right to make the boundary geometry available. Otherwise, we suggest you submit an alternative boundary. In the future; the API will have the functionality to register a standalone boundary, which can be kept “private”, and shared only with specified recipients. This feature will provide an alternative to creating a new field, or updating an existing one;

• As described in the above section, the input geometry may be subject to automated corrections if it overlaps with surrounding active fields below a certain threshold (while for overlaps above threshold the creation of the field will fail). The corrections are applied to ensure that the “parts“ of the input field causing the overlaps are cut out;

• As described above; the “autoreplace” feature is considerably powerful, since it can result in the deletion of existing fields. For this reason it is your responsibility to activate it only if you are sure that your “view“ is more accurate than what already exists in the system.