Skip to content

Extend list of format codes. #467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 5, 2025
Merged

Extend list of format codes. #467

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4e342d0
Extend list of format codes.
pvretano Oct 28, 2024
de7f3a9
Add more format values.
pvretano Nov 26, 2024
e39fce3
Add more format values.
pvretano Jan 5, 2025
f83adda
Fix typo.
pvretano Jan 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion core/sections/clause_8_ogc-process-description.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ include::../recommendations/ogc-process-description/REC_format-key.adoc[]

Processes that perform geo-spatial processing can be expected to have geometric and feature input types. In JSON, geometries, features and collections of feature are commonly encoded using https://datatracker.ietf.org/doc/html/rfc7946[GeoJSON]. Rather the requiring processes descriptions to embed or reference the full schemas for https://datatracker.ietf.org/doc/html/rfc7946[GeoJSON] geometries, features or feature collections, this Standard defines a common set of convenience tokens that can be used instead.

The <<jsonschemavalidation,JSON Schema specification>> defines a https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.7[set of values] for the `format` key. This Standard extends this list by defining the following additional key values for use specifically in OGC process descriptions for defining geometric, feature or feature collection inputs or outputs.
The <<jsonschemavalidation,JSON Schema specification>> defines a https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.7[set of values] for the `format` key. This Standard extends this list by defining the following additional key values for use specifically in OGC process descriptions.

[[format-key-values]]
.Additional values for the JSON schema format key for OGC Process Description
Expand All @@ -118,6 +118,14 @@ The <<jsonschemavalidation,JSON Schema specification>> defines a https://json-sc
|http://www.opengis.net/def/format/ogcapi-processes/0/geojson-feature |geojson-feature |Indicates that the object is an instance of a GeoJSON feature http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/featureGeoJSON.yaml[(featureGeoJSON.yaml)].
|http://www.opengis.net/def/format/ogcapi-processes/0/geojson-geometry |geojson-geometry |Indicates that the object is an instance of a GeoJSON geometry http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/geometryGeoJSON.yaml[(geometryGeoJSON.yaml)].
|http://www.opengis.net/def/format/ogcapi-processes/0/ogc-bbox |ogc-bbox |Indicates that the object is an instance of an OGC bounding box https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/bbox.yaml[(bbox.yaml)].
|http://www.opengis.net/def/format/ogcapi-processes/0/epgc-code |epsg-code |Indicates that the value is a code from the https://epsg.io/[EPSG registry].
Copy link
Contributor

@m-mohr m-mohr Nov 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo:

Suggested change
|http://www.opengis.net/def/format/ogcapi-processes/0/epgc-code |epsg-code |Indicates that the value is a code from the https://epsg.io/[EPSG registry].
|http://www.opengis.net/def/format/ogcapi-processes/0/epsg-code |epsg-code |Indicates that the value is a code from the https://epsg.io/[EPSG registry].

|http://www.opengis.net/def/format/ogcapi-processes/0/wkt2-def |wkt2-def |Indicates that the string value is a https://docs.ogc.org/is/18-010r11/18-010r11.pdf[well-known text representation of a coordinate reference system].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe wkt2-definition? Then it would be aligned with openEO.

Suggested change
|http://www.opengis.net/def/format/ogcapi-processes/0/wkt2-def |wkt2-def |Indicates that the string value is a https://docs.ogc.org/is/18-010r11/18-010r11.pdf[well-known text representation of a coordinate reference system].
|http://www.opengis.net/def/format/ogcapi-processes/0/wkt2-definition |wkt2-definition |Indicates that the string value is a https://docs.ogc.org/is/18-010r11/18-010r11.pdf[well-known text representation of a coordinate reference system].

