Global FieldID Identifiers

This guide explains the different types of identifier used in the Global FieldID system, and how to represent them in your applications.

There are multiple types of identifier in the Global FieldID system:

  • Fields
  • Boundaries
  • Boundary References

In addition, third party cross-references have their own identifiers.

Field Identifiers

A Global FieldID is designed to be easy to capture and communicate in both digital and non-digital formats without mistakes. Here is an example:

15RJ.CZM7

The system generates identifiers using a subset of the ASCII character set, with some important characteristics:

  • IDs are always unique
  • Only capital letters, numbers and a period separator are used, eliminating case sensitivity issues
  • Letters that can be confused with numbers (I and O) are never included
  • The ID will always contain at least one letter, to ensure it cannot be confused for a decimal number
  • Use of vowels is controlled in such a way that the chance an ID can spell a word is limited
  • The word-only character set means a double-clicks selects the whole ID
  • A checksum is included to limit transcription errors

The validity of a field ID can always be checked by resolving it using the GET /fields/{id} API endpoint.

The period character is included for visual separation, its position is not important. In other words, a FieldID with a period omitted or in a different position won’t change the result of the identification or make it invalid.

Visual representation

Although it doesn't affect the identity of the field per se, the period character should be included whenever displaying the FieldID, to provide visual separation that makes it easier to transcribe or read out over the telephone without mistakes.

The ID should always be labelled as a Global FieldID. For example:

Field name: Hill Field

Global FieldID: 15RJ.CZM7

When presented in limited space, the 'GFID tag' may be used instead of a label:

/\ 15RJ.CZM7

The tag may rendered as a character string. T /\ (slash and backslash, ASCII /\). Where feasible it should be colored (RGB 149,211,0, HTML #95D300). Care should be taken to visually separate the tag prefix from the ID itself to avoid end users accidentally concluding that the tag is part of the ID.

Prefixing

Some protocols use prefixed identifiers to distinguish identifiers of different schemes, for example the CURIE syntax, or IRI prefixes used in JSON-LD. In such cases We recommend using GFID as the prefix, i.e.:

GFID:15RJ.CZM7

Web URLs

You can create a link to resolve a Global FieldID in our web application like this:

https://fieldid.varda.ag/fields/15RJ.CZM7

This is also the URL our web application uses for generating a QR code.

Boundary Identifiers

In the Global FieldID system, boundaries are deduplicated spatial objects. Each boundary ID uniquely identifies a specific area on Earth: a common identifier for spatial features from any source with the same geometry. In other words, references to the same boundary ID always refer to the same geometry, and references to different boundary IDs are always referring to different areas of land, even if only slightly differing in the number of vertices, presence of holes etc - if the resulting spatial footprint of is different, it will be assigned a novel boundary ID.

Whenever a boundary is registered in the Global FieldID system, it is always assigned the same boundary ID no matter which source it came from or any other metadata attached to it. This is accomplished by correcting and normalizing the boundary geometry and checking for matches with existing geometries.

Unlike a field, a boundary is considered a technical concept, so its identifier is intended for use in machine-to-machine communications. A Global BoundaryID is a UUID:

2bbc9443-7b65-4a9c-806b-78d20298ab4b

UUIDs are commonly used in data exchange protocols such as ISO 11783 and the ADAPT framework, as well as being well-supported in database engines for optimised index performance.

Note: A BoundaryID is not intended for human display or recognition; different boundaries should be presented either spatially or using their associated metadata in order to distinguish them.

Boundary References

Part of the GFID service's functionality is to deduplicate multiple instances of the same concepts from different systems, and give them a common (shared) BoundaryID. However, each system typically has its own internal name or identifier for a field or boundary. Whilst we provide a Global BoundaryID that is common to all instances of the same geometry (see above), we also retain each individual 'reference' to the boundary, enabling client applications to translate between them.

When each system registers a boundary GeoJSON Feature (a feature comprising geometry and metadata), we retain it as a boundary reference. If the source includes its own identifier, we include it as a user_provided_key property, and clients can use it as a key to query the API. This allows a 3rd party identifier to be resolved to its canonical Global BoundaryID, and vice versa.

However, IDs provided by the source cannot be guaranteed to be unique across or even within sources (e.g. it is common to reuse the same ID for a feature with the same or similar geometry, but different metadata). Therefore a boundary reference is assigned a globally unique primary identifier, which is a UUID.

In summary:

  • The ID of a boundary is a Global BoundaryID (a UUID)
  • A boundary has one or more boundary references linked to it
  • The ID of boundary reference is a UUID
  • A boundary reference has a source, and may have a 'user provided key' (any string)