Creation of public or private custom shapes in GFID

GFID is designed principally around providing an industry-wide common identifier and vector polygon for a field, and provides users with the facility to access, create and edit them. However, sometimes it is useful to obtain a common ID for a specific area of land related to the field, without changing the definition of the field itself. Examples include:

• a specific area within a field used for a field trial or regenerative agriculture agreement

• the specific boundary generated by a planting or application operation, that may cover only part of, or more than one, field

• a farm boundary

• an alternative representation of the field, to provide a link with a third party ID (e.g. the field according to the government)

To allow users to model and identify these “custom shapes“, GFID system uses the “boundary” concept. A boundary which defines a custom shape differs from a field boundary because it is not explicitly linked to a field: although a field always has a boundary defining its spatial location, there can also be any number of other registered boundaries.

A custom shape does not have to meet any constraint to which a field boundary is subject, except being a valid geometry i.e.: custom shapes can be as big/small as needed and they can overlap with other custom shapes and field boundaries in any shape or form.

By default, a boundary representing a custom shape is made part of the “Open Registry” of boundaries, meaning that any user/client of GFID will be able to see the boundary and its geometry.

The GFID system supports also the “Private Registry”: boundaries which can be created but kept private and visible only to designated organisations. A detailed explanation of how the “Private Registry” is supported can be found in the below section “Discoverability and visibility of a custom shape“.

Prerequisites

Please note: write access to the API is available on request. Before granting access we will discuss with you how to ensure your users understand in which circumstances is relevant to create custom shapes. We will also assign you a unique source name to be used in input to the write endpoints.

Discoverability and visibility of a custom shape

The permissions of a boundary are assigned by the creator of the custom shape at creation time and are defined at tenant level. Tenant is synonymous of “organisation”. So, if tenant A assigns special permissions to tenant B on a certain boundary, it means that all the users and clients under tenant B will benefit from the same rights on that boundary.

• If the creator of the boundary wants to restrict access to the boundary to designated tenants, they have to specify, in the input payload, the type of permission along with the identifier of the tenant to which they wish to assign the permission, or “all“ to assign the permissions to all tenants at once;

• If the creator of the boundary omit the input permissions object, the default is to grant the ‘view’ permission to all tenants”, analogous to set permissions object of {“all”: “view”}.

Permissions are of three types, from the most to the least restrictive : “discover”, “view”, “manage”.

The “manage” permission is automatically assigned to the tenant who creates a custom shape boundary. As a “manager”; this tenant can then designate other tenants to have “discover”, “view”, or even “manage” permissions. Once designated; any tenant with “manage” permissions can update permissions for a boundary.

Input

The input payload is a GeoJSON Feature:

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

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

• Under properties:

  • Varda-defined mandatory metadata:

    • Source name: a unique value issued by Varda that indicates the data source. Creation of a source for your boundaries can be done upon request;

  • Varda-defined optional metadata;

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

  • permissions optional object to grant to other tenants rights on the boundary. It is a "<tenant_id>":"<permission_value>" string pairs encoded in a JSON object where:

    • tenant_id: tenant ID to which the specific permission will be granted. Reserved keyword "all" meaning all tenants. One’s tenant_id can be discovered calling the GET /info endpoint;

    • permission_value: one of the following:

      • discover: the specified tenant can discover the boundary in search results but no geometry information will be returned;

      • view: same as discover plus geometry will be returned;

      • manage: same as view plus the varda:permissions object will be returned in endpoint responses (where available) and permissions editing will be enabled.

Examples on how to set up permissions

Let us assume that in all the examples below tenant A is the creator of the custom shape. (It implies that Tenant A will automatically acquire “manage“ permissions on the boundary).

Output

The output payload is a GeoJSON Feature containing a boundary:

• "id": the UUID assigned by GFID to the newly created boundary;

• "properties":

  • “centroid”: the coordinate of the centroid of the boundary which is not guaranteed to be inside the boundary (e.g. in polygons with a ring shape);

  • “representative_point”: the coordinate of the representative point of the boundary which is always guaranteed to be inside the boundary;

  • "area": the area of the boundary and its unit of measurement;

  • "perimeter": the perimeter of the boundary and its unit of measurement;

  • “country_iso_codes”: an array containing the ISO codes of the countries to which the boundary belongs. A boundary belongs to a country if the representative point of the boundary falls within the boundary of that country. If the representative points falls within a disputed area, the boundary is considered to belong to all the countries under dispute.

  • "geometry": the geometry of the boundary represented as a MultiPolygon;

  • “boundary_references”: an array containing the linked boundary references. The array contains multiple objects if the exact same geometry got already submitted to GFID system with different metadata (by one or many sources - more information in the section below);

  • “boundary_relationships”: an array containing the GFID boundaries overlapping with the input, along with metrics to quantify the overlap. For each boundary:

    • “boundary_id”: the ID of the overlapping boundary;

    • "intersection": percentage of intersection of the input boundary with the existing one;

    • "intersection_area": area of intersection of the input boundary with the existing one in square meters;

    • "iou": Intersection-over-union, which is the intersection area divided by the union area of the two boundaries;

  • "field_relationships": an array containing the fields linked to the boundary (eventually pre-existing in the system if the exact same geometry of the input boundary got any time submitted as a representative boundary for a field). For each field:

    • "field_id": the ID of the field eventually linked to the boundary.

    • "effective_from": date since when the boundary is assigned to the field.

    • "effective_to": date until when the boundary is assigned to the field.

  • "permissions": returned in response only to the tenant(s) which have “manage“ permission on the boundary. It contains information about which tenants have which rights on the boundary.

Creation of custom shapes logic

When a client application sends a custom shape to GFID POST /boundaries endpoint:

• A boundary is created and a Global BoundaryID is assigned to it;

• A boundary reference is created and a UUID is assigned to it.

The boundary is deduplicated across all users who register the same shape, whereas a boundary reference represents the creator’s own view of the boundary (see Global FieldID identifiers for further explanation) and is linked to the boundary.

Except for the Varda-defined metadata (which become part of the boundary object), all the input properties will be stored in GFID system as part of the boundary reference, including permissions. For this reason, updating permissions on a boundary implies an update on the boundary reference and it is achievable by calling the PATCH /boundary-references/{id}/permissions endpoint. More info on the guideline page “Updating permissions of a boundary”.

If multiple users register features for the same area of land, the same BoundaryID will be returned. This means if there is already a boundary in the system with a geometry occupying exactly the same area of land as the input, no new boundary will be created and the boundary reference will be linked to the existing boundary.

Note that the union of permissions is used to determine access to a boundary: in other words, if in the above diagram a user has not been granted ‘view’ permission for reference A, but is subsequently granted access to reference X, the boundary will become visible. This does not reveal any unique information from boundary reference A.

Important considerations on the visibility of a field boundary

The POST /fields endpoint has a similar input payload to the POST /boundaries endpoint since, in effect, it registers both a field and a boundary at the same time. Given that the input payload to the POST /boundaries includes permissions, it becomes possible to specify permissions also when creating a field boundary.

However, it is important to note that a field boundary will always be visible to any user/client of the system regardless of the permissions specified at field creation because it is not permissible to create a common industry-wide FieldID, but hide its geometry. This means that more restrictive permissions will be applied only to the boundary reference (including the metadata properties within the payload) while the field boundary geometry will always be accessible by any tenant.

The same is valid when updating a field via the PATCH /fields/{id} endpoint. The permissions eventually provided as part of the boundary object in input payload will be restricted to the boundary reference while the field will always be visible to any tenant.