|http://www.opengis.net/def/format/ogcapi-processes/0/cql2-text-filter |cql2-text |Indicates that the string value is a filter expression encoded using the text representation of the https://docs.ogc.org/is/21-065r2/21-065r2.html[Common Query Language (CQL2)].
|http://www.opengis.net/def/format/ogcapi-processes/0/cql2-json-filter |cql2-json |Indicates that the string value is a filter expression encoded using the JSON representation of the https://docs.ogc.org/is/21-065r2/21-065r2.html[Common Query Language (CQL2)].
|http://www.opengis.net/def/format/ogcapi-processes/0/collection-id |collection-id |Indicates that the string value is a https://docs.ogc.org/DRAFTS/20-024.html#collection-description[collection identifier] (e.g. a feature collection identifier).
|http://www.opengis.net/def/format/ogcapi-processes/0/stac-collection |stac-collection |Indicates that the string value is a https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md[STAC collection].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I got yet one more to propose while we are at it: stac-items
Just encountered that case earlier.

The idea being, that you can request the STAC Items themselves as application/geo+json.
Because STAC Items have nested media-types as Assets, doing a request with only type is ambiguous (is it the items or the assets they describe?)
ie:

some-input:
  collection: https://server.com/stac/api/v1/collection/something
  type: application/geo+json  # Should this be the Items FeatureCollection, or a Vector file found in Assets?
  format: stac-items  # specifically asking for the items, needed to disambiguate from OA Features
some-input:
  collection: https://server.com/stac/api/v1/collection/something
  type: image/tiff; application=geotiff; profile=cloud-optimized
  format: stac-collection  # STAC Assets matching the COG media-type
  # but why 'stac-collection'? -> properties to find them (therefore, not a OA Coverages)
  filter: properties.eo:cloud_cover > 0.5

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Relates to crim-ca/weaver#770

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In STAC thats named ItemCollection, so maybe use stac-itemcollection instead?

Copy link
Contributor

@m-mohr m-mohr Nov 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And what about a single item or a catalog? We discussed a longer list here:
#428

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we can align with OpenEO definitions if they actually mean the same.

I'm mostly trying to map with the results from pystac-client operations CollectionClient, CollectionSearch, and ItemSearch.

For the moment format: stac-collection would be the first, and stac-items (=> stac-itemcollection) would be the last (I think?). Is there other representations applicable in STAC?

What if the STAC Assets themselves should be provided, is there a stac-assetcollection or similar that is already defined?

Copy link
Contributor

@m-mohr m-mohr Nov 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's nothing to align to in STAC right now, I think. There's just different specifications which for all there could be a usecase to pass them to processes.

In openEO we just have a generic STAC type (i.e. item, collection, catalog). ItemCollection is missing, not sure whether that's intentional: Open-EO/openeo-processes#523 (but it's also a slightly different usecase, I think).

We discussed that already in another issue, which listed potential options, I think. Here's the list of options again:

  • stac -> The union of all of the types below, i.e. any STAC entity
  • stac-item -> STAC Item Spec (static or /collections/:id/items/:id)
  • stac-collection -> STAC Collection Spec (static or /collections/:id)
  • stac-catalog -> STAC Catalog spec (static or API landing page)
  • stac-itemcollections -> ItemCollection fragment in STAC API (/collections/:id/item or /search)
  • (stac-api -> a STAC API landing page, could potentially be captured by stac-catalog?)
  • (stac-collectioncollection -> What you get returned in /collections - but I don't have a usecase for this, so can be omitted)

Providing STAC assets on its own doesn't make a lot of sense to me as usually the assets depend on the STAC container, e.g. if an asset has a relativ link you need to get the self link. Also, STAC asset metadata inherits from the properties/top-level metadata since STAC 1.1. So I'd not define a separate stac-asset format. Better pass the asset key in addition to the STAC entity if you want to process a specific asset.

|http://www.opengis.net/def/format/ogcapi-processes/0/ogc-feature-collection |ogc-feature-collection |Indicates that the string value is an https://docs.ogc.org/is/17-069r4/17-069r4.html#_collection_[OGC feature collection].
|http://www.opengis.net/def/format/ogcapi-processes/0/ogc-coverage-collection |ogc-coverage-collection |Indicates that the string value is an https://docs.ogc.org/DRAFTS/19-087.html#_extended_collection_description_response_collectionscollectionid[OGC coverage collection].
|===

NOTE: This list of values has been submitted to the https://www.ogc.org/projects/groups/ogcnasc[OGC Naming Authority] for registration in their definition server.
Expand Down
Loading