Progenetix - GeoLocation

A GeoLocation object is a geographic location formatted as a GeoJSON feature. The format is compatible with RFC 7946, while currently limiting its scope to features of type "Point". Also, the schema defines some optional parameters compatible with the GeoJSON feature properties wrapper object.

Provenance: IETF GeoJSON specification

Examples could be:

  • an address, e.g. of a lab performing an analysis
  • provenance of an individual, obfuscated to a larger order administrative entity (Suffolk, U.K.)
  • a lat/long/alt position where an environmental sample was collected

Geolocation attributes were proposed as part of the original GA4GH Metadata Task Team schemas. The current GeoLocation object is being used by the Progenetix resource and its BeaconPlus implementation of the Beacon v2 protocol.

Schema (YAML version)
"$schema": https://json-schema.org/draft/2020-12/schema
"$id": https://progenetix.org/services/schemas/GeoLocation/v2025-08-26

title: GeoLocation

type: object

description: >-
  A GeoLocation object represents a geographic location formatted as a
  *GeoJSON feature*. The format is compatible with [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946),
  while (currently) imiting its scope to features of type "Point".
  Also, the schema defines some optional parameters compatible with the `GeoJSON
  Feature` `properties` wrapper object.
  Examples could be:  
  * an address, e.g. of a lab performing an analysis
  * provenance of an individual, obfuscated to a larger order administrative
    entity (Suffolk, U.K.)
  * a lat/long position where an environmental sample was collected
  * altitude/elevation MAY be included as an optional/third element.

properties:
  type:
    const: "Feature"
  geometry:
    $ref: "#/$defs/GeoGeometry"
  properties:
    $ref: "#/$defs/GeoLabels"

required:
  - type
  - geometry

additionalProperties: False

$defs:
  GeoGeometry:
    description: >
      The geographic point object uses the default units (but not the properties)
      from the [DCMI point scheme](https://www.dublincore.org/specifications/dublin-core/dcmi-point/)
      and avoids optional representation in non-standard units. It consists of an
      array with at least 2 ordered numbers for

      - longitude/Easting (decimal degrees)
      - latitude/Northing (decimal degrees)
      - optionally altitude/elevation (in meters above/below sea level)

      GeoJSON uses the World Geodetic System of 1984 with units of decimal degrees
      as described in [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946).

      In case of a conflict `GeoGeometry` takes precedence over `GeoLabels`.
    type: object
    properties:
      type:
        const: Point
      coordinates:
        description: >
          An array of 2 (longitude, latitude) or 3 (longitude, latitude, altitude) values.
        type: array
        items:
          type: number
          format: float
        minItems: 2
        maxItems: 3
        examples:
          - - 8.55
            - 47.37 
          - - 86.925026
            - 27.987850
            - 8848.86
    required:
      - type
      - coordinates
    additionalProperties: False

  GeoLabels:
    description: >-
      GeoLabels represent an instance of the GeoJSON `properties` object. The
      parameters provide additional information for the interpretation of the
      location parameters.

      In case of a conflict `GeoGeometry` takes precedence over `GeoLabels`.
    type: object
    properties:
      label:
        type: string
        examples:
          - Heidelberg, Germany
          - Gainesville, FL, United States of America
          - Zurich, Switzerland
          - Str Marasesti 5, 300077 Timisoara, Romania
      city:
        type: string
        description: >-
          The optional name of the city the point location maps to. While this
          is a commonly used for point locations, it should be considered
          secondary to the `geometry` values in interpreting the geographic location.
      country:
        type: string
        description: >-
          The optional name of the country the location maps to, for sanity
          checks and procedural convenience (see notes for "city").
        examples:
          - Switzerland
      ISO3166alpha3:
        description: >-
          The optional ISO 3166-1 alpha-3 code for the country the location maps to.     
        type: string
        examples:
          - USA
          - CHE
      ISO3166alpha2:
        description: >-
          The optional ISO 3166-1 alpha-2 code for the country the location maps to.     
        type: string
        examples:
          - US
          - CH
      ISO3166sub:
        type: string
        description: >-
          The optional ISO 3166-2 code for the principal subdivision (e.g.
          province or state) of the country the location maps to.
        examples:
          - US-WA
          - CH-ZH
      precision:
        type: string
        description: >
          Used together with coordinate annotation, precision represents an
          optional label describing the precision that can be inferred from the
          coordinates. For a precision level of "city", coordinates would have
          to be interpreted as representing any possible location within the
          city's administrative boundaries, not necessarily at the exact
          position of the point coordinates.
          The `precision` parameter can be used to indicate an obfuscation of
          the coordinates, e.g. for privacy protection.
        examples:
          - city

    additionalProperties: True

{S}[B] Contributors

Last updated 2025-08-26 by @mbaudis