clarify use of GeoJSON geometry and properties.extent.spatial

[tomkralidis]

As discussed at the 2022-05-16 SWG, our current record model specifies the following properties for defining spatial.

• geometry (native from GeoJSON proper): can be any GeoJSON geometry, or null
• properties.extent.spatial: bbox

We should clarify the above in the cases where (in the least) the values are duplicate, yet required twice.

cc @pvretano @cportele

[pvretano]

I'm thinking of two approaches for handling this issues ...

First, we can add words to the specification that say:

• the geometry member stores the geometry of the resource; this can be its actual geometry or some other representation of the space the resource occupies for the purposes of discovery
• the extent member stores the extent of the geometry of the resource; these could infact be the same thing if a server chooses to use the bounding box as the representative geometry of the resource

The second approach uses JSON-FG rather than GeoJSON. Using JSON-FG gives us:

• A place to store the spatial extent (i.e. the geometry member)
• A place to store the temporal extent (i.e. the time member)
• Support for CRS other than CRS84 (should a server want to implement the CRS extension of Featrures)
• Support from 3-D geometries (that might be an emergin thing, I don't know)

This would mean that in the specification we:

• remove extents from the record
• add a requirement that say that JSON-FG must be generated using maximum compatability (to GeoJSON) mode so that GeoJSON clients can still read the record without any trouble
• Add words that say if additional extents are required then communities of interest can add them to the properties section

Thoughts?

[pvretano]

2022-05-30: With regard to JSON-FG, after a long discussion, the SWG decided to implement the following in the specification

• Remove the "extent" member from properties.
• Add a "time" member to properties with the same structure as the JSON-FG time.
• This will be added to the "GeoJSON" conformance class.
• There will be no JSON-FG conformance class for now but only a note indicating that the specification will add one at some future time when the JSON-FG specification is available.
• The "time" member in the GeoJSON conformance class will remain there, in that class, for all time!
• When the JSON-FG conformance class is added, it will using JSON-FG as designed and there will be a "time" member at the top level ... but this is a different thing than the "time" member in the GeoJSON conformance class.

[tomkralidis]

@pvretano: some comments, questions:

• I see a JSON-FG conformance class the latest updates to the repo. Is JSON-FG now available?

• for completeness, can we change time to datetime?

  • queries:
  • datetime is a parameter from OGC API Common
  • many OGC APIs already support the datetime parameter, per RFC3339
  • JSON Schema delineates date, time, date-time, for example
  • so do many programming languages
  • time COULD result in confusion (emitting JUST the time with no date?)

• can we add the following to the (currently named) time object:

  • trs, or is one assumed/implied (that we should qualify/document)
  • resolution, per #149

• I'm not sure if these are best routed / cc'd to JSON-FG as well

• we still have core/openapi/schemas/common/extent.yaml; guessing we should remove?

[pvretano]

@tomkralidis

1. JSON-FG - was added as a placeholder until after the code sprint but I don't think we will adding it to the specification in this version. Instead we will adopt some of the "features" of JSON-FG (i.e. the time object).
2. Nope. We took time from JSON-FG as a stepping stone to eventually fully supporting JSON-FG. If we want to change the name we need to convince the JSON-FG guys to change the name of their key to datatime first.
3. From JSON-FG, the trs is fixed to the Gregorial calendar so a trs member is not required.
4. Yes, any changes to the time object should be routed to the JSON-FG group. In records we are simply trying to align, in this respect, with what JSON-FG is doing so that at some point in the future we can add a JSON-FG conformance class and the transition will be as effortless as possible.
5. Yes, extent.yaml should be removed. I'll take care of that with my next PUSH to the repo.

[tomkralidis]

Nope. We took time from JSON-FG as a stepping stone to eventually fully supporting JSON-FG. If we want to change the name we need to convince the JSON-FG guys to change the name of their key to datatime first.

Good point. I've opened a related issue at https://github.com/opengeospatial/ogc-feat-geo-json/issues/56

[cnreediii]

Just a FYI: datetime in CDB is stated as a requirement:

Searchable date and time. This may be a time instance or time period. The specification of date and time in any CDB metadata SHALL be specified in UTC and SHALL be formatted according to RFC 3339, section 5.6. RFC 3339 is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.

Look familiar. However, the CDB SWG has also discussed how to deal with time intervals. The requirement for time intervals will be different as time sampling scales such as Unix time need to be accommodated.

[pvretano]

28-NOV-2022: It was agreed at the code sprint that JSON-FG is not, at this time, relevant to records. @pvretano will review the issue to make sure that all parts have been addressed and close.

[tomkralidis]

@pvretano it may be valuable to align the OARec record time to JSON-FG just the same. OARec currently defines time as either a string or an array (begin, end), whereas JSON-FG defines an object, which contains either a date, timestamp, or interval. The JSON-FG approach provides an easier time for (backend metadata repository) things like document indexers (i.e. it is easier to index time.date [string], and time.timestamp [string], and time.interval [array] than time, which can have multiple non-null types).

Thoughts?

[mariadb-pvretano]

@tomkralidis agreed. Our time field should align with JSON-FG. I'll make the necessary changes.

[pvretano]

07-APR-2023: time was added to the record some time ago so we can close this.

[tomkralidis]

Reopening. OGC API - Records time does not currently align with JSON-FG. Suggesting the following:

• align with JSON-FG time definition
• extend with resolution (related to discussion https://github.com/opengeospatial/ogc-feat-geo-json/issues/56) as per #147 / #149

[pvretano]

@tomkralidis I already have a PR that I am working on for STAC harmonization. I've already updated the time element to align with JSON-FG in that PR. I'll try to have that PR done before our working session next week.

[cnreediii]

Isn't this possibly a much broader OGC wide issue? Sure would be nice if each and every OGC standard now and going forward expressed time and date using the same rules!! And not necessarily entirely driven by STAC. STAC should be just one point of reference.

[pvretano]

@cnreediii on this particular point, driven by JSON-FG and not STAC. The original time member in Records was copied from JSON-FG. Over time JSON-FG changed its definition of it's time member so, in order to stay aligned, we need to update the definition in Records. I might just reference the JSON-FG schema for time but I'm not sure which standard (records of JSON-FG) will be adopted first ... so I'll have to think about whether to copy or reference.

[tomkralidis]

@tomkralidis I already have a PR that I am working on for STAC harmonization. I've already updated the time element to align with JSON-FG in that PR. I'll try to have that PR done before our working session next week.

Thanks @pvretano. Perhaps this is better handled outside the STAC harmonization, which is still under discussion?

[tomkralidis]

@cnreediii on this particular point, driven by JSON-FG and not STAC. The original time member in Records was copied from JSON-FG. Over time JSON-FG changed its definition of it's time member so, in order to stay aligned, we need to update the definition in Records. I might just reference the JSON-FG schema for time but I'm not sure which standard (records of JSON-FG) will be adopted first ... so I'll have to think about whether to copy or reference.

I would keep local in records for now (until JSON-FG is adopted) and add a resolution property (per https://github.com/opengeospatial/ogcapi-records/issues/168#issuecomment-1519065053)

[pvretano]

01-MAY-2023: @kalxas has a concern that the time property is at the top level and not in the properties section. The issue is that JSON-FG/Record are late to the game and most GeoJSON clients will not look for time at the top level but they will look for or handle a time member in the properties section. This is certainly the case for the OpenLayers library. At the top level time is hidden to OpenLayers but if it we in the properties section, OpenLayers would be able to handle it. This is likely true for many GeoJSON-capable clients. One proposal is to duplicate the information to maintain JSON-FG compatibility but still make the information available to existing GeoJSON clients ... not a great proposal though. So the question at hand is ... should be move time into the properties section?

If anyone is aware about how other GeoJSON clients (e.g. QGIS) handle members in the properties section (especially temporal members) please chime in. We are interested to know how temporal information would be handled if it were in the properties section.

We need feedback on this so please feel free to add comments here.

[cnreediii]

@pvretano My two cents. GeoJSON, OpenLayers etc can inform requirements in an OGC standard but should not be the endgame for an OGC Standard. Sure, Features has GeoJSON as the default output encoding . However, any output encoding could be defined and used (JSON-FG, GML, KML, even Shapefiles!) The need is to look at the larger standards (and multi-domain) picture and decide what is best overall. If this means that a change request needs to be submitted for GeoJSON, so be it.

[pvretano]

@cnreediii agreed. In Records we first looked at what "core" information we wanted to encode in the record (independent of the encoding) and then figured out how to map that info into the target encodings (i.e. GeoJSON and HTML). Of course, other encodings of the same information are possible but these are not not defined in the standard (although we were looking at a JSON-FG encoding at one point). As in features, if another encoding becomes popular, we would defined another part of the standard to cover that encoding. I should clarify is that neither Features nor Records have a default output encoding. There is no default. Rather clients and servers negotiate a mutually agreeable output format using standard HTTP content negotiation rules. We include GeoJSON and HTML encodings because we believe these are popular encodings but servers are not compelled to support either. One could, for example, implement a Records API that only uses csw:Record (from CSW 3.0) as its output format. One thing we are keenly aware of though is that in order to encourage uptake of these standards, it's important that they play nice with existing tools ... which is why Features and Records define optional GeoJSON and HTML encodings.

[pvretano]

15-MAY-2023: Closing since it seems the issue related to the specification itself have been resolved.

[pvretano]

Upon re-reading I think this is still an open issue. Just to summarize ...

The basic issue is whether top-level fields, such as time, added by Records should be moved into the properties section so that certain tools (like OpenLayers) have access to the information. This also applies to the conformsTo field as well.

JSON-FG has the same issue and I will try to sync up to thinking there with Records. The current thinking from @cportele with regard to JSON-FG is to add a recommendation that allows the information of top-level properties to be duplicated in the properties section so that tools like OpenLayers can access the information.

[pvretano]

29-MAY-2023: Same issue as discussed here: https://github.com/opengeospatial/ogcapi-records/pull/260#issuecomment-1567217961. There is friction between the desire to write the standard the way we think it should be (e.g. time is a top-level field or the organizing strcuture in OAPIR is called "Folder") and the desire to allow existing tooling to access implementations of the standard. No concensus was reached but the point was made that OGC should write the standard the way they think they should be written and then go out a actively update the open-source tooling the handle the spec. (e.g. update OpenLayers to read time from the top level or update the STAC browser to accept with "Catalog" or "Folder").

[pvretano]

07-AUG-2023: Records will follow the same approach as JSON-FG. We will keep time (for example) as a top level property since this is where we think it should be and then add a recommendation saying that is should be duplicated in properties if you think you have clients that may only access it from the properties section.