Add optional GEOJson object to organization

[mbaudis]

Proposal: Add GEOJson object to organization

For many purposes the inclusion of a standardized geographic location object would be extremely helpful. A prime example here would be Beacon, obviously, but the use cases are widespread from documenting the usage of a federated service across the world to providing a map of collaborators in a distributed project or for filtering services according to their location.

As optional addition such an object would not break the current specification (version bump issues aside).

Format note: With increasing complexity inline object definitions should rather be moved to a definitions section or external files.

        organization:
          type: object
          description: 'Organization providing the service'
          required:
            - name
            - url
          properties:
            name: {}
            url: {}
            location:
              type: object
              description: >-
                Geographic location of the service, either representing the
                organization's head node or the location of the service, as an
                instance of a GeoJSON `feature`.
                **Provenance**: [IETF GeoJSON specification](https://tools.ietf.org/html/rfc7946)
              required:
                - type
                - geometry
                - properties
              properties:
                type:
                  const: Feature
                geometry:
                  description: >-
                    The geographic point object uses the default units from the
                    [DCMI point scheme](http://dublincore.org/documents/dcmi-point/)and avoids
                    optional representation in non-standard units.
                  type: object
                  required:
                    - type
                    - coordinates
                  properties:
                    type:
                      const: "Point"
                    coordinates:
                      description: >-
                        An array of 2 (longitude, latitude) or 3 (longitude, latitude, altitude)
                        ordered values.
                      type: array
                      items:
                        type: number
                        format: float
                      minItems: 2
                      maxItems: 3
                      examples:
                        - - 47.37
                          - 8.55
                        - - 86.925026
                          - 27.987850
                          - 8848.86
                properties:
                  description: >-
                    As an instance of the GeoJSON `properties` object. The parameters
                    provide additional information for the interpretation of the location.
                    Note: the GeoJSON standard does not provide specifications for
                    the content of its `properties` object.
                  type: object
                  required:
                    - label
                  properties:
                    label:
                      type: string
                      examples:
                        - Gainesville, 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.
                        It should be considered secondary to the location values
                        in interpreting the geographic location.
                    country:
                      type: string
                      description: >-
                        The optional name of the country the location maps to,
                        for checks and procedural convenience (see notes for `city`).
                      examples:
                        - Switzerland
                    ISO3166alpha3:
                      type: string
                      examples:
                        - USA
                        - CHE

Example:

location:
  type: Feature
  geometry:
    type: Point
    coordinates:
      - 47.37
      - 8.55
  properties:
    label: Winterthurerstrasse 190, Zurich, Switzerland
    city: Zurich
    country: Switzerland
    ISO3166alpha3: CHE

[andrewyatz]

Nothing too worrying about this. Interesting and if you think there's general applicability I can support the idea. Especially if it is optional. I did find the official JSONSchema for this but don't think there's a way to use it is there? It would be a minor bump.

What I'm not sure is how we publish these changes. Service-info is now a very central concept. Does this have sufficient visibility here?

I would point out when testing your coordinate payload I think they're the wrong way around i.e. this worked in geojson.io

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "label": "Winterthurerstrasse 190, Zurich, Switzerland",
        "city": "Zurich",
        "country": "Switzerland",
        "ISO3166alpha3": "CHE"
      },
      "geometry": {
        "coordinates": [
          8.547288974410833,
          47.39759348037788
        ],
        "type": "Point"
      },
      "id": 0
    }
  ]
}

[mbaudis]

@andrewyatz Yes, since the days of the Metadata Task Team I've thought that we need a geotagging standard one can reference, for provenance, services, admin ... And GEOjson is the obvious choice; however, one needs to create a version which defines a subset of it & adds some specifics (e.g. properties just says key|value so some things like label or city ... need to be provided.

I also think that a) service-info is one of the specs that would really benefit from a location (or geoLocation) parameter, and b) that an inline definition would be my second choice compared to a ga4gh.GeoLocation since it could find widespread use. In fact, we can reference one already since I'd provided one as a "community" example for SchemaBlocks.

So one could rewrite above as:

        organization:
          type: object
          description: 'Organization providing the service'
          required:
            - name
            - url
          properties:
            name: {}
            url: {}
            location:
              $ref: https://schemablocks.org/schema_files/json/Progenetix/GeoLocation.json

... where repo, address ... etc. could be re-engineered (TASC?!). Would be a good driver case.

I would point out when testing your coordinate payload I think they're the wrong way around i.e. this worked in geojson.io

Double ouch - this exemplifies nicely the one of the 2 problems w/ long, lat - they get swapped easily (by copying etc.), esp. since Google Maps for whatever reason uses the other order (google.maps.LatLng(47.398191, 8.548727)). So no, my office is not in Somalia... (The other problem w/ the geometry is "Null Island" from casting missing values to 0).

I did find the official JSONSchema for this

I'm actually not sure that this is kept up-to-date; I'd rather use a tailored instance (in the https://json-schema.org/draft/2020-12/schema version which has things like const) including some pre-defined properties (which are up for discussion).

Further thoughts?